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 beschrieben, 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-Anwendungen können Dienstkonten zur Authentifizierung verwenden, wenn sie die Google Chat API asynchron aufrufen. So können sie:

• Senden Sie mit spaces.messages.create Nachrichten an Google Chat an:
  • Nutzer benachrichtigen, wenn ein lang andauernder Hintergrundjob beendet ist.
  • Nutzer warnen, dass ein Server offline ist.
  • Bitten Sie einen Kundensupport, sich um einen neu eröffneten Kundenfall zu kümmern.
• Aktualisieren Sie zuvor gesendete Nachrichten mit spaces.messages.update in:
  • Status bei laufendem Vorgang ändern.
  • Sie können die für eine Aufgabe zuständige Person oder das Fälligkeitsdatum aktualisieren.
• Listen Sie Nutzer in einem Gruppenbereich mit spaces.members.list auf, um:
  • Sieh nach, wer sich in einem Gruppenbereich befindet.
  • Prüfen Sie, ob alle Mitglieder eines Teams als Mitglied des Gruppenbereichs Mitglied sind.

Bei 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. 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 Ihre 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 gewähren, 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 über Ihr Dienstkonto ausführen, um die Identität eines Nutzerkontos zu übernehmen. Obwohl ein Dienstkonto zur Authentifizierung verwendet wird, wird die domainweite Delegierung der Identität eines Nutzers nachgeahmt und gilt daher als Nutzerauthentifizierung. Für alle Funktionen, für die eine Nutzerauthentifizierung erforderlich ist, können Sie die domainweite Delegierung verwenden.

Weitere Informationen dazu, wann Chatanwendungen eine Authentifizierung erfordern und welche Art von Authentifizierung verwendet werden muss, finden Sie unter Arten erforderlicher Authentifizierung in der Übersicht über die 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. 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 über die 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
• npm-Paketverwaltungstool

• Ein initialisiertes Node.js-Projekt. Zum Initialisieren eines neuen Projekts erstellen Sie einen neuen Ordner, wechseln Sie zu einem neuen Ordner und führen Sie dann den folgenden Befehl über die Befehlszeile aus:

  npm init
  

Apps Script

• Ein Apps Script-Projekt, das mit Ihrem Google Cloud-Projekt verknüpft ist. Informationen zum Initialisieren eines Apps Script-Projekts finden Sie unter Kurzanleitung: Chat-App mit Google Apps Script.

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

1. Öffnen Sie in der Google Cloud Console das Dreistrich-Menü > IAM und Verwaltung > Dienstkonten.

   Zur Seite „Dienstkonten“

2. Klicken Sie auf Dienstkonto erstellen.
3. 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, bearbeiten Sie die ID im Feld „Dienstkonto-ID“.
4. 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.
5. Klicken Sie auf Weiter.
6. 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.
7. Klicken Sie auf Fertig. Notieren Sie sich die E-Mail-Adresse für das Dienstkonto.

gcloud-CLI

1. Erstellen Sie das Dienstkonto:

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

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

Warnung : In diesem Beispiel wird der Einfachheit halber ein exportierter Dienstkontoschlüssel verwendet. In der Produktionsumgebung wird der Export eines privaten Schlüssels nicht empfohlen, da er nicht an einem unsicheren Ort wie Versionsverwaltung gespeichert werden sollte.

Weitere Informationen zu sicheren Implementierungen von Dienstkonten und Best Practices finden Sie unter Festlegen, wann Dienstkonten verwendet werden sollen.

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

1. Öffnen Sie in der Google Cloud Console das Dreistrich-Menü > IAM und Verwaltung > Dienstkonten.

   Zur Seite „Dienstkonten“

2. Wählen Sie Ihr Dienstkonto aus.
3. Klicken Sie auf Schlüssel > Schlüssel hinzufügen > Neuen Schlüssel erstellen.
4. 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.

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

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

Wechseln Sie zum Hinzufügen der Google-Clientbibliotheken zu Ihrem Node.js-Projekt 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:

1. Klicke links auf Editor .
2. Klicken Sie links neben Bibliotheken auf Bibliothek hinzufügen .
3. Geben Sie die Skript-ID 1B7FSrk5Zi6L1rSxxTDgDEUsPzlukDsi4KGuTMorsTQHhGBzBkMun4iDF ein.
4. 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:

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

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

Schritt 3: Script schreiben, das sich mit dem Dienstkonto bei der Chat API authentifiziert

Mit dem folgenden Code wird die Authentifizierung bei der Chat API mit einem Dienstkonto durchgeführt. Anschließend wird eine Nachricht in einem Chatbereich gepostet:

Java

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

2. 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();
       }
   }
   

3. Ersetzen Sie im Code SPACE_NAME durch den Namen eines Gruppenbereichs, den Sie mit der Methode spaces.list in der Chat API oder aus der URL eines Gruppenbereichs abrufen können.

4. Erstellen Sie im Verzeichnis Ihres Projekts ein neues Unterverzeichnis mit dem Namen resources.

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

6. 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 die folgende Konfiguration im Abschnitt <build> hinzu:

   <build>
     <!-- ... existing configurations ... -->
     <resources>
       <resource>
         <directory>resources</directory>
       </resource>
     </resources>
   </build>
   

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

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

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

3. Ersetzen Sie im Code SPACE_NAME durch den Namen eines Gruppenbereichs, 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 Datei mit dem privaten Schlüssel für Ihr Dienstkonto den Namen credentials.json hat.

Node.js

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

2. 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);
   

3. Ersetzen Sie im Code SPACE_NAME durch den Namen eines Gruppenbereichs, 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 Datei mit dem privaten Schlüssel für Ihr Dienstkonto den Namen credentials.json hat.

Apps Script

1. Bearbeiten Sie im Apps Script-Editor die Datei appsscript.json und fügen Sie den OAuth-Bereich hinzu, der erforderlich ist, um externe Anfragen zum Abrufen des OAuth-Tokens des Dienstkontos zu senden:

     "oauthScopes": [
       "https://www.googleapis.com/auth/script.external_request"
     ]
   

2. 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());
   }
   

3. Ersetzen Sie im Code CREDENTIALS durch den Inhalt der Datei credentials.json.

4. Ersetzen Sie im Code SPACE_NAME durch den Namen eines Gruppenbereichs, 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 Antwort eine Nachricht in einem Chatbereich als Chat-App postet.

Fehlerbehebung im 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 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 nicht berechtigt ist, Chatnachrichten im angegebenen Chatbereich zu erstellen.

Fügen Sie die Chat-App dem im Skript angegebenen Chatbereich hinzu, um den Fehler zu beheben.

Weitere Informationen

Weitere Informationen zur Chat API finden Sie in der Referenzdokumentation zur Chat API.