Google Chat-Gruppenbereich erstellen und Mitglieder hinzufügen

In diesem Leitfaden wird beschrieben, wie Sie mit der Methode setUp() für die Ressource Space der Google Chat API einen Chat-Gruppenbereich erstellen und ihm Mitglieder hinzufügen.

Die Space-Ressource stellt einen Ort dar, an dem Personen und Chat-Apps Nachrichten senden, Dateien teilen und zusammenarbeiten können. Es gibt verschiedene Arten von Bereichen:

  • Direktnachrichten (DNs) sind Unterhaltungen zwischen zwei Nutzern oder zwischen einem Nutzer und einer Chat-App.
  • Gruppenchats sind Unterhaltungen zwischen drei oder mehr Nutzern und Chat-Apps.
  • Benannte Gruppenbereiche sind dauerhafte Orte, an denen Nutzer Nachrichten senden, Dateien teilen und zusammenarbeiten können.

Mit der Methode setUp() können Sie Folgendes tun:

  • Erstellen Sie einen benannten Space mit ersten Mitgliedern.
  • Erstelle eine Direktnachricht (DN) zwischen zwei Personen.
  • Gruppennachrichten mit mehreren Personen einrichten

Beachten Sie beim Einrichten eines Gruppenbereichs Folgendes:

  • Der anrufende (authentifizierte) Nutzer wird automatisch dem Bereich hinzugefügt. Sie müssen die Mitgliedschaft des Nutzers also nicht in der Anfrage angeben.
  • Wenn Sie eine Direktnachricht (DN) erstellen und zwischen zwei Nutzern bereits eine DN vorhanden ist, wird diese zurückgegeben. Andernfalls wird eine Direktnachricht erstellt.
  • Wenn beim Erstellen eines Gruppenchats keine der im Antrag angegebenen Mitgliedschaften erfolgreich zum Gruppenchat hinzugefügt werden kann (z. B. aufgrund eines Berechtigungsproblems), wird möglicherweise ein leerer Gruppenchat erstellt, der nur den anrufenden Nutzer enthält.
  • Sie können keine Gruppenbereiche mit verschachtelten Antworten einrichten oder Personen außerhalb Ihrer Google Workspace-Organisation hinzufügen.
  • Doppelte Mitgliedschaften (einschließlich des aufrufenden Nutzers), die im Request angegeben sind, werden herausgefiltert, anstatt einen Request-Fehler zu verursachen.
  • Wenn ein Google Workspace-Administrator eine Chat-App für die gesamte Google Workspace-Organisation installiert, wird in Google Chat eine Direktnachricht zwischen der installierten Chat-App und jedem Nutzer in der Organisation erstellt. Es ist also nicht erforderlich, Direktnachrichten programmatisch einzurichten. Stattdessen können Sie Projektbereiche auflisten, um alle Direktnachrichten zurückzugeben, oder eine Direktnachricht suchen, um Details zu einer bestimmten Direktnachricht zu erhalten.

Vorbereitung

Node.js

Python

Java

Apps Script

Gruppenbereich einrichten

Um einen Bereich einzurichten, übergeben Sie Folgendes in Ihrer Anfrage:

  • Geben Sie den Autorisierungsbereich chat.spaces.create oder chat.spaces an.
  • Rufen Sie die Methode SetUpSpace() auf.
  • Übergeben Sie space als Instanz von Space mit allen erforderlichen Feldern wie displayName oder spaceType.
  • Übergeben Sie memberships als Array von Membership-Instanzen. Für jede Instanz:
    • Geben Sie users/{user} an, um einen menschlichen Nutzer als Space-Mitglied hinzuzufügen. Dabei ist {user} entweder die {person_id} für die person aus der People API oder die ID eines user in der Directory API. Wenn die Person resourceName in der People API beispielsweise people/123456789 ist, können Sie den Nutzer dem Bereich hinzufügen, indem Sie eine Mitgliedschaft mit users/123456789 als member.name einfügen.
    • Geben Sie groups/{group} an, um eine Gruppe als Mitglied eines Gruppenbereichs hinzuzufügen. {group} ist die Gruppen-ID, für die Sie eine Mitgliedschaft erstellen möchten. Die ID für die Gruppe kann mit der Cloud Identity API abgerufen werden. Wenn die Cloud Identity API beispielsweise eine Gruppe mit dem Namen groups/123456789 zurückgibt, setzen Sie membership.groupMember.name auf groups/123456789. Google-Gruppen können nicht einem Gruppenchat oder einer Direktnachricht, sondern nur einem benannten Projektbereich hinzugefügt werden.

Wenn Sie eine Direktnachricht zwischen dem anrufenden Nutzer und einem anderen menschlichen Nutzer erstellen möchten, geben Sie in Ihrer Anfrage die Mitgliedschaft des menschlichen Nutzers an.

Wenn Sie eine DM zwischen dem anrufenden Nutzer und der anrufenden App erstellen möchten, legen Sie space.singleUserBotDm auf true fest und geben Sie keine Mitgliedschaften an. Sie können diese Methode nur verwenden, um eine Direktnachricht mit der Anruf-App einzurichten. Wenn Sie die Anruf-App als Mitglied eines Bereichs oder einer vorhandenen Direktnachricht zwischen zwei menschlichen Nutzern hinzufügen möchten, lesen Sie den Abschnitt Mitgliedschaft erstellen.

