Nutzer, Google Groups-Gruppen oder Google Chat App in einen Gruppenbereich einladen oder hinzufügen

In diesem Leitfaden wird erläutert, wie Sie mit der Methode create() der Membership-Ressource der Google Chat API einen Nutzer, eine Google-Gruppe oder eine Chat-App zu einem Gruppenbereich einladen oder hinzufügen, was auch als Erstellen einer Mitgliedschaft bezeichnet wird. Wenn beim Erstellen einer Mitgliedschaft die automatische Annahme für das angegebene Mitglied deaktiviert ist, wird es eingeladen und muss die Einladung zum Gruppenbereich annehmen, bevor es beitreten kann. Andernfalls wird das Mitglied durch das Erstellen einer Mitgliedschaft direkt dem angegebenen Gruppenbereich hinzugefügt.

Als Google Workspace-Administrator können Sie jedem Gruppenbereich in Ihrer Google Workspace-Organisation Nutzer, Google Groups-Gruppen oder Chat-Apps hinzufügen.

Die Ressource Membership gibt an, ob ein menschlicher Nutzer oder die Google Chat-App zu einem Gruppenbereich eingeladen wird, ihm angehört oder nicht.

Vorbereitung

Node.js

Python

Java

Apps Script

Nutzer in einen Gruppenbereich einladen oder hinzufügen

Wenn Sie einen Nutzer zu einem Gruppenbereich mit Nutzerauthentifizierung einladen oder hinzufügen möchten, geben Sie in Ihrer Anfrage Folgendes an:

  • Geben Sie den Autorisierungsbereich für chat.memberships an.
  • Rufen Sie die Methode CreateMembership() auf.
  • Geben Sie parent als Ressourcennamen des Gruppenbereichs an, in dem die Mitgliedschaft erstellt werden soll.
  • Übergeben Sie membership als Instanz von Membership, wobei das Feld member auf Folgendes festgelegt ist:
    • Das Feld type ist auf HUMAN gesetzt.
    • Das Feld name ist auf users/{user} gesetzt, wobei {user} die Person ist, die Sie dem Gruppenbereich hinzufügen möchten. Wenn Sie den Chat-Nutzer angeben möchten, ersetzen Sie {user} durch einen der folgenden Werte:
      • Die ID für die Person in der People API. Wenn der Wert für die People API person resourceName beispielsweise people/123456789 ist, verwenden Sie den Wert users/123456789.
      • Die ID für den Nutzer in der Directory API.
      • Die E-Mail-Adresse des Nutzers. Beispiel: users/222larabrown@gmail.com oder users/larabrown@cymbalgroup.com. Wenn der Nutzer ein Google-Konto verwendet oder zu einer anderen Google Workspace-Organisation gehört, müssen Sie seine E-Mail-Adresse verwenden.

Im folgenden Beispiel wird einem Gruppenbereich ein Nutzer mit Nutzerauthentifizierung hinzugefügt:

Node.js

chat/client-libraries/cloud/create-membership-user-cred.js
import {createClientWithUserCredentials} from './authentication-utils.js';

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

