Diese Seite wurde von der Cloud Translation API übersetzt.

Als Google Chat-App authentifizieren

In dieser Anleitung wird erläutert, wie Sie ein Dienstkonto einrichten und verwenden, um im Namen einer Chat-App auf die Google Chat API zuzugreifen. Zuerst wird erläutert, wie Sie ein Dienstkonto erstellen. Anschließend wird gezeigt, wie Sie ein Skript schreiben, das das Dienstkonto zur Authentifizierung bei der Chat API verwendet und eine Nachricht in einem Chatbereich postet.

Chat-Apps können Dienstkonten zur Authentifizierung verwenden, wenn sie die Google Chat API asynchron aufrufen, damit sie Folgendes tun können:

Senden Sie Nachrichten an Google Chat mit spaces.messages.create an:
- Benachrichtigen Sie Nutzer, wenn ein Hintergrundjob mit langer Ausführungszeit abgeschlossen ist.
- Benachrichtigen Sie Nutzer, dass ein Server offline ist.
- Bitten Sie einen Kundendienstmitarbeiter, sich um eine neu eröffnete Kundenanfrage zu kümmern.
Aktualisieren Sie zuvor gesendete Nachrichten mit spaces.messages.update auf:
- Ändere den Status von "Im laufenden Vorgang".
- Aktualisieren Sie die zuständige Person oder das Fälligkeitsdatum einer Aufgabe.
Zum Auflisten von Nutzern in einem Gruppenbereich mit spaces.members.list haben Sie folgende Möglichkeiten:
- Sehen, wer sich in einem Gruppenbereich befindet
- Prüfen Sie, ob alle Teammitglieder in einem Gruppenbereich Mitglied sind.

Bei der Authentifizierung mit einem Dienstkonto müssen Chat-Apps eine Mitgliedschaft im Bereich haben, um Daten zu einem Chatbereich abzurufen oder Aktionen in diesem Bereich ausführen zu können. Wenn Sie beispielsweise die Mitglieder eines Gruppenbereichs auflisten oder eine Nachricht in einem Gruppenbereich erstellen möchten, muss die Chat-App selbst Mitglied des Gruppenbereichs sein.

Wenn die Chat-App auf Nutzerdaten zugreifen oder Aktionen im Namen eines Nutzers ausführen muss, authentifizieren Sie sich stattdessen als Nutzer.

Als Domainadministrator können Sie eine domainweite Delegierung von Befugnissen gewähren, um das Dienstkonto einer Anwendung für den Zugriff auf die Daten Ihrer Nutzer zu autorisieren, ohne dass jeder Nutzer seine Einwilligung geben muss. Nachdem Sie die domainweite Delegierung konfiguriert haben, können Sie API-Aufrufe mit Ihrem Dienstkonto ausführen, um die Identität eines Nutzerkontos zu übernehmen. Obwohl ein Dienstkonto zur Authentifizierung verwendet wird, gibt die domainweite Delegierung die Identität eines Nutzers an und gilt daher als Nutzerauthentifizierung. Für alle Funktionen, die eine Nutzerauthentifizierung erfordern, können Sie die domainweite Delegierung verwenden.

Weitere Informationen dazu, wann Chat-Apps eine Authentifizierung erfordern und welche Art von Authentifizierung verwendet werden soll, finden Sie unter Arten der erforderlichen Authentifizierung in der Übersicht zu Authentifizierung und Autorisierung der Chat API.

Voraussetzungen

Zum Ausführen des Beispiels in dieser Anleitung müssen die folgenden Voraussetzungen erfüllt sein:

Ein Google Workspace-Konto mit Zugriff auf Google Chat .
Ein Google Cloud-Projekt mit aktivierter Chat API. Wie Sie ein Projekt erstellen und eine API aktivieren, erfahren Sie unter Projekt erstellen und API aktivieren.
Eine veröffentlichte Chat-App mit Mitgliedschaft in einem Chatbereich:
- Informationen zum Erstellen und Veröffentlichen einer Chat-App finden Sie unter Google Chat-App mit Cloud Functions erstellen.
- Informationen zum Hinzufügen einer Chat-App zu einem Chatbereich finden Sie unter Apps zu Gruppenbereichen oder Unterhaltungen in Google Chat hinzufügen.

Außerdem müssen die folgenden sprachspezifischen Voraussetzungen erfüllt sein:

Java

JDK 1.7 oder höher
Das Paketverwaltungstool Maven

