From f66440dec8cab0a11e53dd9e3e165b85f9651f38 Mon Sep 17 00:00:00 2001 From: "gcf-owl-bot[bot]" <78513119+gcf-owl-bot[bot]@users.noreply.github.com> Date: Tue, 14 May 2024 07:26:36 -0400 Subject: [PATCH] docs: [google-apps-chat] update Chat API comments (#12694) - [ ] Regenerate this pull request now. PiperOrigin-RevId: 633320855 Source-Link: https://github.com/googleapis/googleapis/commit/6cac6e4f2b8f7c30a50cdd796e635e72426f478b Source-Link: https://github.com/googleapis/googleapis-gen/commit/d5f80f506dd3b7297c5f92bc2dc792a11b7fb387 Copy-Tag: eyJwIjoicGFja2FnZXMvZ29vZ2xlLWFwcHMtY2hhdC8uT3dsQm90LnlhbWwiLCJoIjoiZDVmODBmNTA2ZGQzYjcyOTdjNWY5MmJjMmRjNzkyYTExYjdmYjM4NyJ9 --------- Co-authored-by: Owl Bot Co-authored-by: Anthonios Partheniou --- .../services/chat_service/async_client.py | 52 ++++++++++++------- .../chat_v1/services/chat_service/client.py | 52 ++++++++++++------- .../services/chat_service/transports/grpc.py | 45 ++++++++++------ .../chat_service/transports/grpc_asyncio.py | 45 ++++++++++------ .../google/apps/chat_v1/types/membership.py | 5 +- .../google/apps/chat_v1/types/reaction.py | 3 +- .../google/apps/chat_v1/types/space.py | 21 ++++---- .../google/apps/chat_v1/types/space_setup.py | 20 +++---- 8 files changed, 145 insertions(+), 98 deletions(-) diff --git a/packages/google-apps-chat/google/apps/chat_v1/services/chat_service/async_client.py b/packages/google-apps-chat/google/apps/chat_v1/services/chat_service/async_client.py index b34528c1c352..41cc6e33682d 100644 --- a/packages/google-apps-chat/google/apps/chat_v1/services/chat_service/async_client.py +++ b/packages/google-apps-chat/google/apps/chat_v1/services/chat_service/async_client.py @@ -313,8 +313,9 @@ async def create_message( timeout: Union[float, object] = gapic_v1.method.DEFAULT, metadata: Sequence[Tuple[str, str]] = (), ) -> gc_message.Message: - r"""Creates a message in a Google Chat space. For an example, see - `Send a + r"""Creates a message in a Google Chat space. The maximum message + size, including text and cards, is 32,000 bytes. For an example, + see `Send a message `__. Calling this method requires @@ -769,8 +770,9 @@ async def sample_get_membership(): name (:class:`str`): Required. Resource name of the membership to retrieve. - To get the app's own membership, you can optionally use - ``spaces/{space}/members/app``. + To get the app's own membership `by using user + authentication `__, + you can optionally use ``spaces/{space}/members/app``. Format: ``spaces/{space}/members/{member}`` or ``spaces/{space}/members/app`` @@ -1572,7 +1574,7 @@ async def sample_get_space(): The request object. A request to return a single space. name (:class:`str`): Required. Resource name of the space, in the form - "spaces/*". + `spaces/*`. Format: ``spaces/{space}`` @@ -1773,19 +1775,19 @@ async def set_up_space( members `__. To specify the human members to add, add memberships with the - appropriate ``member.name`` in the ``SetUpSpaceRequest``. To add - a human user, use ``users/{user}``, where ``{user}`` can be the - email address for the user. For users in the same Workspace - organization ``{user}`` can also be the ``id`` for the person - from the People API, or the ``id`` for the user in the Directory - API. For example, if the People API Person profile ID for + appropriate ``membership.member.name``. To add a human user, use + ``users/{user}``, where ``{user}`` can be the email address for + the user. For users in the same Workspace organization + ``{user}`` can also be the ``id`` for the person from the People + API, or the ``id`` for the user in the Directory API. For + example, if the People API Person profile ID for ``user@example.com`` is ``123456789``, you can add the user to the space by setting the ``membership.member.name`` to ``users/user@example.com`` or ``users/123456789``. - For a space or group chat, if the caller blocks or is blocked by - some members, then those members aren't added to the created - space. + For a named space or group chat, if the caller blocks, or is + blocked by some members, or doesn't have permission to add some + members, then those members aren't added to the created space. To create a direct message (DM) between the calling user and another human user, specify exactly one membership to represent @@ -2365,7 +2367,7 @@ async def create_membership( authentication `__. To specify the member to add, set the ``membership.member.name`` - in the ``CreateMembershipRequest``: + for the human or app member. - To add the calling app to a space or a direct message between two human users, use ``users/app``. Unable to add other apps @@ -2519,8 +2521,12 @@ async def update_membership( timeout: Union[float, object] = gapic_v1.method.DEFAULT, metadata: Sequence[Tuple[str, str]] = (), ) -> gc_membership.Membership: - r"""Updates a membership. Requires `user - authentication `__. + r"""Updates a membership. For an example, see `Update a user's + membership in a + space `__. + + Requires `user + authentication `__. .. code-block:: python @@ -3114,7 +3120,9 @@ async def get_space_read_state( metadata: Sequence[Tuple[str, str]] = (), ) -> space_read_state.SpaceReadState: r"""Returns details about a user's read state within a space, used - to identify read and unread messages. + to identify read and unread messages. For an example, see `Get + details about a user's space read + state `__. Requires `user authentication `__. @@ -3243,7 +3251,9 @@ async def update_space_read_state( metadata: Sequence[Tuple[str, str]] = (), ) -> gc_space_read_state.SpaceReadState: r"""Updates a user's read state within a space, used to identify - read and unread messages. + read and unread messages. For an example, see `Update a user's + space read + state `__. Requires `user authentication `__. @@ -3394,7 +3404,9 @@ async def get_thread_read_state( metadata: Sequence[Tuple[str, str]] = (), ) -> thread_read_state.ThreadReadState: r"""Returns details about a user's read state within a thread, used - to identify read and unread messages. + to identify read and unread messages. For an example, see `Get + details about a user's thread read + state `__. Requires `user authentication `__. diff --git a/packages/google-apps-chat/google/apps/chat_v1/services/chat_service/client.py b/packages/google-apps-chat/google/apps/chat_v1/services/chat_service/client.py index e7fffd5b22a7..b009e74fc474 100644 --- a/packages/google-apps-chat/google/apps/chat_v1/services/chat_service/client.py +++ b/packages/google-apps-chat/google/apps/chat_v1/services/chat_service/client.py @@ -859,8 +859,9 @@ def create_message( timeout: Union[float, object] = gapic_v1.method.DEFAULT, metadata: Sequence[Tuple[str, str]] = (), ) -> gc_message.Message: - r"""Creates a message in a Google Chat space. For an example, see - `Send a + r"""Creates a message in a Google Chat space. The maximum message + size, including text and cards, is 32,000 bytes. For an example, + see `Send a message `__. Calling this method requires @@ -1306,8 +1307,9 @@ def sample_get_membership(): name (str): Required. Resource name of the membership to retrieve. - To get the app's own membership, you can optionally use - ``spaces/{space}/members/app``. + To get the app's own membership `by using user + authentication `__, + you can optionally use ``spaces/{space}/members/app``. Format: ``spaces/{space}/members/{member}`` or ``spaces/{space}/members/app`` @@ -2090,7 +2092,7 @@ def sample_get_space(): The request object. A request to return a single space. name (str): Required. Resource name of the space, in the form - "spaces/*". + `spaces/*`. Format: ``spaces/{space}`` @@ -2285,19 +2287,19 @@ def set_up_space( members `__. To specify the human members to add, add memberships with the - appropriate ``member.name`` in the ``SetUpSpaceRequest``. To add - a human user, use ``users/{user}``, where ``{user}`` can be the - email address for the user. For users in the same Workspace - organization ``{user}`` can also be the ``id`` for the person - from the People API, or the ``id`` for the user in the Directory - API. For example, if the People API Person profile ID for + appropriate ``membership.member.name``. To add a human user, use + ``users/{user}``, where ``{user}`` can be the email address for + the user. For users in the same Workspace organization + ``{user}`` can also be the ``id`` for the person from the People + API, or the ``id`` for the user in the Directory API. For + example, if the People API Person profile ID for ``user@example.com`` is ``123456789``, you can add the user to the space by setting the ``membership.member.name`` to ``users/user@example.com`` or ``users/123456789``. - For a space or group chat, if the caller blocks or is blocked by - some members, then those members aren't added to the created - space. + For a named space or group chat, if the caller blocks, or is + blocked by some members, or doesn't have permission to add some + members, then those members aren't added to the created space. To create a direct message (DM) between the calling user and another human user, specify exactly one membership to represent @@ -2865,7 +2867,7 @@ def create_membership( authentication `__. To specify the member to add, set the ``membership.member.name`` - in the ``CreateMembershipRequest``: + for the human or app member. - To add the calling app to a space or a direct message between two human users, use ``users/app``. Unable to add other apps @@ -3016,8 +3018,12 @@ def update_membership( timeout: Union[float, object] = gapic_v1.method.DEFAULT, metadata: Sequence[Tuple[str, str]] = (), ) -> gc_membership.Membership: - r"""Updates a membership. Requires `user - authentication `__. + r"""Updates a membership. For an example, see `Update a user's + membership in a + space `__. + + Requires `user + authentication `__. .. code-block:: python @@ -3596,7 +3602,9 @@ def get_space_read_state( metadata: Sequence[Tuple[str, str]] = (), ) -> space_read_state.SpaceReadState: r"""Returns details about a user's read state within a space, used - to identify read and unread messages. + to identify read and unread messages. For an example, see `Get + details about a user's space read + state `__. Requires `user authentication `__. @@ -3722,7 +3730,9 @@ def update_space_read_state( metadata: Sequence[Tuple[str, str]] = (), ) -> gc_space_read_state.SpaceReadState: r"""Updates a user's read state within a space, used to identify - read and unread messages. + read and unread messages. For an example, see `Update a user's + space read + state `__. Requires `user authentication `__. @@ -3870,7 +3880,9 @@ def get_thread_read_state( metadata: Sequence[Tuple[str, str]] = (), ) -> thread_read_state.ThreadReadState: r"""Returns details about a user's read state within a thread, used - to identify read and unread messages. + to identify read and unread messages. For an example, see `Get + details about a user's thread read + state `__. Requires `user authentication `__. diff --git a/packages/google-apps-chat/google/apps/chat_v1/services/chat_service/transports/grpc.py b/packages/google-apps-chat/google/apps/chat_v1/services/chat_service/transports/grpc.py index e16ac1e0e41c..d1cc702756dc 100644 --- a/packages/google-apps-chat/google/apps/chat_v1/services/chat_service/transports/grpc.py +++ b/packages/google-apps-chat/google/apps/chat_v1/services/chat_service/transports/grpc.py @@ -252,8 +252,9 @@ def create_message( ) -> Callable[[gc_message.CreateMessageRequest], gc_message.Message]: r"""Return a callable for the create message method over gRPC. - Creates a message in a Google Chat space. For an example, see - `Send a + Creates a message in a Google Chat space. The maximum message + size, including text and cards, is 32,000 bytes. For an example, + see `Send a message `__. Calling this method requires @@ -689,19 +690,19 @@ def set_up_space(self) -> Callable[[space_setup.SetUpSpaceRequest], space.Space] members `__. To specify the human members to add, add memberships with the - appropriate ``member.name`` in the ``SetUpSpaceRequest``. To add - a human user, use ``users/{user}``, where ``{user}`` can be the - email address for the user. For users in the same Workspace - organization ``{user}`` can also be the ``id`` for the person - from the People API, or the ``id`` for the user in the Directory - API. For example, if the People API Person profile ID for + appropriate ``membership.member.name``. To add a human user, use + ``users/{user}``, where ``{user}`` can be the email address for + the user. For users in the same Workspace organization + ``{user}`` can also be the ``id`` for the person from the People + API, or the ``id`` for the user in the Directory API. For + example, if the People API Person profile ID for ``user@example.com`` is ``123456789``, you can add the user to the space by setting the ``membership.member.name`` to ``users/user@example.com`` or ``users/123456789``. - For a space or group chat, if the caller blocks or is blocked by - some members, then those members aren't added to the created - space. + For a named space or group chat, if the caller blocks, or is + blocked by some members, or doesn't have permission to add some + members, then those members aren't added to the created space. To create a direct message (DM) between the calling user and another human user, specify exactly one membership to represent @@ -906,7 +907,7 @@ def create_membership( authentication `__. To specify the member to add, set the ``membership.member.name`` - in the ``CreateMembershipRequest``: + for the human or app member. - To add the calling app to a space or a direct message between two human users, use ``users/app``. Unable to add other apps @@ -946,8 +947,12 @@ def update_membership( ) -> Callable[[gc_membership.UpdateMembershipRequest], gc_membership.Membership]: r"""Return a callable for the update membership method over gRPC. - Updates a membership. Requires `user - authentication `__. + Updates a membership. For an example, see `Update a user's + membership in a + space `__. + + Requires `user + authentication `__. Returns: Callable[[~.UpdateMembershipRequest], @@ -1097,7 +1102,9 @@ def get_space_read_state( r"""Return a callable for the get space read state method over gRPC. Returns details about a user's read state within a space, used - to identify read and unread messages. + to identify read and unread messages. For an example, see `Get + details about a user's space read + state `__. Requires `user authentication `__. @@ -1130,7 +1137,9 @@ def update_space_read_state( r"""Return a callable for the update space read state method over gRPC. Updates a user's read state within a space, used to identify - read and unread messages. + read and unread messages. For an example, see `Update a user's + space read + state `__. Requires `user authentication `__. @@ -1162,7 +1171,9 @@ def get_thread_read_state( r"""Return a callable for the get thread read state method over gRPC. Returns details about a user's read state within a thread, used - to identify read and unread messages. + to identify read and unread messages. For an example, see `Get + details about a user's thread read + state `__. Requires `user authentication `__. diff --git a/packages/google-apps-chat/google/apps/chat_v1/services/chat_service/transports/grpc_asyncio.py b/packages/google-apps-chat/google/apps/chat_v1/services/chat_service/transports/grpc_asyncio.py index 8ae3c4e1a35f..4fe301802dba 100644 --- a/packages/google-apps-chat/google/apps/chat_v1/services/chat_service/transports/grpc_asyncio.py +++ b/packages/google-apps-chat/google/apps/chat_v1/services/chat_service/transports/grpc_asyncio.py @@ -256,8 +256,9 @@ def create_message( ) -> Callable[[gc_message.CreateMessageRequest], Awaitable[gc_message.Message]]: r"""Return a callable for the create message method over gRPC. - Creates a message in a Google Chat space. For an example, see - `Send a + Creates a message in a Google Chat space. The maximum message + size, including text and cards, is 32,000 bytes. For an example, + see `Send a message `__. Calling this method requires @@ -703,19 +704,19 @@ def set_up_space( members `__. To specify the human members to add, add memberships with the - appropriate ``member.name`` in the ``SetUpSpaceRequest``. To add - a human user, use ``users/{user}``, where ``{user}`` can be the - email address for the user. For users in the same Workspace - organization ``{user}`` can also be the ``id`` for the person - from the People API, or the ``id`` for the user in the Directory - API. For example, if the People API Person profile ID for + appropriate ``membership.member.name``. To add a human user, use + ``users/{user}``, where ``{user}`` can be the email address for + the user. For users in the same Workspace organization + ``{user}`` can also be the ``id`` for the person from the People + API, or the ``id`` for the user in the Directory API. For + example, if the People API Person profile ID for ``user@example.com`` is ``123456789``, you can add the user to the space by setting the ``membership.member.name`` to ``users/user@example.com`` or ``users/123456789``. - For a space or group chat, if the caller blocks or is blocked by - some members, then those members aren't added to the created - space. + For a named space or group chat, if the caller blocks, or is + blocked by some members, or doesn't have permission to add some + members, then those members aren't added to the created space. To create a direct message (DM) between the calling user and another human user, specify exactly one membership to represent @@ -926,7 +927,7 @@ def create_membership( authentication `__. To specify the member to add, set the ``membership.member.name`` - in the ``CreateMembershipRequest``: + for the human or app member. - To add the calling app to a space or a direct message between two human users, use ``users/app``. Unable to add other apps @@ -968,8 +969,12 @@ def update_membership( ]: r"""Return a callable for the update membership method over gRPC. - Updates a membership. Requires `user - authentication `__. + Updates a membership. For an example, see `Update a user's + membership in a + space `__. + + Requires `user + authentication `__. Returns: Callable[[~.UpdateMembershipRequest], @@ -1124,7 +1129,9 @@ def get_space_read_state( r"""Return a callable for the get space read state method over gRPC. Returns details about a user's read state within a space, used - to identify read and unread messages. + to identify read and unread messages. For an example, see `Get + details about a user's space read + state `__. Requires `user authentication `__. @@ -1157,7 +1164,9 @@ def update_space_read_state( r"""Return a callable for the update space read state method over gRPC. Updates a user's read state within a space, used to identify - read and unread messages. + read and unread messages. For an example, see `Update a user's + space read + state `__. Requires `user authentication `__. @@ -1190,7 +1199,9 @@ def get_thread_read_state( r"""Return a callable for the get thread read state method over gRPC. Returns details about a user's read state within a thread, used - to identify read and unread messages. + to identify read and unread messages. For an example, see `Get + details about a user's thread read + state `__. Requires `user authentication `__. diff --git a/packages/google-apps-chat/google/apps/chat_v1/types/membership.py b/packages/google-apps-chat/google/apps/chat_v1/types/membership.py index 44bd80d92a0c..0fafc7201bc3 100644 --- a/packages/google-apps-chat/google/apps/chat_v1/types/membership.py +++ b/packages/google-apps-chat/google/apps/chat_v1/types/membership.py @@ -396,8 +396,9 @@ class GetMembershipRequest(proto.Message): name (str): Required. Resource name of the membership to retrieve. - To get the app's own membership, you can optionally use - ``spaces/{space}/members/app``. + To get the app's own membership `by using user + authentication `__, + you can optionally use ``spaces/{space}/members/app``. Format: ``spaces/{space}/members/{member}`` or ``spaces/{space}/members/app`` diff --git a/packages/google-apps-chat/google/apps/chat_v1/types/reaction.py b/packages/google-apps-chat/google/apps/chat_v1/types/reaction.py index 4f4423244af7..c64f3d2ef5b3 100644 --- a/packages/google-apps-chat/google/apps/chat_v1/types/reaction.py +++ b/packages/google-apps-chat/google/apps/chat_v1/types/reaction.py @@ -108,7 +108,8 @@ class CustomEmoji(proto.Message): Attributes: uid (str): - Unique key for the custom emoji resource. + Output only. Unique key for the custom emoji + resource. """ uid: str = proto.Field( diff --git a/packages/google-apps-chat/google/apps/chat_v1/types/space.py b/packages/google-apps-chat/google/apps/chat_v1/types/space.py index 96b083171e62..86e3d2e305e6 100644 --- a/packages/google-apps-chat/google/apps/chat_v1/types/space.py +++ b/packages/google-apps-chat/google/apps/chat_v1/types/space.py @@ -120,16 +120,15 @@ class Space(proto.Message): Only populated in the output when ``spaceType`` is ``GROUP_CHAT`` or ``SPACE``. admin_installed (bool): - Output only. Whether the Chat app was - installed by a Google Workspace administrator. - Administrators can install a Chat app for their - domain, organizational unit, or a group of - users. - - Administrators can only install Chat apps for - direct messaging between users and the app. To - support admin install, your app must feature - direct messaging. + 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 + their organization. + + To support admin install, your Chat app must + feature direct messaging. """ class Type(proto.Enum): @@ -409,7 +408,7 @@ class GetSpaceRequest(proto.Message): Attributes: name (str): Required. Resource name of the space, in the form - "spaces/*". + `spaces/*`. Format: ``spaces/{space}`` """ diff --git a/packages/google-apps-chat/google/apps/chat_v1/types/space_setup.py b/packages/google-apps-chat/google/apps/chat_v1/types/space_setup.py index b26a6f342d54..8f7fd902d1af 100644 --- a/packages/google-apps-chat/google/apps/chat_v1/types/space_setup.py +++ b/packages/google-apps-chat/google/apps/chat_v1/types/space_setup.py @@ -75,16 +75,16 @@ class SetUpSpaceRequest(proto.Message): The set currently allows up to 20 memberships (in addition to the caller). - The ``Membership.member`` field must contain a ``user`` with - ``name`` populated (format: ``users/{user}``) and ``type`` - set to ``User.Type.HUMAN``. You can only add human users - when setting up a space (adding Chat apps is only supported - for direct message setup with the calling app). You can also - add members using the user's email as an alias for {user}. - For example, the ``user.name`` can be - ``users/example@gmail.com``." To invite Gmail users or users - from external Google Workspace domains, user's email must be - used for ``{user}``. + For human membership, the ``Membership.member`` field must + contain a ``user`` with ``name`` populated (format: + ``users/{user}``) and ``type`` set to ``User.Type.HUMAN``. + You can only add human users when setting up a space (adding + Chat apps is only supported for direct message setup with + the calling app). You can also add members using the user's + email as an alias for {user}. For example, the ``user.name`` + can be ``users/example@gmail.com``. To invite Gmail users or + users from external Google Workspace domains, user's email + must be used for ``{user}``. Optional when setting ``Space.spaceType`` to ``SPACE``.