Im folgenden Beispiel wird ein benannter Bereich erstellt und eine Mitgliedschaft für zwei menschliche Nutzer (den authentifizierten Nutzer und einen anderen Nutzer) erstellt.

Node.js

chat/client-libraries/cloud/set-up-space-user-cred.js
import {createClientWithUserCredentials} from './authentication-utils.js';

const USER_AUTH_OAUTH_SCOPES = ['https://www.googleapis.com/auth/chat.spaces.create'];

// This sample shows how to set up a named space with one initial member
// with user credential
async function main() {
  // Create a client
  const chatClient = await createClientWithUserCredentials(USER_AUTH_OAUTH_SCOPES);

  // Initialize request argument(s)
  const request = {
    space: {
      spaceType: 'SPACE',
      // Replace DISPLAY_NAME here.
      displayName: 'DISPLAY_NAME'
    },
    memberships: [{
      member: {
        // Replace USER_NAME here.
        name: 'users/USER_NAME',
        type: 'HUMAN'
      }
    }]
  };

  // Make the request
  const response = await chatClient.setUpSpace(request);

  // Handle the response
  console.log(response);
}

main().catch(console.error);

Python

chat/client-libraries/cloud/set_up_space_user_cred.py
from authentication_utils import create_client_with_user_credentials
from google.apps import chat_v1 as google_chat

SCOPES = ["https://www.googleapis.com/auth/chat.spaces.create"]

def set_up_space_with_user_cred():
    # Create a client
    client = create_client_with_user_credentials(SCOPES)

    # Initialize request argument(s)
    request = google_chat.SetUpSpaceRequest(
        space = {
            "space_type": 'SPACE',
            # Replace DISPLAY_NAME here.
            "display_name": 'DISPLAY_NAME'
        },
        memberships = [{
            "member": {
                # Replace USER_NAME here.
                "name": 'users/USER_NAME',
                "type_": 'HUMAN'
            }
        }]
    )

    # Make the request
    response = client.set_up_space(request)

    # Handle the response
    print(response)

set_up_space_with_user_cred()

Java

chat/client-libraries/cloud/src/main/java/com/google/workspace/api/chat/samples/SetUpSpaceUserCred.java
import com.google.chat.v1.ChatServiceClient;
import com.google.chat.v1.Membership;
import com.google.chat.v1.SetUpSpaceRequest;
import com.google.chat.v1.Space;
import com.google.chat.v1.User;

// This sample shows how to set up a named space with one initial member with
// user credential.
public class SetUpSpaceUserCred {

  private static final String SCOPE =
    "https://www.googleapis.com/auth/chat.spaces.create";

  public static void main(String[] args) throws Exception {
    try (ChatServiceClient chatServiceClient =
        AuthenticationUtils.createClientWithUserCredentials(
          ImmutableList.of(SCOPE))) {
      SetUpSpaceRequest.Builder request = SetUpSpaceRequest.newBuilder()
        .setSpace(Space.newBuilder()
          .setSpaceType(Space.SpaceType.SPACE)
          // Replace DISPLAY_NAME here.
          .setDisplayName("DISPLAY_NAME"))
        .addAllMemberships(ImmutableList.of(Membership.newBuilder()
          .setMember(User.newBuilder()
            // Replace USER_NAME here.
            .setName("users/USER_NAME")
            .setType(User.Type.HUMAN)).build()));
      Space response = chatServiceClient.setUpSpace(request.build());

      System.out.println(JsonFormat.printer().print(response));
    }
  }
}

Apps Script

chat/advanced-service/Main.gs
/**
 * This sample shows how to set up a named space with one initial member with
 * user credential.
 * 
 * It relies on the OAuth2 scope 'https://www.googleapis.com/auth/chat.spaces.create'
 * referenced in the manifest file (appsscript.json).
 */
function setUpSpaceUserCred() {
  // Initialize request argument(s)
  const space = {
    spaceType: 'SPACE',
    // TODO(developer): Replace DISPLAY_NAME here
    displayName: 'DISPLAY_NAME'
  };
  const memberships = [{
    member: {
      // TODO(developer): Replace USER_NAME here
      name: 'users/USER_NAME',
      // User type for the membership
      type: 'HUMAN'
    }
  }];

  // Make the request
  const response = Chat.Spaces.setup({ space: space, memberships: memberships });

  // Handle the response
  console.log(response);
}

So führen Sie das Beispiel aus:

  • DISPLAY_NAME: Der Anzeigename des neuen Bereichs.
  • USER_NAME: die ID des anderen Nutzers, für den eine Mitgliedschaft enthalten sein soll.

Um zum Gruppenbereich zu gelangen, verwenden Sie die Ressourcen-ID des Gruppenbereichs, um die URL des Gruppenbereichs zu erstellen. Sie können die Ressourcen-ID aus dem Feld name im Antworttext von Google Chat abrufen. Wenn die name Ihres Bereichs beispielsweise spaces/1234567 ist, können Sie über die folgende URL auf den Bereich zugreifen: https://mail.google.com/chat/u/0/#chat/space/1234567.