Ein initialisiertes Maven-Projekt. Führen Sie in der Befehlszeile den folgenden Befehl aus, um ein neues Projekt zu initialisieren:

mvn archetype:generate -DgroupId=com.google.chat.app.authsample -DartifactId=auth-sample-app -DarchetypeArtifactId=maven-archetype-quickstart -DarchetypeVersion=1.4 -DinteractiveMode=false

Python

Python 3.6 oder höher
Das Paketverwaltungstool pip

Node.js

Node.js
Das npm-Paketverwaltungstool
Ein initialisiertes Node.js-Projekt. Zum Initialisieren eines neuen Projekts müssen Sie einen neuen Ordner erstellen und dorthin wechseln. Führen Sie dann in der Befehlszeile den folgenden Befehl aus:
```
npm init
```

Apps Script

Ein Apps Script-Projekt, das mit Ihrem Google Cloud-Projekt verbunden ist. Informationen zum Initialisieren eines Apps Script-Projekts finden Sie unter Kurzanleitung zur Google Apps Script Chat-App.

Schritt 1: Dienstkonto in der Google Cloud Console erstellen

Erstelle ein Dienstkonto, mit dem deine Chat-App auf Google APIs zugreifen kann.

Dienstkonto erstellen

So erstellen Sie ein Dienstkonto:

Google Cloud Console

Öffnen Sie in der Google Cloud Console das Dreistrich-Menü > IAM und Verwaltung > Dienstkonten.
Zur Seite „Dienstkonten“
Klicken Sie auf Dienstkonto erstellen.
Geben Sie die Dienstkontodetails ein und klicken Sie dann auf Erstellen und fortfahren.
Hinweis: Google erstellt standardmäßig eine eindeutige Dienstkonto-ID. Wenn Sie die ID ändern möchten, können Sie sie im Feld „Dienstkonto-ID“ anpassen.
Optional: Weisen Sie Ihrem Dienstkonto Rollen zu, um Zugriff auf die Ressourcen Ihres Google Cloud-Projekts zu gewähren. Weitere Informationen finden Sie unter Zugriff auf Ressourcen erteilen, ändern und entziehen.
Klicken Sie auf Weiter.
Optional: Geben Sie Nutzer oder Gruppen ein, die Aktionen mit diesem Dienstkonto verwalten und ausführen können. Weitere Informationen finden Sie unter Identitätswechsel für Dienstkonten verwalten.
Klicken Sie auf Fertig. Notieren Sie sich die E-Mail-Adresse des Dienstkontos.

gcloud-CLI

Erstellen Sie das Dienstkonto:

gcloud iam service-accounts create SERVICE_ACCOUNT_NAME \
  --display-name="SERVICE_ACCOUNT_NAME"

Optional: Weisen Sie Ihrem Dienstkonto Rollen zu, um Zugriff auf die Ressourcen Ihres Google Cloud-Projekts zu gewähren. Weitere Informationen finden Sie unter Zugriff auf Ressourcen erteilen, ändern und entziehen.

Das Dienstkonto wird auf der Dienstkontoseite angezeigt. Als Nächstes erstellen Sie einen privaten Schlüssel für das Dienstkonto.

Privaten Schlüssel erstellen

So erstellen und laden Sie einen privaten Schlüssel für das Dienstkonto herunter:

Öffnen Sie in der Google Cloud Console das Dreistrich-Menü > IAM und Verwaltung > Dienstkonten.
Zur Seite „Dienstkonten“
Wählen Sie Ihr Dienstkonto aus.
Klicken Sie auf Schlüssel > Schlüssel hinzufügen > Neuen Schlüssel erstellen.
Wählen Sie JSON aus und klicken Sie dann auf Erstellen.
Ihr neues öffentliches/privates Schlüsselpaar wird generiert und als neue Datei auf Ihren Computer heruntergeladen. Speichern Sie die heruntergeladene JSON-Datei als credentials.json in Ihrem Arbeitsverzeichnis. Diese Datei ist die einzige Kopie dieses Schlüssels. Informationen zum sicheren Speichern deines Schlüssels findest du unter Dienstkontoschlüssel verwalten.
Klicken Sie auf Schließen.

Weitere Informationen zu Dienstkonten finden Sie unter Dienstkonten in der Google Cloud IAM-Dokumentation.

Schritt 2: Google-Clientbibliothek und andere Abhängigkeiten installieren

Installieren Sie die Google-Clientbibliothek und andere Abhängigkeiten, die für das Projekt erforderlich sind.