// This sample shows how to create membership with user credential for a human user
async function main() {
  // Create a client
  const chatClient = await createClientWithUserCredentials(USER_AUTH_OAUTH_SCOPES);

  // Initialize request argument(s)
  const request = {
    // Replace SPACE_NAME here.
    parent: 'spaces/SPACE_NAME',
    membership: {
      member: {
        // Replace USER_NAME here
        name: 'users/USER_NAME',
        // User type for the membership
        type: 'HUMAN'
      }
    }
  };

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

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

main().catch(console.error);

Python

chat/client-libraries/cloud/create_membership_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.memberships"]

# This sample shows how to create membership with user credential for a human
# user
def create_membership_with_user_cred():
    # Create a client
    client = create_client_with_user_credentials(SCOPES)

    # Initialize request argument(s)
    request = google_chat.CreateMembershipRequest(
        # Replace SPACE_NAME here
        parent = "spaces/SPACE_NAME",
        membership = {
            "member": {
                # Replace USER_NAME here
                "name": "users/USER_NAME",
                # user type for the membership
                "type_": "HUMAN"
            }
        }
    )

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

    # Handle the response
    print(response)

create_membership_with_user_cred()

Java

chat/client-libraries/cloud/src/main/java/com/google/workspace/api/chat/samples/CreateMembershipUserCred.java
import com.google.chat.v1.ChatServiceClient;
import com.google.chat.v1.CreateMembershipRequest;
import com.google.chat.v1.Membership;
import com.google.chat.v1.SpaceName;
import com.google.chat.v1.User;

// This sample shows how to create membership with user credential for a human
// user.
public class CreateMembershipUserCred {

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

  public static void main(String[] args) throws Exception {
    try (ChatServiceClient chatServiceClient =
        AuthenticationUtils.createClientWithUserCredentials(
          ImmutableList.of(SCOPE))) {
      CreateMembershipRequest.Builder request = CreateMembershipRequest.newBuilder()
        // replace SPACE_NAME here
        .setParent("spaces/SPACE_NAME")
        .setMembership(Membership.newBuilder()
          .setMember(User.newBuilder()
            // replace USER_NAME here
            .setName("users/USER_NAME")
            // user type for the membership
            .setType(User.Type.HUMAN)));
      Membership response = chatServiceClient.createMembership(request.build());

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

Apps Script

chat/advanced-service/Main.gs
/**
 * This sample shows how to create membership with user credential for a human user
 * 
 * It relies on the OAuth2 scope 'https://www.googleapis.com/auth/chat.memberships'
 * referenced in the manifest file (appsscript.json).
 */
function createMembershipUserCred() {
  // Initialize request argument(s)
  // TODO(developer): Replace SPACE_NAME here.
  const parent = 'spaces/SPACE_NAME';
  const membership = {
    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.Members.create(membership, parent);

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

Ersetzen Sie Folgendes, um das Beispiel auszuführen:

  • SPACE_NAME: die ID aus dem name des Gruppenbereichs. Sie können die ID durch Aufrufen der Methode ListSpaces() oder aus der URL des Gruppenbereichs abrufen.
  • USER_NAME: eine Nutzer-ID.

Die Chat API gibt eine Instanz von Membership zurück, in der die erstellte Nutzermitgliedschaft angegeben ist.

Google-Gruppen zu Gruppenbereichen einladen oder hinzufügen

Wenn Sie eine Google-Gruppe zu einem Gruppenbereich mit Nutzerauthentifizierung einladen oder hinzufügen möchten (die App-Authentifizierung unterstützt das nicht), geben Sie in Ihrer Anfrage Folgendes an:

  • Geben Sie den Autorisierungsbereich für chat.memberships an.
  • Rufen Sie die Methode CreateMembership() auf.
  • Gib parent als Ressourcennamen des Gruppenbereichs an, in dem die Mitgliedschaft erstellt werden soll.
  • Übergeben Sie membership als Instanz von Membership, wobei das Feld name von groupMember auf groups/{group} festgelegt ist. {group} ist die Gruppen-ID, für die Sie die Mitgliedschaft erstellen möchten. Die ID für die Gruppe kann mithilfe der Cloud Identity API abgerufen werden.

Google-Gruppen können keinem Gruppenchat oder einer Direktnachricht hinzugefügt werden, sondern nur einem benannten Gruppenbereich.

Im folgenden Beispiel wird einer benannten Gruppe mit Nutzerauthentifizierung eine Gruppe hinzugefügt:

Node.js

chat/client-libraries/cloud/create-membership-user-cred-for-group.js
import {createClientWithUserCredentials} from './authentication-utils.js';

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

// This sample shows how to create membership with user credential for a group
async function main() {
  // Create a client
  const chatClient = await createClientWithUserCredentials(USER_AUTH_OAUTH_SCOPES);

  // Initialize request argument(s)
  const request = {
    // Replace SPACE_NAME here.
    parent: 'spaces/SPACE_NAME',
    membership: {
      groupMember: {
        // Replace GROUP_NAME here
        name: 'groups/GROUP_NAME'
      }
    }
  };

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

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

main().catch(console.error);

Python

chat/client-libraries/cloud/create_membership_user_cred_for_group.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.memberships"]

# This sample shows how to create membership with user credential for a group
def create_membership_with_user_cred_for_group():
    # Create a client
    client = create_client_with_user_credentials(SCOPES)

    # Initialize request argument(s)
    request = google_chat.CreateMembershipRequest(
        # Replace SPACE_NAME here
        parent = "spaces/SPACE_NAME",
        membership = {
            "groupMember": {
                # Replace GROUP_NAME here
                "name": "groups/GROUP_NAME"
            }
        }
    )

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

    # Handle the response
    print(response)

create_membership_with_user_cred_for_group()

Java

chat/client-libraries/cloud/src/main/java/com/google/workspace/api/chat/samples/CreateMembershipUserCredForGroup.java
import com.google.chat.v1.ChatServiceClient;
import com.google.chat.v1.CreateMembershipRequest;
import com.google.chat.v1.Membership;
import com.google.chat.v1.SpaceName;
import com.google.chat.v1.Group;

// This sample shows how to create membership with user credential for a group.
public class CreateMembershipUserCredForGroup {

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

  public static void main(String[] args) throws Exception {
    try (ChatServiceClient chatServiceClient =
        AuthenticationUtils.createClientWithUserCredentials(
          ImmutableList.of(SCOPE))) {
      CreateMembershipRequest.Builder request = CreateMembershipRequest.newBuilder()
        // replace SPACE_NAME here
        .setParent("spaces/SPACE_NAME")
        .setMembership(Membership.newBuilder()
          .setGroupMember(Group.newBuilder()
            // replace GROUP_NAME here
            .setName("groups/GROUP_NAME")));
      Membership response = chatServiceClient.createMembership(request.build());

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

Apps Script

chat/advanced-service/Main.gs
/**
 * This sample shows how to create membership with user credential for a group
 * 
 * It relies on the OAuth2 scope 'https://www.googleapis.com/auth/chat.memberships'
 * referenced in the manifest file (appsscript.json).
 */
function createMembershipUserCredForGroup() {
  // Initialize request argument(s)
  // TODO(developer): Replace SPACE_NAME here.
  const parent = 'spaces/SPACE_NAME';
  const membership = {
    groupMember: {
      // TODO(developer): Replace GROUP_NAME here
      name: 'groups/GROUP_NAME'
    }
  };

  // Make the request
  const response = Chat.Spaces.Members.create(membership, parent);

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

Ersetzen Sie zum Ausführen des Beispiels Folgendes:

  • SPACE_NAME: die ID aus dem name des Gruppenbereichs Sie können die ID durch Aufrufen der Methode ListSpaces() oder aus der URL des Gruppenbereichs abrufen.
  • GROUP_NAME: eine Gruppen-ID.

Die Chat API gibt eine Instanz von Membership zurück, die Details zur erstellten Nutzermitgliedschaft enthält.

Chat-App zu einem Gruppenbereich hinzufügen

Eine Chat-App kann einem Gruppenbereich keine andere App als Mitglied hinzufügen. Wenn Sie einer Gruppenbereichs- oder Direktnachricht zwischen zwei Nutzern eine Chat-App hinzufügen möchten, geben Sie in Ihrer Anfrage Folgendes mit Nutzerauthentifizierung an. Die App-Authentifizierung unterstützt das Einladen oder Hinzufügen einer Chat-App zu einem Gruppenbereich nicht:

  • Geben Sie den Autorisierungsbereich für chat.memberships.app an.
  • Rufen Sie die Methode CreateMembership() auf.
  • Übergeben Sie parent als Ressourcennamen des Gruppenbereichs, in dem die Mitgliedschaft erstellt werden soll.
  • Übergeben Sie membership als Instanz von Membership, wobei das Feld member mit Folgendem festgelegt ist:
    • Das Feld type ist auf BOT gesetzt.
    • Das Feld name ist auf users/app festgelegt, ein Alias, der die App darstellt, die die Chat API aufruft.

Im folgenden Beispiel wird einem Gruppenbereich eine Chat-App hinzugefügt:

Node.js

chat/client-libraries/cloud/create-membership-user-cred-for-app.js
import {createClientWithUserCredentials} from './authentication-utils.js';

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

// This sample shows how to create membership with app credential for an app
async function main() {
  // Create a client
  const chatClient = await createClientWithUserCredentials(USER_AUTH_OAUTH_SCOPES);

  // Initialize request argument(s)
  const request = {
    // Replace SPACE_NAME here.
    parent: 'spaces/SPACE_NAME',
    membership: {
      member: {
        // Member name for app membership, do not change this
        name: 'users/app',
        // User type for the membership
        type: 'BOT'
      }
    }
  };

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

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

main().catch(console.error);

Python

chat/client-libraries/cloud/create_membership_user_cred_for_app.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.memberships.app"]

# This sample shows how to create membership with app credential for an app
def create_membership_with_user_cred_for_app():
    # Create a client
    client = create_client_with_user_credentials(SCOPES)

    # Initialize request argument(s)
    request = google_chat.CreateMembershipRequest(
        # Replace SPACE_NAME here
        parent = "spaces/SPACE_NAME",
        membership = {
            "member": {
                # member name for app membership, do not change this.
                "name": "users/app",
                # user type for the membership
                "type_": "BOT"
            }
        }
    )

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

    # Handle the response
    print(response)

create_membership_with_user_cred_for_app()

Java

chat/client-libraries/cloud/src/main/java/com/google/workspace/api/chat/samples/CreateMembershipUserCredForApp.java
import com.google.chat.v1.ChatServiceClient;
import com.google.chat.v1.CreateMembershipRequest;
import com.google.chat.v1.Membership;
import com.google.chat.v1.SpaceName;
import com.google.chat.v1.User;

// This sample shows how to create membership with user credential for the
// calling app.
public class CreateMembershipUserCredForApp {

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

  public static void main(String[] args) throws Exception {
    try (ChatServiceClient chatServiceClient =
        AuthenticationUtils.createClientWithUserCredentials(
          ImmutableList.of(SCOPE))) {
      CreateMembershipRequest.Builder request = CreateMembershipRequest.newBuilder()
        // replace SPACE_NAME here
        .setParent("spaces/SPACE_NAME")
        .setMembership(Membership.newBuilder()
          .setMember(User.newBuilder()
            // member name for app membership, do not change this.
            .setName("users/app")
            // user type for the membership
            .setType(User.Type.BOT)));
      Membership response = chatServiceClient.createMembership(request.build());

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

Apps Script

chat/advanced-service/Main.gs
/**
 * This sample shows how to create membership with app credential for an app
 * 
 * It relies on the OAuth2 scope 'https://www.googleapis.com/auth/chat.memberships.app'
 * referenced in the manifest file (appsscript.json).
 */
function createMembershipUserCredForApp() {
  // Initialize request argument(s)
  // TODO(developer): Replace SPACE_NAME here.
  const parent = 'spaces/SPACE_NAME';
  const membership = {
    member: {
      // Member name for app membership, do not change this
      name: 'users/app',
      // User type for the membership
      type: 'BOT'
    }
  };

  // Make the request
  const response = Chat.Spaces.Members.create(membership, parent);

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

Ersetzen Sie zum Ausführen des Beispiels SPACE_NAME durch die ID aus dem name des Leerzeichens. Sie können die ID durch Aufrufen der Methode ListSpaces() oder aus der URL des Gruppenbereichs abrufen.

Die Chat API gibt eine Instanz von Membership zurück, die Details zur erstellten Nutzermitgliedschaft enthält.

Nutzer als Chat-App in Gruppenbereiche einladen oder hinzufügen

Für die App-Authentifizierung ist eine einmalige Administratorgenehmigung erforderlich.

Wenn Sie einen Nutzer zu einem Gruppenbereich mit App-Authentifizierung einladen oder hinzufügen möchten, geben Sie in Ihrer Anfrage Folgendes an:

  • Geben Sie den Autorisierungsbereich für chat.app.memberships an.
  • Rufen Sie die Methode create für die Ressource membership auf.
  • Legen Sie für parent den Ressourcennamen des Gruppenbereichs fest, in dem die Mitgliedschaft erstellt werden soll.
  • Legen Sie member auf users/{user} fest. Dabei ist {user} die Person, für die Sie die Mitgliedschaft erstellen möchten. Sie kann folgende Rollen haben:
    • Die ID für die Person in der People API. Wenn beispielsweise people/123456789 der Wert für person resourceName in der People API ist, setzen Sie membership.member.name auf users/123456789.
    • Die ID für den Nutzer in der Directory API.
    • Die E-Mail-Adresse des Nutzers. Beispiel: users/222larabrown@gmail.com oder users/larabrown@cymbalgroup.com. Wenn der Nutzer ein Google-Konto verwendet oder zu einer anderen Google Workspace-Organisation gehört, müssen Sie seine E-Mail-Adresse verwenden.

API-Schlüssel erstellen

Wenn Sie eine API-Methode der Entwicklervorschau aufrufen möchten, müssen Sie eine nicht öffentliche Entwicklervorschauversion des API-Discovery-Dokuments verwenden. Zum Authentifizieren der Anfrage müssen Sie einen API-Schlüssel übergeben.

Öffnen Sie zum Erstellen des API-Schlüssels das Google Cloud-Projekt Ihrer Anwendung und gehen Sie so vor:

  1. Gehen Sie in der Google Cloud Console zu „Menü“  > APIs und Dienste > Anmeldedaten.

    Zu den Anmeldedaten

  2. Klicken Sie auf Anmeldedaten erstellen > API-Schlüssel.
  3. Ihr neuer API-Schlüssel wird angezeigt.
    • Klicken Sie auf „Kopieren“ , um den API-Schlüssel für die Verwendung im Code Ihrer App zu kopieren. Den API-Schlüssel finden Sie auch im Bereich „API-Schlüssel“ der Anmeldedaten Ihres Projekts.
    • Klicken Sie auf Schlüssel einschränken, um die erweiterten Einstellungen zu aktualisieren und die Verwendung des API-Schlüssels einzuschränken. Weitere Informationen finden Sie unter Einschränkungen für API-Schlüssel anwenden.

Skript schreiben, das die Chat API aufruft

Im folgenden Beispiel wird einem Gruppenbereich ein Nutzer mit App-Authentifizierung hinzugefügt:

Python

  1. Erstellen Sie in Ihrem Arbeitsverzeichnis eine Datei mit dem Namen chat_membership_app_create.py.

  2. Fügen Sie in chat_membership_app_create.py den folgenden Code ein:

    from google.oauth2 import service_account
from apiclient.discovery import build

# Define your app's authorization scopes.
# When modifying these scopes, delete the file token.json, if it exists.
SCOPES = ["https://www.googleapis.com/auth/chat.app.memberships"]

def main():
    '''
    Authenticates with Chat API using app authentication,
    then adds a user to a Chat space by creating a membership.
    '''

    # Specify service account details.
    creds = (
        service_account.Credentials.from_service_account_file('credentials.json')
        .with_scopes(SCOPES)
    )

    # Build a service endpoint for Chat API.
    chat = build('chat', 'v1', credentials=creds, discoveryServiceUrl='https://chat.googleapis.com/$discovery/rest?version=v1&labels=DEVELOPER_PREVIEW&key=API_KEY')

    # Use the service endpoint to call Chat API.
    result = chat.spaces().members().create(

        # The space in which to create a membership.
        parent = 'spaces/SPACE',

        # Specify which user the membership is for.
        body = {
          'member': {
            'name':'users/USER',
            'type': 'HUMAN'
          }
        }

    ).execute()

    # Prints details about the created membership.
    print(result)

if __name__ == '__main__':
    main()

  3. Ersetzen Sie im Code Folgendes:

    • API_KEY: Der API-Schlüssel, den Sie zum Erstellen des Dienstendpunkts für die Chat API erstellt haben.

    • SPACE: ein Name des Gruppenbereichs, den Sie über die Methode spaces.list in der Chat API oder aus der URL eines Gruppenbereichs abrufen können.

    • USER: eine Nutzer-ID.

  4. Erstellen und führen Sie das Beispiel in Ihrem Arbeitsverzeichnis aus:

    python3 chat_membership_app_create.py

Als Google Workspace-Administrator Nutzern oder Google-Gruppen Gruppenbereiche hinzufügen

Wenn Sie Google Workspace-Administrator sind, können Sie die Methode create() aufrufen, um einem Gruppenbereich in Ihrer Google Workspace-Organisation Nutzer, Google Groups-Gruppen oder Chat-Apps hinzuzufügen.

So rufen Sie diese Methode als Google Workspace-Administrator auf:

  • Rufen Sie die Methode mit Nutzerauthentifizierung auf und geben Sie einen Autorisierungsbereich an, der den Aufruf der Methode mit Administratorberechtigungen unterstützt.
  • Geben Sie in Ihrer Anfrage den Abfrageparameter useAdminAccess an true.

Weitere Informationen und Beispiele finden Sie unter Google Chat-Gruppenbereiche als Google Workspace-Administrator verwalten.

Einschränkungen und Überlegungen

  • Bei der App-Authentifizierung kann eine Chat-App Nutzer einladen oder hinzufügen, nicht jedoch Google Groups- oder Chat-Apps. Damit eine Chat-App sich selbst hinzufügen kann, muss sie die Nutzerauthentifizierung mit dem Autorisierungsbereich chat.memberships verwenden.