Chat-App mit anderen Diensten und Tools verbinden

Auf dieser Seite wird beschrieben, wie Sie eine Google Chat-App mit einem Dienst oder Tool außerhalb von Google Chat verbinden. Chat-Apps sind zwar leistungsstark, funktionieren aber oft in Verbindung mit anderen Systemen und erfordern Begleit-Apps, um Konten zu verknüpfen, den Datenzugriff zu autorisieren, zusätzliche Daten anzuzeigen oder Nutzereinstellungen zu konfigurieren.

Wenn Sie Nutzer mit einem Drittanbieterdienst oder OAuth-Ablauf authentifizieren möchten, führt Ihre Chat-App die folgenden Schritte aus:

  1. Erkennen, wann eine Autorisierung oder Konfiguration erforderlich ist:
  2. Eine einfache Autorisierungskarte zurückgeben, die den Nutzer auffordert, sich anzumelden oder den Dienst zu konfigurieren.
  3. Weiterleitung zum Abschluss-URI, damit Google Chat die ursprüngliche Interaktion automatisch noch einmal versucht, nachdem der Nutzer die Autorisierung abgeschlossen hat.

Architektur der Authentifizierung von Google Chat-Apps bei einem Drittanbieterdienst.

Vorbereitung

HTTP

Eine Google Chat-App, die Nutzerinteraktionen empfängt und darauf reagiert. Kurzanleitung für HTTP

Apps Script

Eine Google Chat-App, die Nutzerinteraktionen empfängt und darauf reagiert. Apps Script-Kurzanleitung

Erkennen, dass eine Autorisierung erforderlich ist

Wenn Nutzer mit Ihrer Chat-App interagieren, sind sie möglicherweise aus verschiedenen Gründen nicht berechtigt, auf eine geschützte Ressource zuzugreifen, z. B. aus den folgenden:

  • Es wurde noch kein Zugriffstoken für die Verbindung zum Drittanbieterdienst generiert oder das Token ist abgelaufen.
  • Das Zugriffstoken deckt die angeforderte Ressource nicht ab.
  • Das Zugriffstoken umfasst nicht die für die Anfrage erforderlichen Bereiche.

Ihre Chat-App sollte diese Fälle erkennen, damit sich Nutzer anmelden und den Zugriff auf Ihren Dienst autorisieren können.

Wenn Sie Apps Script verwenden, können Sie die OAuth2 for Google Apps Script-Bibliothek (oder die OAuth1-Version) verwenden. Dort prüft die Funktion hasAccess, ob der Nutzer den Zugriff auf einen Dienst autorisiert hat. Alternativ können Sie bei Verwendung von UrlFetchApp.fetch-Anfragen den Parameter muteHttpExceptions auf true setzen, um den Antwortcode und den Inhalt des zurückgegebenen HttpResponse-Objekts zu prüfen.

Nutzer mit einer einfachen Autorisierungskarte auffordern

Wenn Ihre Chat-App erkennt, dass eine Autorisierung oder Konfiguration erforderlich ist, geben Sie eine AuthorizationError-Antwort zurück, um dem Nutzer eine private grundlegende Autorisierungskarte anzuzeigen.

Das folgende Bild zeigt ein Beispiel für die grundlegende Autorisierungskarte von Google:

Einfache Autorisierungsaufforderung für das Beispielkonto
Abbildung 1: Einfacher Autorisierungsprompt für das Beispielkonto. In der Aufforderung wird darauf hingewiesen, dass die Chat-App zusätzliche Informationen anzeigen möchte, dafür aber die Genehmigung des Nutzers für den Zugriff auf das Konto benötigt.

Wenn Sie Nutzern eine einfache Autorisierungskarte präsentieren möchten, geben Sie ein AuthorizationError-Objekt zurück:

HTTP

Gib die folgende JSON-Antwort zurück:

{
  "basic_authorization_prompt": {
    "authorization_url": "<var>AUTHORIZATION_URL</var>",
    "resource": "<var>RESOURCE_DISPLAY_NAME</var>"
  }
}

Apps Script

CardService.newAuthorizationException()
    .setAuthorizationUrl('<var>AUTHORIZATION_URL</var>')
    .setResourceDisplayName('<var>RESOURCE_DISPLAY_NAME</var>')
    .throwException();

Ersetzen Sie Folgendes:

  • AUTHORIZATION_URL: Die HTTPS-URL für die Web-App, die die Authentifizierung, Autorisierung oder Konfiguration übernimmt.
  • RESOURCE_DISPLAY_NAME: Der Anzeigename für die geschützte Ressource oder den geschützten Dienst. Dieser Name wird dem Nutzer im Autorisierungs-Prompt angezeigt. Wenn Ihr RESOURCE_DISPLAY_NAME beispielsweise Example Account ist, wird in der Aufforderung angezeigt, dass die App eine Genehmigung für den Zugriff auf Ihr Example Account benötigt.

Konfigurationsanfrage abschließen

In Chat kann der Nutzer den Autorisierungsprozess abschließen und Chat kann die ursprüngliche Interaktion automatisch noch einmal versuchen, ohne dass eine manuelle Aktualisierung erforderlich ist. Chat unterstützt automatische Wiederholungen, wenn der Auslöser Nachricht, Dem Gruppenbereich hinzugefügt oder App-Befehl ist.

Bei diesen Triggern erhält Ihre Chat-App in der Ereignis-Payload einen Abschluss-Weiterleitungs-URI (configCompleteRedirectUri / completeRedirectUri):

  • Nachricht: chat.messagePayload.configCompleteRedirectUri
  • Dem Gruppenbereich hinzugefügt: chat.addedToSpacePayload.configCompleteRedirectUri
  • App-Befehl: chat.appCommandPayload.configCompleteRedirectUri