Java

Wenn Sie Ihrem Maven-Projekt die Google-Clientbibliotheken und andere erforderliche Abhängigkeiten hinzufügen möchten, bearbeiten Sie die Datei pom.xml im Verzeichnis Ihres Projekts und fügen Sie die folgenden Abhängigkeiten hinzu:

<dependencies>
  <!-- ... existing dependencies ... -->
  <dependency>
    <groupId>com.google.apis</groupId>
    <artifactId>google-api-services-chat</artifactId>
    <version>v1-rev20230905-2.0.0</version>
  </dependency>
  <dependency>
    <groupId>com.google.auth</groupId>
    <artifactId>google-auth-library-oauth2-http</artifactId>
    <version>1.19.0</version>
  </dependency>
  <dependency>
      <groupId>com.google.code.gson</groupId>
      <artifactId>gson</artifactId>
      <version>2.10.1</version>
  </dependency>
</dependencies>

Python

Wenn Sie die Google-Clientbibliotheken für Python noch nicht installiert haben, führen Sie den folgenden Befehl in der Befehlszeile aus:

pip3 install --upgrade google-api-python-client google-auth

Node.js

Um Ihrem Node.js-Projekt die Google-Clientbibliotheken hinzuzufügen, wechseln Sie in das Verzeichnis Ihres Projekts und führen Sie in der Befehlszeile den folgenden Befehl aus:

npm install "@googleapis/chat"

Apps Script

In diesem Beispiel wird die OAuth2-Bibliothek für Apps Script verwendet, um ein JWT-Token für die Dienstkontoauthentifizierung zu generieren. So fügen Sie die Bibliothek Ihrem Apps Script-Projekt hinzu:

Klicken Sie links auf Editor .
Klicken Sie links neben Bibliotheken auf Bibliothek hinzufügen .
Geben Sie die Skript-ID 1B7FSrk5Zi6L1rSxxTDgDEUsPzlukDsi4KGuTMorsTQHhGBzBkMun4iDF ein.
Klicken Sie auf Suchen und dann auf Hinzufügen.

In diesem Beispiel wird der erweiterte Chatdienst verwendet, um die Google Chat API aufzurufen. So aktivieren Sie den Dienst für Ihr Apps Script-Projekt:

Klicken Sie links auf Editor .
Klicken Sie links neben Dienste auf Dienst hinzufügen .
Wählen Sie Google Chat API aus.
Wählen Sie unter Version die Option v1 aus.
Klicken Sie auf Hinzufügen.

Sie können jede von unseren Clientbibliotheken unterstützte Sprache verwenden.

Schritt 3: Skript schreiben, das das Dienstkonto zur Authentifizierung bei der Chat API verwendet

Mit dem folgenden Code wird mithilfe eines Dienstkontos bei der Chat API authentifiziert und dann eine Nachricht in einem Chatbereich gepostet:

Java

Öffnen Sie im Verzeichnis Ihres Projekts die Datei src/main/java/com/google/chat/app/authsample/App.java.

Ersetzen Sie den Inhalt in App.java durch den folgenden Code:

package com.google.chat.app.authsample;

import com.google.api.client.googleapis.javanet.GoogleNetHttpTransport;
import com.google.api.client.http.HttpRequestInitializer;
import com.google.api.client.json.gson.GsonFactory;
import com.google.api.services.chat.v1.HangoutsChat;
import com.google.api.services.chat.v1.model.Message;
import com.google.auth.http.HttpCredentialsAdapter;
import com.google.auth.oauth2.GoogleCredentials;

/**
 * Authenticates with Chat API via service account credentials,
 * then creates a Chat message.
 */
public class App {
    // Specify required scopes.
    private static final String CHAT_SCOPE = "https://www.googleapis.com/auth/chat.bot";

    // Specify service account details.
    private static final String PRIVATE_KEY_RESOURCE_URI = "/credentials.json";

    public static void main( String[] args ) {
        try {
            // Run app.
            Message response = App.createChatMessage();
            // Print details about the created message.
            System.out.println(response);
        } catch (Exception e) {
            e.printStackTrace();
        }
    }

