docs: [google-apps-chat] Update doc for SetUpSpace in service ChatService to support group members (#12841)

- [ ] Regenerate this pull request now.

BEGIN_COMMIT_OVERRIDE
docs: Update doc for SetUpSpace in service ChatService to support group
members
docs: Update doc for `CreateMembership` in service `ChatService` to
support group members
docs: Update doc for field `group_member` in message
`google.chat.v1.Membership`
END_COMMIT_OVERRIDE


PiperOrigin-RevId: 646951938

Source-Link:
googleapis/googleapis@ac0973e

Source-Link:
googleapis/googleapis-gen@2b187e2
Copy-Tag:
eyJwIjoicGFja2FnZXMvZ29vZ2xlLWFwcHMtY2hhdC8uT3dsQm90LnlhbWwiLCJoIjoiMmIxODdlMjlhM2QxOTA0ZDNlNTk4MWJiM2M4YjdhYjcwYTAwMjM5MyJ9

---------

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

Author: gcf-owl-bot[bot]

packages/google-apps-chat/google/apps/chat_v1/services/chat_service/async_client.py

@@ -1785,6 +1785,18 @@ async def set_up_space(
         the space by setting the ``membership.member.name`` to
         ``users/[email protected]`` or ``users/123456789``.
 
+        To specify the Google groups to add, add memberships with the
+        appropriate ``membership.group_member.name``. To add or invite a
+        Google group, use ``groups/{group}``, where ``{group}`` is the
+        ``id`` for the group from the Cloud Identity Groups API. For
+        example, you can use `Cloud Identity Groups lookup
+        API <https://cloud.google.com/identity/docs/reference/rest/v1/groups/lookup>`__
+        to retrieve the ID ``123456789`` for group email
+        ``[email protected]``, then you can add the group to the space
+        by setting the ``membership.group_member.name`` to
+        ``groups/123456789``. Group email is not supported, and Google
+        groups can only be added as members in named spaces.
+
         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.
@@ -2367,7 +2379,8 @@ async def create_membership(
         authentication <https://developers.google.com/workspace/chat/authenticate-authorize-chat-user>`__.
 
         To specify the member to add, set the ``membership.member.name``
-        for the human or app member.
+        for the human or app member, or set the
+        ``membership.group_member.name`` for the group 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
@@ -2383,6 +2396,18 @@ async def create_membership(
            ``membership.member.name`` to ``users/[email protected]`` or
            ``users/123456789``.
 
+        -  To add or invite a Google group in a named space, use
+           ``groups/{group}``, where ``{group}`` is the ``id`` for the
+           group from the Cloud Identity Groups API. For example, you
+           can use `Cloud Identity Groups lookup
+           API <https://cloud.google.com/identity/docs/reference/rest/v1/groups/lookup>`__
+           to retrieve the ID ``123456789`` for group email
+           ``[email protected]``, then you can add or invite the group
+           to a named space by setting the
+           ``membership.group_member.name`` to ``groups/123456789``.
+           Group email is not supported, and Google groups can only be
+           added as members in named spaces.
+
         .. code-block:: python
 
             # This snippet has been automatically generated and should be regarded as a

packages/google-apps-chat/google/apps/chat_v1/services/chat_service/client.py

@@ -2297,6 +2297,18 @@ def set_up_space(
         the space by setting the ``membership.member.name`` to
         ``users/[email protected]`` or ``users/123456789``.
 
+        To specify the Google groups to add, add memberships with the
+        appropriate ``membership.group_member.name``. To add or invite a
+        Google group, use ``groups/{group}``, where ``{group}`` is the
+        ``id`` for the group from the Cloud Identity Groups API. For
+        example, you can use `Cloud Identity Groups lookup
+        API <https://cloud.google.com/identity/docs/reference/rest/v1/groups/lookup>`__
+        to retrieve the ID ``123456789`` for group email
+        ``[email protected]``, then you can add the group to the space
+        by setting the ``membership.group_member.name`` to
+        ``groups/123456789``. Group email is not supported, and Google
+        groups can only be added as members in named spaces.
+
         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.
@@ -2867,7 +2879,8 @@ def create_membership(
         authentication <https://developers.google.com/workspace/chat/authenticate-authorize-chat-user>`__.
 
         To specify the member to add, set the ``membership.member.name``
-        for the human or app member.
+        for the human or app member, or set the
+        ``membership.group_member.name`` for the group 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
@@ -2883,6 +2896,18 @@ def create_membership(
            ``membership.member.name`` to ``users/[email protected]`` or
            ``users/123456789``.
 
+        -  To add or invite a Google group in a named space, use
+           ``groups/{group}``, where ``{group}`` is the ``id`` for the
+           group from the Cloud Identity Groups API. For example, you
+           can use `Cloud Identity Groups lookup
+           API <https://cloud.google.com/identity/docs/reference/rest/v1/groups/lookup>`__
+           to retrieve the ID ``123456789`` for group email
+           ``[email protected]``, then you can add or invite the group
+           to a named space by setting the
+           ``membership.group_member.name`` to ``groups/123456789``.
+           Group email is not supported, and Google groups can only be
+           added as members in named spaces.
+
         .. code-block:: python
 
             # This snippet has been automatically generated and should be regarded as a

packages/google-apps-chat/google/apps/chat_v1/services/chat_service/transports/grpc.py

@@ -700,6 +700,18 @@ def set_up_space(self) -> Callable[[space_setup.SetUpSpaceRequest], space.Space]
         the space by setting the ``membership.member.name`` to
         ``users/[email protected]`` or ``users/123456789``.
 
+        To specify the Google groups to add, add memberships with the
+        appropriate ``membership.group_member.name``. To add or invite a
+        Google group, use ``groups/{group}``, where ``{group}`` is the
+        ``id`` for the group from the Cloud Identity Groups API. For
+        example, you can use `Cloud Identity Groups lookup
+        API <https://cloud.google.com/identity/docs/reference/rest/v1/groups/lookup>`__
+        to retrieve the ID ``123456789`` for group email
+        ``[email protected]``, then you can add the group to the space
+        by setting the ``membership.group_member.name`` to
+        ``groups/123456789``. Group email is not supported, and Google
+        groups can only be added as members in named spaces.
+
         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.
@@ -907,7 +919,8 @@ def create_membership(
         authentication <https://developers.google.com/workspace/chat/authenticate-authorize-chat-user>`__.
 
         To specify the member to add, set the ``membership.member.name``
-        for the human or app member.
+        for the human or app member, or set the
+        ``membership.group_member.name`` for the group 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
@@ -923,6 +936,18 @@ def create_membership(
            ``membership.member.name`` to ``users/[email protected]`` or
            ``users/123456789``.
 
+        -  To add or invite a Google group in a named space, use
+           ``groups/{group}``, where ``{group}`` is the ``id`` for the
+           group from the Cloud Identity Groups API. For example, you
+           can use `Cloud Identity Groups lookup
+           API <https://cloud.google.com/identity/docs/reference/rest/v1/groups/lookup>`__
+           to retrieve the ID ``123456789`` for group email
+           ``[email protected]``, then you can add or invite the group
+           to a named space by setting the
+           ``membership.group_member.name`` to ``groups/123456789``.
+           Group email is not supported, and Google groups can only be
+           added as members in named spaces.
+
         Returns:
             Callable[[~.CreateMembershipRequest],
                     ~.Membership]:

packages/google-apps-chat/google/apps/chat_v1/services/chat_service/transports/grpc_asyncio.py

@@ -714,6 +714,18 @@ def set_up_space(
         the space by setting the ``membership.member.name`` to
         ``users/[email protected]`` or ``users/123456789``.
 
+        To specify the Google groups to add, add memberships with the
+        appropriate ``membership.group_member.name``. To add or invite a
+        Google group, use ``groups/{group}``, where ``{group}`` is the
+        ``id`` for the group from the Cloud Identity Groups API. For
+        example, you can use `Cloud Identity Groups lookup
+        API <https://cloud.google.com/identity/docs/reference/rest/v1/groups/lookup>`__
+        to retrieve the ID ``123456789`` for group email
+        ``[email protected]``, then you can add the group to the space
+        by setting the ``membership.group_member.name`` to
+        ``groups/123456789``. Group email is not supported, and Google
+        groups can only be added as members in named spaces.
+
         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.
@@ -927,7 +939,8 @@ def create_membership(
         authentication <https://developers.google.com/workspace/chat/authenticate-authorize-chat-user>`__.
 
         To specify the member to add, set the ``membership.member.name``
-        for the human or app member.
+        for the human or app member, or set the
+        ``membership.group_member.name`` for the group 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
@@ -943,6 +956,18 @@ def create_membership(
            ``membership.member.name`` to ``users/[email protected]`` or
            ``users/123456789``.
 
+        -  To add or invite a Google group in a named space, use
+           ``groups/{group}``, where ``{group}`` is the ``id`` for the
+           group from the Cloud Identity Groups API. For example, you
+           can use `Cloud Identity Groups lookup
+           API <https://cloud.google.com/identity/docs/reference/rest/v1/groups/lookup>`__
+           to retrieve the ID ``123456789`` for group email
+           ``[email protected]``, then you can add or invite the group
+           to a named space by setting the
+           ``membership.group_member.name`` to ``groups/123456789``.
+           Group email is not supported, and Google groups can only be
+           added as members in named spaces.
+
         Returns:
             Callable[[~.CreateMembershipRequest],
                     Awaitable[~.Membership]]:

packages/google-apps-chat/google/apps/chat_v1/types/membership.py

@@ -73,9 +73,7 @@ class Membership(proto.Message):
             This field is a member of `oneof`_ ``memberType``.
         group_member (google.apps.chat_v1.types.Group):
             The Google Group the membership corresponds
-            to. Only supports read operations. Other
-            operations, like creating or updating a
-            membership, aren't currently supported.
+            to.
 
             This field is a member of `oneof`_ ``memberType``.
         create_time (google.protobuf.timestamp_pb2.Timestamp):

packages/google-apps-chat/google/apps/chat_v1/types/space_setup.py

@@ -69,8 +69,9 @@ class SetUpSpaceRequest(proto.Message):
             Chat app with a different authenticated user
             returns an error.
         memberships (MutableSequence[google.apps.chat_v1.types.Membership]):
-            Optional. The Google Chat users to invite to join the space.
-            Omit the calling user, as they are added automatically.
+            Optional. The Google Chat users or groups to invite to join
+            the space. Omit the calling user, as they are added
+            automatically.
 
             The set currently allows up to 20 memberships (in addition
             to the caller).
@@ -86,6 +87,11 @@ class SetUpSpaceRequest(proto.Message):
             users from external Google Workspace domains, user's email
             must be used for ``{user}``.
 
+            For Google group membership, the ``Membership.group_member``
+            field must contain a ``group`` with ``name`` populated
+            (format ``groups/{group}``). You can only add Google groups
+            when setting ``Space.spaceType`` to ``SPACE``.
+
             Optional when setting ``Space.spaceType`` to ``SPACE``.
 
             Required when setting ``Space.spaceType`` to ``GROUP_CHAT``,

packages/google-apps-chat/noxfile.py

@@ -160,14 +160,28 @@ def install_unittest_dependencies(session, *constraints):
         session.install("-e", ".", *constraints)
 
 
-def default(session):
+@nox.session(python=UNIT_TEST_PYTHON_VERSIONS)
+@nox.parametrize(
+    "protobuf_implementation",
+    ["python", "upb", "cpp"],
+)
+def unit(session, protobuf_implementation):
     # Install all test dependencies, then install this package in-place.
 
+    if protobuf_implementation == "cpp" and session.python in ("3.11", "3.12"):
+        session.skip("cpp implementation is not supported in python 3.11+")
+
     constraints_path = str(
         CURRENT_DIRECTORY / "testing" / f"constraints-{session.python}.txt"
     )
     install_unittest_dependencies(session, "-c", constraints_path)
 
+    # TODO(https://github.com/googleapis/synthtool/issues/1976):
+    # Remove the 'cpp' implementation once support for Protobuf 3.x is dropped.
+    # The 'cpp' implementation requires Protobuf<4.
+    if protobuf_implementation == "cpp":
+        session.install("protobuf<4")
+
     # Run py.test against the unit tests.
     session.run(
         "py.test",
@@ -181,15 +195,12 @@ def default(session):
         "--cov-fail-under=0",
         os.path.join("tests", "unit"),
         *session.posargs,
+        env={
+            "PROTOCOL_BUFFERS_PYTHON_IMPLEMENTATION": protobuf_implementation,
+        },
     )
 
 
-@nox.session(python=UNIT_TEST_PYTHON_VERSIONS)
-def unit(session):
-    """Run the unit test suite."""
-    default(session)
-
-
 def install_systemtest_dependencies(session, *constraints):
     # Use pre-release gRPC for system tests.
     # Exclude version 1.52.0rc1 which has a known issue.
@@ -358,9 +369,16 @@ def docfx(session):
 
 
 @nox.session(python="3.12")
-def prerelease_deps(session):
+@nox.parametrize(
+    "protobuf_implementation",
+    ["python", "upb", "cpp"],
+)
+def prerelease_deps(session, protobuf_implementation):
     """Run all tests with prerelease versions of dependencies installed."""
 
+    if protobuf_implementation == "cpp" and session.python in ("3.11", "3.12"):
+        session.skip("cpp implementation is not supported in python 3.11+")
+
     # Install all dependencies
     session.install("-e", ".[all, tests, tracing]")
     unit_deps_all = UNIT_TEST_STANDARD_DEPENDENCIES + UNIT_TEST_EXTERNAL_DEPENDENCIES
@@ -397,9 +415,9 @@ def prerelease_deps(session):
         "protobuf",
         # dependency of grpc
         "six",
+        "grpc-google-iam-v1",
         "googleapis-common-protos",
-        # Exclude version 1.52.0rc1 which has a known issue. See https://github.com/grpc/grpc/issues/32163
-        "grpcio!=1.52.0rc1",
+        "grpcio",
         "grpcio-status",
         "google-api-core",
         "google-auth",
@@ -425,4 +443,10 @@ def prerelease_deps(session):
     session.run("python", "-c", "import grpc; print(grpc.__version__)")
     session.run("python", "-c", "import google.auth; print(google.auth.__version__)")
 
-    session.run("py.test", "tests/unit")
+    session.run(
+        "py.test",
+        "tests/unit",
+        env={
+            "PROTOCOL_BUFFERS_PYTHON_IMPLEMENTATION": protobuf_implementation,
+        },
+    )