feat: If you're a domain administrator or a delegated administrator, you can now include the useAdminAccess parameter when you call the Chat API with your administrator privileges with the following methods to manage Chat spaces and memberships in your Workspace organization:

Google APIs · copybara-github · commit c5bc296a6d5e · 2024-09-12T10:06:19.000-07:00
- SearchSpaces
- DeleteSpace
- UpdateSpace
- GetSpace
- ListMemberships
- DeleteMembership
- CreateMembership
- UpdateMembership
- GetMembership

Additionally, `last_active_time` and `membership_count` parameters are added to the `Space` resource.

docs: A comment for field `filter` in message `.google.chat.v1.ListMembershipsRequest` is updated to support `!=` operator
PiperOrigin-RevId: 673895888
diff --git a/google/chat/v1/chat_grpc_service_config.json b/google/chat/v1/chat_grpc_service_config.json
@@ -12,6 +12,7 @@
       { "service": "google.chat.v1.ChatService", "method": "GetSpace" },
       { "service": "google.chat.v1.ChatService", "method": "ListSpaces" },
       { "service": "google.chat.v1.ChatService", "method": "DeleteSpace" },
+      { "service": "google.chat.v1.ChatService", "method": "SearchSpaces" },
       { "service": "google.chat.v1.ChatService", "method": "CreateMembership" },
       { "service": "google.chat.v1.ChatService", "method": "GetMembership" },
       { "service": "google.chat.v1.ChatService", "method": "ListMemberships" },
diff --git a/google/chat/v1/chat_service.proto b/google/chat/v1/chat_service.proto
@@ -269,6 +269,18 @@ service ChatService {
     option (google.api.method_signature) = "";
   }
 
+  // Returns a list of spaces in a Google Workspace organization based on an
+  // administrator's search. Requires [user
+  // authentication with administrator
+  // privileges](https://developers.google.com/workspace/chat/authenticate-authorize-chat-user#admin-privileges).
+  // In the request, set `use_admin_access` to `true`.
+  rpc SearchSpaces(SearchSpacesRequest) returns (SearchSpacesResponse) {
+    option (google.api.http) = {
+      get: "/v1/spaces:search"
+    };
+    option (google.api.method_signature) = "";
+  }
+
   // Returns details about a space. For an example, see
   // [Get details about a
   // space](https://developers.google.com/workspace/chat/get-spaces).
diff --git a/google/chat/v1/chat_v1.yaml b/google/chat/v1/chat_v1.yaml
@@ -162,6 +162,11 @@ authentication:
         https://www.googleapis.com/auth/chat.bot,
         https://www.googleapis.com/auth/chat.spaces,
         https://www.googleapis.com/auth/chat.spaces.readonly
+  - selector: google.chat.v1.ChatService.SearchSpaces
+    oauth:
+      canonical_scopes: |-
+        https://www.googleapis.com/auth/chat.admin.spaces,
+        https://www.googleapis.com/auth/chat.admin.spaces.readonly
   - selector: google.chat.v1.ChatService.SetUpSpace
     oauth:
       canonical_scopes: |-
diff --git a/google/chat/v1/membership.proto b/google/chat/v1/membership.proto
@@ -156,6 +156,21 @@ message CreateMembershipRequest {
   // membership relation for itself, it must use the `chat.memberships.app`
   // scope, set `user.type` to `BOT`, and set `user.name` to `users/app`.
   Membership membership = 2 [(google.api.field_behavior) = REQUIRED];
+
+  // When `true`, the method runs using the user's Google Workspace
+  // administrator privileges.
+  //
+  // The calling user must be a Google Workspace administrator with the
+  // [manage chat and spaces conversations
+  // privilege](https://support.google.com/a/answer/13369245).
+  //
+  // Requires the `chat.admin.memberships` [OAuth 2.0
+  // scope](https://developers.google.com/workspace/chat/authenticate-authorize#chat-api-scopes).
+  //
+  // Creating app memberships or creating memberships for users outside the
+  // administrator's Google Workspace organization isn't supported using admin
+  // access.
+  bool use_admin_access = 5;
 }
 
 // Request message for updating a membership.
@@ -172,6 +187,17 @@ message UpdateMembershipRequest {
   // - `role`
   google.protobuf.FieldMask update_mask = 2
       [(google.api.field_behavior) = REQUIRED];
+
+  // When `true`, the method runs using the user's Google Workspace
+  // administrator privileges.
+  //
+  // The calling user must be a Google Workspace administrator with the
+  // [manage chat and spaces conversations
+  // privilege](https://support.google.com/a/answer/13369245).
+  //
+  // Requires the `chat.admin.memberships` [OAuth 2.0
+  // scope](https://developers.google.com/workspace/chat/authenticate-authorize#chat-api-scopes).
+  bool use_admin_access = 3;
 }
 
 // Request message for listing memberships.