    private static Message createChatMessage() throws Exception {
        // Build the Chat API client and authenticate with the service account.
        GoogleCredentials credentials = GoogleCredentials.fromStream(
            App.class.getResourceAsStream(PRIVATE_KEY_RESOURCE_URI))
            .createScoped(CHAT_SCOPE);
        HttpRequestInitializer requestInitializer = new HttpCredentialsAdapter(credentials);
        HangoutsChat chatService = new HangoutsChat.Builder(
            GoogleNetHttpTransport.newTrustedTransport(),
            GsonFactory.getDefaultInstance(),
            requestInitializer)
            .setApplicationName("auth-sample-app")
            .build();

        // The space to create the message in.
        //
        // Replace SPACE_NAME with a space name.
        // Obtain the space name from the spaces resource of Chat API,
        // or from a space's URL.
        String spaceName = "spaces/SPACE_NAME";

        // Create a Chat message.
        Message message = new Message().setText("Hello, world!");
        return chatService.spaces().messages().create(spaceName, message).execute();
    }
}

Ersetzen Sie im Code SPACE_NAME durch einen Namen für den Gruppenbereich, den Sie über die Methode spaces.list in der Chat API oder über die URL eines Gruppenbereichs abrufen können.
Erstellen Sie im Verzeichnis Ihres Projekts ein neues Unterverzeichnis mit dem Namen resources.
Achten Sie darauf, dass die Datei mit dem privaten Schlüssel für Ihr Dienstkonto den Namen credentials.json hat, und kopieren Sie sie in das Unterverzeichnis resources.
Um Maven so zu konfigurieren, dass die Datei mit dem privaten Schlüssel in das Projektpaket aufgenommen wird, bearbeiten Sie die Datei pom.xml im Verzeichnis Ihres Projekts und fügen Sie die folgende Konfiguration im Abschnitt <build> hinzu:
```
<build>
  
  <resources>
    <resource>
      <directory>resources</directory>
    </resource>
  </resources>
</build>
```

Wenn Sie Maven so konfigurieren möchten, dass die Abhängigkeiten in das Projektpaket aufgenommen und die Hauptklasse Ihrer Anwendung ausgeführt wird, bearbeiten Sie die Datei pom.xml im Verzeichnis Ihres Projekts und fügen Sie die folgende Konfiguration in den Abschnitt <plugins> ein:

<plugins>
  <!-- ... existing configurations ... -->
  <plugin>
    <artifactId>maven-assembly-plugin</artifactId>
    <configuration>
      <archive>
        <manifest>
          <mainClass>com.google.chat.app.authsample.App</mainClass>
        </manifest>
      </archive>
      <descriptorRefs>
        <descriptorRef>jar-with-dependencies</descriptorRef>
      </descriptorRefs>
    </configuration>
  </plugin>
</plugins>

Python

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

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

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

# Specify required scopes.
SCOPES = ['https://www.googleapis.com/auth/chat.bot']

# Specify service account details.
CREDENTIALS = service_account.Credentials.from_service_account_file(
    'credentials.json', scopes=SCOPES)

# Build the URI and authenticate with the service account.
chat = build('chat', 'v1', credentials=CREDENTIALS)

# Create a Chat message.
result = chat.spaces().messages().create(

    # The space to create the message in.
    #
    # Replace SPACE_NAME with a space name.
    # Obtain the space name from the spaces resource of Chat API,
    # or from a space's URL.
    parent='spaces/SPACE_NAME',

    # The message to create.
    body={'text': 'Hello, world!'}

).execute()

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

Ersetzen Sie im Code SPACE_NAME durch einen Namen für den Gruppenbereich, den Sie über die Methode spaces.list in der Chat API oder über die URL eines Gruppenbereichs abrufen können. Achten Sie darauf, dass die Datei mit dem privaten Schlüssel für Ihr Dienstkonto den Namen credentials.json hat.

Node.js

Erstellen Sie im Verzeichnis Ihres Projekts eine Datei mit dem Namen chat_app_auth.js.

Fügen Sie den folgenden Code in chat_app_auth.js ein:

const chat = require('@googleapis/chat');

async function createMessage() {
  const auth = new chat.auth.GoogleAuth({

    // Specify service account details.
    keyFilename: 'credentials.json',

    // Specify required scopes.
    scopes: ['https://www.googleapis.com/auth/chat.bot']

  });
  const authClient = await auth.getClient();

  // Create the Chat API client and authenticate with the service account.
  const chatClient = await chat.chat({
    version: 'v1',
    auth: authClient
  });

  // Create a Chat message.
  const result = await chatClient.spaces.messages.create({

    // The space to create the message in.
    //
    // Replace SPACE_NAME with a space name.
    // Obtain the space name from the spaces resource of Chat API,
    // or from a space's URL.
    parent: 'spaces/SPACE_NAME',

    // The message to create.
    requestBody: { 'text': 'Hello, world!' }

  });
  return result;
}

