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() für die Ressource Membership der Google Chat API einen Nutzer, eine Google-Gruppe oder eine Chat-App in einen Gruppenbereich einladen oder hinzufügen. Dies wird auch als Erstellen einer Mitgliedschaft bezeichnet. Wenn Sie eine Mitgliedschaft erstellen und die angegebene Person die Richtlinie zum automatischen Akzeptieren deaktiviert hat, wird sie eingeladen und muss die Einladung für den Bereich annehmen, bevor sie beitreten kann. Andernfalls wird das Mitglied durch das Erstellen einer Mitgliedschaft direkt dem angegebenen Gruppenbereich hinzugefügt.

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

Die Membership-Ressource gibt an, ob ein menschlicher Nutzer oder eine Google Chat-App zu einem Gruppenbereich eingeladen wurde, Teil eines Gruppenbereichs ist oder nicht.

Vorbereitung

Node.js

Python

Java

Apps Script

Nutzer als Nutzer in einen Gruppenbereich einladen oder hinzufügen

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

  • Geben Sie den chat.memberships-Autorisierungsbereich 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 HUMAN gesetzt.
    • Das Feld name ist auf users/{user} festgelegt, wobei {user} die Person ist, die Sie dem Gruppenbereich hinzufügen möchten. Wenn Sie den Chatnutzer angeben möchten, ersetzen Sie {user} durch einen der folgenden Werte:
      • Die ID für die Person in der People API. Wenn beispielsweise die People API-person-resourceName 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 ein Nutzer mit Nutzerauthentifizierung einem Bereich 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);
}

So führen Sie das Beispiel aus:

  • SPACE_NAME: Die ID aus dem name des Bereichs. Sie können die ID abrufen, indem Sie die Methode ListSpaces() aufrufen oder die URL des Bereichs verwenden.
  • USER_NAME: eine Nutzer-ID.

Die Chat API gibt eine Instanz von Membership zurück, in der die erstellte Mitgliedschaft des Nutzers beschrieben wird.

Google-Gruppen in einen Gruppenbereich einladen oder hinzufügen

Wenn Sie eine Google-Gruppe in einen Gruppenbereich mit Nutzerauthentifizierung einladen oder hinzufügen möchten (App-Authentifizierung unterstützt das Einladen oder Hinzufügen einer Google-Gruppe in einen Gruppenbereich nicht), übergeben Sie Folgendes in Ihrer Anfrage:

  • Geben Sie den chat.memberships-Autorisierungsbereich 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 name von groupMember auf groups/{group} festgelegt ist. {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.

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

Im folgenden Beispiel wird eine Gruppe einem benannten Bereich mit Nutzerauthentifizierung 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);
}

So führen Sie das Beispiel aus:

  • SPACE_NAME: Die ID aus dem name des Bereichs. Sie können die ID abrufen, indem Sie die Methode ListSpaces() aufrufen oder die URL des Bereichs verwenden.
  • GROUP_NAME: eine Gruppen-ID.

Die Chat API gibt eine Instanz von Membership zurück, in der die erstellte Mitgliedschaft des Nutzers beschrieben wird.

Chat-App zu einem Gruppenbereich hinzufügen

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

  • Geben Sie den chat.memberships.app-Autorisierungsbereich 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. Dies ist ein Alias, der die App darstellt, die die Chat API aufruft.

Im folgenden Beispiel wird einem Bereich 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 SPACE_NAME durch die ID aus dem name des Bereichs, um das Beispiel auszuführen. Sie können die ID abrufen, indem Sie die Methode ListSpaces() aufrufen oder die URL des Bereichs verwenden.

Die Chat API gibt eine Instanz von Membership zurück, in der die erstellte Mitgliedschaft des Nutzers beschrieben wird.

Nutzer als Chat-App in einen Gruppenbereich einladen oder hinzufügen

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

Wenn Sie einen Nutzer mit App-Authentifizierung in einen Bereich einladen oder hinzufügen möchten, übergeben Sie Folgendes in Ihrer Anfrage:

  • Geben Sie den chat.app.memberships-Autorisierungsbereich an.
  • Rufen Sie die Methode create für die Ressource membership auf.
  • Legen Sie parent auf den Ressourcennamen des Bereichs fest, in dem die Mitgliedschaft erstellt werden soll.
  • Setzen Sie member auf users/{user}, wobei {user} die Person ist, für die Sie eine Mitgliedschaft erstellen möchten. {user} kann Folgendes sein:
    • Die ID für die Person in der People API. Wenn beispielsweise die People API-person-resourceName people/123456789 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 Developer Preview-API-Methode aufrufen möchten, müssen Sie eine nicht öffentliche Developer Preview-Version des API-Erkennungsdokuments verwenden. Zur Authentifizierung der Anfrage müssen Sie einen API-Schlüssel übergeben.

So erstellen Sie den API-Schlüssel: Öffnen Sie das Google Cloud-Projekt Ihrer App und gehen Sie so vor:

  1. Rufen Sie in der Google Cloud Console das Menü  > APIs und Dienste > Anmeldedaten auf.

    Zu den Anmeldedaten

  2. Klicken Sie auf Anmeldedaten erstellen > API-Schlüssel.
  3. Der neue API-Schlüssel wird angezeigt.
    • Klicken Sie auf „Kopieren“ , um den API-Schlüssel zu kopieren und im Code Ihrer App zu verwenden. Der API-Schlüssel ist auch im Bereich „API-Schlüssel“ der Anmeldedaten Ihres Projekts zu finden.
    • Klicken Sie auf Schlüssel einschränken, um die erweiterten Einstellungen zu aktualisieren und die Verwendung Ihres 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 ein Nutzer mit App-Authentifizierung einem Bereich hinzugefügt:

Python

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

  2. Fügen Sie den folgenden Code in chat_membership_app_create.py 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 Bereichsname, den Sie über die Methode spaces.list in der Chat API oder über die URL eines Bereichs abrufen können.

    • USER: eine Nutzer-ID.

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

    python3 chat_membership_app_create.py

Als Google Workspace-Administrator Nutzer oder Google-Gruppen einem Gruppenbereich hinzufügen

Als Google Workspace-Administrator können Sie die Methode create() aufrufen, um Nutzer, Google-Gruppen oder Chat-Apps zu einem beliebigen Bereich in Ihrer Google Workspace-Organisation hinzuzufügen.

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

  • Rufen Sie die Methode mit der 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 als true an.

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

Einschränkungen und Überlegungen

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