@@ -215,8 +241,8 @@ message ListMembershipsRequest {
   //
   // To filter by role, set `role` to `ROLE_MEMBER` or `ROLE_MANAGER`.
   //
-  // To filter by type, set `member.type` to `HUMAN` or `BOT`. Developer
-  // Preview: You can also filter for `member.type` using the `!=` operator.
+  // To filter by type, set `member.type` to `HUMAN` or `BOT`. You can also
+  // filter for `member.type` using the `!=` operator.
   //
   // To filter by both role and type, use the `AND` operator. To filter by
   // either role or type, use the `OR` operator.
@@ -263,6 +289,20 @@ message ListMembershipsRequest {
   // Currently requires [user
   // authentication](https://developers.google.com/workspace/chat/authenticate-authorize-chat-user).
   bool show_invited = 7 [(google.api.field_behavior) = OPTIONAL];
+
+  // When `true`, the method runs using the user's Google Workspace
+  // administrator privileges.
+  //
+  // The calling user must be a Google Workspace administrator with the
+  // [manage chat and spaces conversations
+  // privilege](https://support.google.com/a/answer/13369245).
+  //
+  // Requires either the `chat.admin.memberships.readonly` or
+  // `chat.admin.memberships` [OAuth 2.0
+  // scope](https://developers.google.com/workspace/chat/authenticate-authorize#chat-api-scopes).
+  //
+  // Listing app memberships in a space isn't supported when using admin access.
+  bool use_admin_access = 8;
 }
 
 // Response to list memberships of the space.
@@ -295,6 +335,20 @@ message GetMembershipRequest {
     (google.api.field_behavior) = REQUIRED,
     (google.api.resource_reference) = { type: "chat.googleapis.com/Membership" }
   ];
+
+  // When `true`, the method runs using the user's Google Workspace
+  // administrator privileges.
+  //
+  // The calling user must be a Google Workspace administrator with the
+  // [manage chat and spaces conversations
+  // privilege](https://support.google.com/a/answer/13369245).
+  //
+  // Requires the `chat.admin.memberships` or `chat.admin.memberships.readonly`
+  // [OAuth 2.0
+  // scopes](https://developers.google.com/workspace/chat/authenticate-authorize#chat-api-scopes).
+  //
+  // Getting app memberships in a space isn't supported when using admin access.
+  bool use_admin_access = 3;
 }
 
 // Request to delete a membership in a space.
@@ -317,4 +371,17 @@ message DeleteMembershipRequest {
     (google.api.field_behavior) = REQUIRED,
     (google.api.resource_reference) = { type: "chat.googleapis.com/Membership" }
   ];
+
+  // When `true`, the method runs using the user's Google Workspace
+  // administrator privileges.
+  //
+  // The calling user must be a Google Workspace administrator with the
+  // [manage chat and spaces conversations
+  // privilege](https://support.google.com/a/answer/13369245).
+  //
+  // Requires the `chat.admin.memberships` [OAuth 2.0
+  // scope](https://developers.google.com/workspace/chat/authenticate-authorize#chat-api-scopes).
+  //
+  // Deleting app memberships in a space isn't supported using admin access.
+  bool use_admin_access = 2;
 }
diff --git a/google/chat/v1/space.proto b/google/chat/v1/space.proto
@@ -103,6 +103,16 @@ message Space {
     string guidelines = 2;
   }
 