Sie müssen diesen Weiterleitungs-URI in Ihrem <var>AUTHORIZATION_URL</var> codieren und den Browser des Nutzers nach Abschluss des Autorisierungsvorgangs dorthin weiterleiten. Die Weiterleitung zu dieser URL signalisiert Google Chat, dass die Autorisierungs- oder Konfigurationsanfrage erfüllt wurde.

Wenn ein Nutzer erfolgreich zum Abschluss-Weiterleitungs-URI weitergeleitet wird, der in der ursprünglichen Ereignis-Payload angegeben ist, führt Google Chat die folgenden Schritte aus:

  1. Löscht den privaten Autorisierungs-Prompt, der dem initiierenden Nutzer angezeigt wird.
  2. Die ursprüngliche Nachricht wird in eine öffentliche Nachricht umgewandelt und ist für andere Mitglieder des Gruppenbereichs sichtbar.
  3. Sendet das ursprüngliche Ereignisobjekt ein zweites Mal an Ihre Chat-App.

Wenn Sie nicht zur Abschluss-Weiterleitungs-URI weiterleiten, kann der Nutzer den Autorisierungsablauf trotzdem abschließen. Google Chat versucht jedoch nicht automatisch, die vorherige Ausführung noch einmal auszuführen, und der Nutzer muss Ihre Chat-App manuell aufrufen.

Der Besuch eines Abschluss-Weiterleitungs-URI wirkt sich nur auf eine einzelne Nutzerinteraktion aus. Wenn ein Nutzer einer Chat-App mehrmals Nachrichten gesendet und mehrere Aufforderungen erhalten hat, wird durch das Abschließen des Authentifizierungs- und Konfigurationsprozesses für eine Aufforderung nur diese bestimmte Interaktion wiederholt.

Chat-Nutzer außerhalb von Chat authentifizieren

Wenn Sie eine Verknüpfung zu einer URL außerhalb von Chat herstellen (z. B. ein OAuth-Web-Callback), müssen Sie die externe Websitzung häufig mit der Nutzeridentität in Chat in Beziehung setzen. Wir empfehlen, die Ziel-Web-App mit Google Log-in zu schützen.

Verwenden Sie das bei der Anmeldung ausgegebene Identitätstoken, um die Nutzer-ID abzurufen. Der Anspruch sub enthält die eindeutige Google-ID des Nutzers und kann mit dem Nutzernamen der Ressource (chat.user.name) aus Google Chat in Beziehung gesetzt werden.

Wenn Sie den sub-Anspruch mit einem Google Chat-users/{user}-Ressourcennamen in Beziehung setzen möchten, stellen Sie dem sub-Anspruchswert users/ voran. Ein sub-Anspruchswert von 123 entspricht beispielsweise users/123 in Ereignisobjekten, die an Ihre Chat-App gesendet werden.

Codebeispiele

Die folgenden Codebeispiele zeigen, wie eine Chat-App mit einer einfachen Autorisierungskarte Offline-OAuth2-Anmeldedaten anfordern, in einer Datenbank speichern, zur Abschluss-URI weiterleiten und API-Aufrufe mit Nutzerauthentifizierung ausführen kann:

Chat-Apps, die keine Add-ons sind: Chat-Apps mit anderen Diensten und Tools verbinden

Wenn Sie eine Chat-App verwalten, die kein Google Workspace-Add‑on ist, werden für Ihre Chat-App Konfigurationsanfragen mit einem actionResponse vom Typ REQUEST_CONFIG gesendet und configCompleteRedirectUrl aus dem Event-Objekt der obersten Ebene gelesen.

Wenn Sie eine Chat-App, die kein Add‑on ist, auf das Google Workspace-Add‑on-Framework umstellen möchten, lesen Sie den Abschnitt Google Chat-App in ein Google Workspace-Add‑on umwandeln.

Konfiguration von einem Nutzer in einer Chat-App anfordern, die kein Add‑on ist

Geben Sie in einer Chat-App, die kein Add‑on ist, eine Konfigurations-URL für den Nutzer im folgenden Format zurück:

{
  "actionResponse": {
    "type": "REQUEST_CONFIG",
    "url": "CONFIGURATION_URL"
  }
}

Dadurch wird Google Chat angewiesen, dem Nutzer einen privaten Prompt zu präsentieren. CONFIGURATION_URL ist ein Link, den der Nutzer aufrufen kann, um zusätzliche Authentifizierungs-, Autorisierungs- oder Konfigurationsschritte auszuführen. Eine REQUEST_CONFIG-Antwort schließt eine reguläre Antwortnachricht aus. Alle Texte, Karten oder anderen Attribute werden ignoriert.

Konfigurationsanfrage in einer Chat-App abschließen, die kein Add‑on ist

Jede MESSAGE-, ADDED_TO_SPACE- und APP_COMMAND-Interaktion Event, die eine Chat-App empfängt, die kein Add-on ist, enthält das Feld der obersten Ebene configCompleteRedirectUrl. Codieren Sie diese URL in Ihrer Konfigurations-URL und leiten Sie den Nutzer nach Abschluss dorthin weiter, damit Google Chat den Prompt löscht, die ursprüngliche Nachricht in „öffentlich“ ändert und das ursprüngliche Interaktionsereignis noch einmal an Ihre Chat-App sendet.

Beispielimplementierungen finden Sie auf GitHub im Node.js-Beispiel für eine Verbindungs-App und im Python-Beispiel für eine MyProfile-Autorisierungs-App.