feat: [chat] Add doc for Discoverable Space support for GA launch (#5525

)

* feat: Add doc for Discoverable Space support for GA launch
docs: Update resource naming formats

PiperOrigin-RevId: 649131985

Source-Link: googleapis/googleapis@fd67cac

Source-Link: googleapis/googleapis-gen@7c31c51
Copy-Tag: eyJwIjoicGFja2FnZXMvZ29vZ2xlLWNoYXQvLk93bEJvdC55YW1sIiwiaCI6IjdjMzFjNTFjZTU3YTRiM2JmOGFhMTFiZGU1YzE1NDRhZTY4OTg3M2MifQ==

* 🦉 Updates from OwlBot post-processor

See https://github.com/googleapis/repo-automation-bots/blob/main/packages/owl-bot/README.md

---------

Co-authored-by: Owl Bot <gcf-owl-bot[bot]@users.noreply.github.com>
Co-authored-by: sofisl <[email protected]>

packages/google-chat/protos/google/chat/v1/attachment.proto

@@ -48,7 +48,7 @@ message Attachment {
   }
 
   // Resource name of the attachment, in the form
-  // `spaces/*/messages/*/attachments/*`.
+  // `spaces/{space}/messages/{message}/attachments/{attachment}`.
   string name = 1;
 
   // Output only. The original file name for the content, not the full path.