+  // Represents the count of memberships of a space, grouped into categories.
+  message MembershipCount {
+    // Count of human users that have directly joined the space, not counting
+    // users joined by having membership in a joined group.
+    int32 joined_direct_human_user_count = 4;
+
+    // Count of all groups that have directly joined the space.
+    int32 joined_group_count = 5;
+  }
+
   // Represents the [access
   // setting](https://support.google.com/chat/answer/11971020) of the space.
   message AccessSettings {
@@ -218,6 +228,10 @@ message Space {
     (google.api.field_behavior) = OPTIONAL
   ];
 
+  // Output only. Timestamp of the last message in the space.
+  google.protobuf.Timestamp last_active_time = 18
+      [(google.api.field_behavior) = OUTPUT_ONLY];
+
   // Output only. For direct message (DM) spaces with a Chat app, whether the
   // space was created by a Google Workspace administrator. Administrators can
   // install and set up a direct message with a Chat app on behalf of users in
@@ -226,6 +240,12 @@ message Space {
   // To support admin install, your Chat app must feature direct messaging.
   bool admin_installed = 19 [(google.api.field_behavior) = OUTPUT_ONLY];
 
+  // Output only. The count of joined memberships grouped by member type.
+  // Populated when the `space_type` is `SPACE`, `DIRECT_MESSAGE` or
+  // `GROUP_CHAT`.
+  MembershipCount membership_count = 20
+      [(google.api.field_behavior) = OUTPUT_ONLY];
+
   // Optional. Specifies the [access
   // setting](https://support.google.com/chat/answer/11971020) of the space.
   // Only populated when the `space_type` is `SPACE`.
@@ -318,6 +338,17 @@ message GetSpaceRequest {
     (google.api.field_behavior) = REQUIRED,
     (google.api.resource_reference) = { type: "chat.googleapis.com/Space" }
   ];
+
+  // When `true`, the method runs using the user's Google Workspace
+  // administrator privileges.
+  //
+  // The calling user must be a Google Workspace administrator with the
+  // [manage chat and spaces conversations
+  // privilege](https://support.google.com/a/answer/13369245).
+  //
+  // Requires the `chat.admin.spaces` or `chat.admin.spaces.readonly` [OAuth 2.0
+  // scopes](https://developers.google.com/workspace/chat/authenticate-authorize#chat-api-scopes).
+  bool use_admin_access = 2;
 }
 
 // A request to get direct message space based on the user resource.
@@ -397,6 +428,165 @@ message UpdateSpaceRequest {
   //  (Warning: mutually exclusive with all other non-permission settings field
   // paths). `permission_settings` is not supported with admin access.
   google.protobuf.FieldMask update_mask = 2;
+
+  // When `true`, the method runs using the user's Google Workspace
+  // administrator privileges.
+  //
+  // The calling user must be a Google Workspace administrator with the
+  // [manage chat and spaces conversations
+  // privilege](https://support.google.com/a/answer/13369245).
+  //
+  // Requires the `chat.admin.spaces` [OAuth 2.0
+  // scope](https://developers.google.com/workspace/chat/authenticate-authorize#chat-api-scopes).
+  //
+  // Some `FieldMask` values are not supported using admin access. For details,
+  // see the description of `update_mask`.
+  bool use_admin_access = 3;
+}
+
+// Request to search for a list of spaces based on a query.
+message SearchSpacesRequest {
+  // When `true`, the method runs using the user's Google Workspace
+  // administrator privileges.
+  //
+  // The calling user must be a Google Workspace administrator with the
+  // [manage chat and spaces conversations
+  // privilege](https://support.google.com/a/answer/13369245).
+  //
+  // Requires either the `chat.admin.spaces.readonly` or `chat.admin.spaces`
+  // [OAuth 2.0
+  // scope](https://developers.google.com/workspace/chat/authenticate-authorize#chat-api-scopes).
+  //
+  // This method currently only supports admin access, thus only `true` is
+  // accepted for this field.
+  bool use_admin_access = 1;
+
+  // The maximum number of spaces to return. The service may return fewer than
+  // this value.
+  //
+  // If unspecified, at most 100 spaces are returned.
+  //
+  // The maximum value is 1000. If you use a value more than 1000, it's
+  // automatically changed to 1000.
+  int32 page_size = 2;
+
+  // A token, received from the previous search spaces call. Provide this
+  // parameter to retrieve the subsequent page.
+  //
+  // When paginating, all other parameters provided should match the call that
+  // provided the page token. Passing different values to the other parameters
+  // might lead to unexpected results.
+  string page_token = 3;
+
+  // Required. A search query.
+  //
+  // You can search by using the following parameters:
+  //
+  // - `create_time`
+  // - `customer`
+  // - `display_name`
+  // - `external_user_allowed`
+  // - `last_active_time`
+  // - `space_history_state`
+  // - `space_type`
+  //
+  // `create_time` and `last_active_time` accept a timestamp in
+  // [RFC-3339](https://www.rfc-editor.org/rfc/rfc3339) format and the supported
+  // comparison operators are: `=`, `<`, `>`, `<=`, `>=`.
+  //
+  // `customer` is required and is used to indicate which customer
+  // to fetch spaces from. `customers/my_customer` is the only supported value.
+  //
+  // `display_name` only accepts the `HAS` (`:`) operator. The text to
+  // match is first tokenized into tokens and each token is prefix-matched
+  // case-insensitively and independently as a substring anywhere in the space's
+  // `display_name`. For example, `Fun Eve` matches `Fun event` or `The
+  // evening was fun`, but not `notFun event` or `even`.
+  //
+  // `external_user_allowed` accepts either `true` or `false`.
+  //
+  // `space_history_state` only accepts values from the [`historyState`]
+  // (https://developers.google.com/workspace/chat/api/reference/rest/v1/spaces#Space.HistoryState)
+  // field of a `space` resource.
+  //
+  // `space_type` is required and the only valid value is `SPACE`.
+  //
+  // Across different fields, only `AND` operators are supported. A valid
+  // example is `space_type = "SPACE" AND display_name:"Hello"` and an invalid
+  // example is `space_type = "SPACE" OR display_name:"Hello"`.
+  //
+  // Among the same field,
+  // `space_type` doesn't support `AND` or `OR` operators.
+  // `display_name`, 'space_history_state', and 'external_user_allowed' only
+  // support `OR` operators.
+  // `last_active_time` and `create_time` support both `AND` and `OR` operators.
+  // `AND` can only be used to represent an interval, such as `last_active_time
+  // < "2022-01-01T00:00:00+00:00" AND last_active_time >
+  // "2023-01-01T00:00:00+00:00"`.
+  //
+  // The following example queries are valid:
+  //
+  // ```
+  // customer = "customers/my_customer" AND space_type = "SPACE"
+  //
+  // customer = "customers/my_customer" AND space_type = "SPACE" AND
+  // display_name:"Hello World"
+  //
+  // customer = "customers/my_customer" AND space_type = "SPACE" AND
+  // (last_active_time < "2020-01-01T00:00:00+00:00" OR last_active_time >
+  // "2022-01-01T00:00:00+00:00")
+  //
+  // customer = "customers/my_customer" AND space_type = "SPACE" AND
+  // (display_name:"Hello World" OR display_name:"Fun event") AND
+  // (last_active_time > "2020-01-01T00:00:00+00:00" AND last_active_time <
+  // "2022-01-01T00:00:00+00:00")
+  //
+  // customer = "customers/my_customer" AND space_type = "SPACE" AND
+  // (create_time > "2019-01-01T00:00:00+00:00" AND create_time <
+  // "2020-01-01T00:00:00+00:00") AND (external_user_allowed = "true") AND
+  // (space_history_state = "HISTORY_ON" OR space_history_state = "HISTORY_OFF")
+  // ```
+  string query = 4 [(google.api.field_behavior) = REQUIRED];
+
+  // Optional. How the list of spaces is ordered.
+  //
+  // Supported attributes to order by are:
+  //
+  // - `membership_count.joined_direct_human_user_count` — Denotes the count of
+  // human users that have directly joined a space.
+  // - `last_active_time` — Denotes the time when last eligible item is added to
+  // any topic of this space.
+  // - `create_time` — Denotes the time of the space creation.
+  //
+  // Valid ordering operation values are:
+  //
+  // - `ASC` for ascending. Default value.
+  //
+  // - `DESC` for descending.
+  //
+  // The supported syntax are:
+  //
+  // - `membership_count.joined_direct_human_user_count DESC`
+  // - `membership_count.joined_direct_human_user_count ASC`
+  // - `last_active_time DESC`
+  // - `last_active_time ASC`
+  // - `create_time DESC`
+  // - `create_time ASC`
+  string order_by = 5 [(google.api.field_behavior) = OPTIONAL];
+}
+
+// Response with a list of spaces corresponding to the search spaces request.
+message SearchSpacesResponse {
+  // A page of the requested spaces.
+  repeated Space spaces = 1;
+
+  // A token that can be used to retrieve the next page. If this field is empty,
+  // there are no subsequent pages.
+  string next_page_token = 2;
+
+  // The total number of spaces that match the query, across all pages. If the
+  // result is over 10,000 spaces, this value is an estimate.
+  int32 total_size = 3;
 }
 
 // Request for deleting a space.
@@ -408,6 +598,17 @@ message DeleteSpaceRequest {
     (google.api.field_behavior) = REQUIRED,
     (google.api.resource_reference) = { type: "chat.googleapis.com/Space" }
   ];
+
+  // When `true`, the method runs using the user's Google Workspace
+  // administrator privileges.
+  //
+  // The calling user must be a Google Workspace administrator with the
+  // [manage chat and spaces conversations
+  // privilege](https://support.google.com/a/answer/13369245).
+  //
+  // Requires the `chat.admin.delete` [OAuth 2.0
+  // scope](https://developers.google.com/workspace/chat/authenticate-authorize#chat-api-scopes).
+  bool use_admin_access = 2;
 }
 
 // Request message for completing the import process for a space.