// Execute function then print details about the created message.
createMessage().then(console.log);

Ersetzen Sie im Code SPACE_NAME durch einen Namen für den Gruppenbereich, den Sie über die Methode spaces.list in der Chat API oder über die URL eines Gruppenbereichs abrufen können. Achten Sie darauf, dass die Datei mit dem privaten Schlüssel für Ihr Dienstkonto den Namen credentials.json hat.

Apps Script

Bearbeiten Sie im Apps Script-Editor die Datei appsscript.json und fügen Sie den OAuth-Bereich hinzu, der für externe Anfragen zum Abrufen des OAuth-Tokens des Dienstkontos erforderlich ist:
```
  "oauthScopes": [
    "https://www.googleapis.com/auth/script.external_request"
  ]
```

Speichern Sie den folgenden Code in Ihrem Apps Script-Projekt in einer Datei mit dem Namen ChatAppAuth.gs:

// Specify the contents of the file credentials.json.
const CREDENTIALS = CREDENTIALS;

const SCOPE = 'https://www.googleapis.com/auth/chat.bot';

// The space to create the message in.
//
// Replace SPACE_NAME with a space name.
// Obtain the space name from the spaces resource of Chat API,
// or from a space's URL.
const PARENT = 'spaces/SPACE_NAME'

/**
 * Authenticates with Chat API via app credentials, then posts a message.
 */
function createMessageWithAppCredentials() {
  try {
    const service = getService_();
    if (!service.hasAccess()) {
      console.error(service.getLastError());
      return;
    }

    // Specify the message to create.
    const message = {'text': 'Hello world!'};

    // Call Chat API with a service account to create a message.
    const result = Chat.Spaces.Messages.create(
        message,
        PARENT,
        {},
        // Authenticate with the service account token.
        {'Authorization': 'Bearer ' + service.getAccessToken()});

    // Log details about the created message.
    console.log(result);

  } catch (err) {
    // TODO (developer) - Handle exception.
    console.log('Failed to create message with error %s', err.message);
  }
}

/**
 * Configures the OAuth library to authenticate with the service account.
 */
function getService_() {
  return OAuth2.createService(CREDENTIALS.client_email)
      .setTokenUrl('https://oauth2.googleapis.com/token')
      .setPrivateKey(CREDENTIALS.private_key)
      .setIssuer(CREDENTIALS.client_email)
      .setSubject(CREDENTIALS.client_email)
      .setScope(SCOPE)
      .setPropertyStore(PropertiesService.getScriptProperties());
}

Ersetzen Sie im Code CREDENTIALS durch den Inhalt der Datei credentials.json.
Ersetzen Sie im Code SPACE_NAME durch einen Namen für den Gruppenbereich, den Sie über die Methode spaces.list in der Chat API oder über die URL eines Gruppenbereichs abrufen können.

Schritt 4: Vollständiges Beispiel ausführen

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

Java

mvn compile assembly:single
java -jar target/auth-sample-app-1.0-SNAPSHOT-jar-with-dependencies.jar

Python

python3 chat_app_auth.py

Node.js

node chat_app_auth.js

Apps Script

Öffnen Sie die Datei ChatAppAuth.gs im Apps Script Editor und klicken Sie auf Ausführen.

Ihr Skript stellt eine authentifizierte Anfrage an die Chat API, die mit einer Nachricht in einem Chatbereich als Chat-App antwortet.

Fehlerbehebung für das Beispiel

In diesem Abschnitt werden häufige Probleme beschrieben, die beim Ausführen dieses Beispiels auftreten können.

Du bist nicht berechtigt, diese App zu verwenden

Beim Ausführen des Skripts erhalten Sie möglicherweise folgende Fehlermeldung:

<HttpError 403 when requesting https://chat.googleapis.com/v1/spaces/{space}/messages?alt=json returned "You are not permitted to use this app". Details: "You are not permitted to use this app">

Diese Fehlermeldung bedeutet, dass die Chat-App keine Berechtigung zum Erstellen von Chatnachrichten im angegebenen Chatbereich hat.

Zur Behebung des Fehlers fügen Sie die Chat-App dem im Skript angegebenen Chatbereich hinzu.

Informationen zu den weiteren Funktionen der Chat API finden Sie in der Referenzdokumentation zur Chat API.