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 werden Sie durch die Erstellung eines Dienstkontos geführt. Anschließend wird gezeigt, wie Sie ein Skript schreiben, das das Dienstkonto verwendet, um sich bei der Chat API zu authentifizieren und eine Nachricht in einem Chatbereich zu posten.

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

Nachrichten mit spaces.messages.create an Google Chat senden an:
- Nutzer werden benachrichtigt, wenn ein lang andauernder Hintergrundjob beendet ist.
- Nutzer warnen, dass ein Server offline ist.
- Bitten Sie einen Kundensupportmitarbeiter, sich um eine neu eröffnete Kundenanfrage zu kümmern.
Aktualisieren Sie zuvor mit spaces.messages.update gesendete Nachrichten auf:
- Ändere den Status eines laufenden Vorgangs.
- Zuständige Person oder Fälligkeitsdatum für eine Aufgabe aktualisieren
Sie können Nutzer in einem Gruppenbereich mit spaces.members.list auflisten, um:
- Sieh dir an, wer in einem Gruppenbereich ist.
- Prüfen Sie, ob alle Mitglieder eines Teams als Mitglied eines Gruppenbereichs Mitglied sind.

Nach der Authentifizierung mit einem Dienstkonto müssen Chat-Apps eine Mitgliedschaft im Gruppenbereich haben, um Daten zu einem Chatbereich abzurufen oder Aktionen in einem Chatbereich auszuführen. Damit beispielsweise die Mitglieder eines Gruppenbereichs aufgelistet oder eine Nachricht in einem Gruppenbereich erstellt werden kann, muss die Chat-App selbst Mitglied des Gruppenbereichs sein.

Wenn die Chat-Anwendung 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 erteilen, um das Dienstkonto einer Anwendung für den Zugriff auf die Daten Ihrer Nutzer zu autorisieren, ohne dass jeder Nutzer seine Zustimmung 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, wird bei der domainweiten Delegierung die Identität eines Nutzers übernommen. Dies gilt daher als Nutzerauthentifizierung. Für alle Funktionen, die eine Nutzerauthentifizierung erfordern, können Sie die domainweite Delegierung verwenden.

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

Voraussetzungen

Zum Ausführen des Beispiels in diesem Leitfaden 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. Informationen zum Erstellen eines Projekts und zum Aktivieren einer API finden 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 Maven-Paketverwaltungstool

Ein initialisiertes Maven-Projekt. Führen Sie den folgenden Befehl in der Befehlszeile 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 Paketverwaltungstool npm
Ein initialisiertes Node.js-Projekt. Um ein neues Projekt zu initialisieren, erstellen Sie einen neuen Ordner, wechseln Sie dorthin und führen Sie dann den folgenden Befehl in der Befehlszeile 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 Google Apps Script Chat App – Kurzanleitung.

Schritt 1: Dienstkonto in der Google Cloud Console erstellen

Erstellen Sie ein Dienstkonto, mit dem Ihre 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: Standardmäßig erstellt Google eine eindeutige Dienstkonto-ID. Wenn Sie die ID ändern möchten, passen Sie sie im Feld „Dienstkonto-ID“ an.
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 für das Dienstkonto.

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. Erstellen Sie als Nächstes einen privaten Schlüssel für das Dienstkonto.

Privaten Schlüssel erstellen

So erstellen Sie einen privaten Schlüssel für das Dienstkonto und laden ihn 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 des Schlüssels finden Sie unter Dienstkontoschlüssel verwalten.
Klicken Sie auf Schließen.

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

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

Um Ihrem Maven-Projekt die Google-Clientbibliotheken und andere erforderliche Abhängigkeiten hinzuzufügen, 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

Wenn Sie Ihrem Node.js-Projekt die Google-Clientbibliotheken hinzufügen möchten, wechseln Sie in das Verzeichnis Ihres Projekts und führen Sie den folgenden Befehl über die Befehlszeile 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 Chat-Dienst zum Aufrufen der Google Chat API verwendet. 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: Script schreiben, das das Dienstkonto zur Authentifizierung bei der Chat API verwendet

Der folgende Code wird mit einem Dienstkonto 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 mit der Methode spaces.list in der Chat API oder aus der URL eines Gruppenbereichs abrufen können.
Erstellen Sie im Verzeichnis Ihres Projekts ein neues Unterverzeichnis mit dem Namen resources.
Achten Sie darauf, dass die private Schlüsseldatei für Ihr Dienstkonto den Namen credentials.json hat, und kopieren Sie sie in das Unterverzeichnis resources.
Wenn Sie Maven so konfigurieren möchten, 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 im Abschnitt <build> die folgende Konfiguration 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 der Anwendung ausgeführt wird, bearbeiten Sie die Datei pom.xml im Verzeichnis Ihres Projekts und fügen Sie die folgende Konfiguration im Abschnitt <plugins> hinzu:

<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 mit der Methode spaces.list in der Chat API oder aus der URL eines Gruppenbereichs abrufen können. Achten Sie darauf, dass die private Schlüsseldatei 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 mit der Methode spaces.list in der Chat API oder aus der URL eines Gruppenbereichs abrufen können. Achten Sie darauf, dass die private Schlüsseldatei 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 erforderlichen OAuth-Bereich für externe Anfragen zum Abrufen des OAuth-Tokens des Dienstkontos hinzu:
```
  "oauthScopes": [
    "https://www.googleapis.com/auth/script.external_request"
  ]
```

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

// 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 mit der Methode spaces.list in der Chat API oder aus der 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 als Chat-App eine Nachricht in einem Chatbereich postet.

Fehler im Beispiel beheben

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 wird möglicherweise folgende Fehlermeldung angezeigt:

<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.

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