@@ -103,7 +103,7 @@ message AttachmentDataRef {
 // Request to get an attachment.
 message GetAttachmentRequest {
   // Required. Resource name of the attachment, in the form
-  // `spaces/*/messages/*/attachments/*`.
+  // `spaces/{space}/messages/{message}/attachments/{attachment}`.
   string name = 1 [
     (google.api.field_behavior) = REQUIRED,
     (google.api.resource_reference) = { type: "chat.googleapis.com/Attachment" }

packages/google-chat/protos/google/chat/v1/chat_service.proto

@@ -42,6 +42,11 @@ option ruby_package = "Google::Apps::Chat::V1";
 service ChatService {
   option (google.api.default_host) = "chat.googleapis.com";
   option (google.api.oauth_scopes) =
+      "https://www.googleapis.com/auth/chat.admin.delete,"
+      "https://www.googleapis.com/auth/chat.admin.memberships,"
+      "https://www.googleapis.com/auth/chat.admin.memberships.readonly,"
+      "https://www.googleapis.com/auth/chat.admin.spaces,"
+      "https://www.googleapis.com/auth/chat.admin.spaces.readonly,"
       "https://www.googleapis.com/auth/chat.bot,"
       "https://www.googleapis.com/auth/chat.delete,"
       "https://www.googleapis.com/auth/chat.import,"
@@ -253,6 +258,9 @@ service ChatService {
   // Lists spaces visible to the caller or authenticated user. Group chats
   // and DMs aren't listed until the first message is sent.
   //
+  // To list all named spaces by Google Workspace organization, use the
+  // [`spaces.search()`](https://developers.google.com/workspace/chat/api/reference/rest/v1/spaces/search)
+  // method using Workspace administrator privileges instead.
   rpc ListSpaces(ListSpacesRequest) returns (ListSpacesResponse) {
     option (google.api.http) = {
       get: "/v1/spaces"

packages/google-chat/protos/google/chat/v1/membership.proto

@@ -215,16 +215,23 @@ 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`.
+  // 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 both role and type, use the `AND` operator. To filter by
   // either role or type, use the `OR` operator.
   //
+  // Either `member.type = "HUMAN"` or `member.type != "BOT"` is required
+  // when `use_admin_access` is set to true. Other member type filters will be
+  // rejected.
+  //
   // For example, the following queries are valid:
   //
   // ```
   // role = "ROLE_MANAGER" OR role = "ROLE_MEMBER"
   // member.type = "HUMAN" AND role = "ROLE_MANAGER"
+  //
+  // member.type != "BOT"
   // ```
   //
   // The following queries are invalid:
@@ -234,7 +241,6 @@ message ListMembershipsRequest {
   // role = "ROLE_MANAGER" AND role = "ROLE_MEMBER"
   // ```
   //
-  //
   // Invalid queries are rejected by the server with an `INVALID_ARGUMENT`
   // error.
   string filter = 5 [(google.api.field_behavior) = OPTIONAL];

packages/google-chat/protos/google/chat/v1/space.proto

@@ -103,6 +103,39 @@ message Space {
     string guidelines = 2;
   }
 
+  // Represents the [access
+  // setting](https://support.google.com/chat/answer/11971020) of the space.
+  message AccessSettings {
+    // Represents the access state of the space.
+    enum AccessState {
+      // Access state is unknown or not supported in this API.
+      ACCESS_STATE_UNSPECIFIED = 0;
+
+      // Space is discoverable by added or invited members or groups.
+      PRIVATE = 1;
+
+      // Space is discoverable by the selected [target
+      // audience](https://support.google.com/a/answer/9934697), as well as
+      // added or invited members or groups.
+      DISCOVERABLE = 2;
+    }
+
+    // Output only. Indicates the access state of the space.
+    AccessState access_state = 1 [(google.api.field_behavior) = OUTPUT_ONLY];
+
+    // Optional. The resource name of the [target
+    // audience](https://support.google.com/a/answer/9934697) who can discover
+    // the space, join the space, and preview the messages in the space. For
+    // details, see [Make a space discoverable to a target
+    // audience](https://developers.google.com/workspace/chat/space-target-audience).
+    //
+    // Format: `audiences/{audience}`
+    //
+    // To use the default target audience for the Google Workspace organization,
+    // set to `audiences/default`.
+    string audience = 3 [(google.api.field_behavior) = OPTIONAL];
+  }
+
   // Resource name of the space.
   //
   // Format: `spaces/{space}`
@@ -192,6 +225,14 @@ message Space {
   //
   // To support admin install, your Chat app must feature direct messaging.
   bool admin_installed = 19 [(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`.
+  AccessSettings access_settings = 23 [(google.api.field_behavior) = OPTIONAL];
+
+  // Output only. The URI for a user to access the space.
+  string space_uri = 25 [(google.api.field_behavior) = OUTPUT_ONLY];
 }
 
 // A request to create a named space.
@@ -270,7 +311,7 @@ message ListSpacesResponse {
 
 // A request to return a single space.
 message GetSpaceRequest {
-  // Required. Resource name of the space, in the form "spaces/*".
+  // Required. Resource name of the space, in the form `spaces/{space}`.
   //
   // Format: `spaces/{space}`
   string name = 1 [
@@ -325,6 +366,7 @@ message UpdateSpaceRequest {
   // the display name is optional if the existing space already has the `SPACE`
   // type. Trying to update the space type in other ways results in an invalid
   // argument error).
+  // `space_type` is not supported with admin access.
   //
   // - `space_details`
   //
@@ -333,12 +375,27 @@ message UpdateSpaceRequest {
   // allows users to change their history
   // setting](https://support.google.com/a/answer/7664184).
   // Warning: mutually exclusive with all other field paths.)
+  // `space_history_state` is not supported with admin access.
+  //
+  // - `access_settings.audience` (Supports changing the [access
+  // setting](https://support.google.com/chat/answer/11971020) of who can
+  // discover the space, join the space, and preview the messages in space. If
+  // no audience is specified in the access setting, the space's access setting
+  // is updated to private. Warning: mutually exclusive with all other field
+  // paths.)
+  // `access_settings.audience` is not supported with admin access.
   //
-  // - Developer Preview: `access_settings.audience` (Supports changing the
-  // [access setting](https://support.google.com/chat/answer/11971020) of a
-  // space. If no audience is specified in the access setting, the space's
-  // access setting is updated to restricted. Warning: mutually exclusive with
-  // all other field paths.)
+  // - Developer Preview: Supports changing the [permission
+  // settings](https://support.google.com/chat/answer/13340792) of a space,
+  // supported field paths
+  // include: `permission_settings.manage_members_and_groups`,
+  // `permission_settings.modify_space_details`,
+  // `permission_settings.toggle_history`,
+  // `permission_settings.use_at_mention_all`,
+  // `permission_settings.manage_apps`, `permission_settings.manage_webhooks`,
+  // `permission_settings.reply_messages`
+  //  (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;
 }