Interaktive Google Chat-App in ein Google Workspace-Add‑on umwandeln

Wenn Sie eine Google Chat-App erstellt und veröffentlicht haben, die Google Chat API-Interaktionsereignisse verwendet, z. B. eine App, die auf dem Google Chat-App-Schnellstart basiert, erfahren Sie auf dieser Seite, wie Sie sie in ein Google Workspace-Add‑on umwandeln, das Google Chat erweitert.

Durch die Umstellung kann Ihre Google Chat-App das Google Workspace-Add‑on-Framework verwenden. Dadurch ergeben sich neue Möglichkeiten für die Integration und Funktionen in Google Chat und in Google Workspace. Anstatt zwei Verteilungen – eine Google Chat-App und ein Google Workspace-Add‑on – können Sie ein einzelnes Google Workspace-Add‑on über den Google Workspace Marketplace verteilen, das Chat-Apps zusammen mit anderen Google Workspace-Hostanwendungen wie Gmail, Kalender und Docs erweitert.

Beschränkungen

Bevor Sie mit der Konvertierung beginnen, sollten Sie sich die Einschränkungen von Google Workspace-Add‑ons, die Google Chat erweitern ansehen, um sicherzustellen, dass Ihre Google Chat-App konvertiert werden kann, ohne dass wichtige Funktionen verloren gehen.

Schritt 1: Vorhandenen Google Chat-App-Code kopieren

Für die Umstellung sind Codeänderungen erforderlich. Damit Ihre aktive Google Chat App nicht beeinträchtigt wird, sollten Sie eine Kopie Ihres Codes erstellen und daran arbeiten.

Apps Script

  1. Öffnen Sie Ihr vorhandenes Google Apps Script-Projekt für die Google Chat App.
  2. Klicken Sie links auf Übersicht .
  3. Klicken Sie rechts auf Kopie erstellen .
  4. Klicken Sie links auf Projekteinstellungen .
  5. Klicken Sie unter Google Cloud-Projekt auf Projekt wechseln.
  6. Geben Sie dieselbe Projektnummer ein, die mit Ihrem vorhandenen Google Chat-App-Projekt verknüpft ist.
  7. Klicken Sie auf Projekt festlegen.

HTTP

Erstellen Sie eine Fork oder Kopie Ihrer vorhandenen Codebasis und stellen Sie sie als neuen Dienst bereit, der von Ihrer aktiven Google Chat-App getrennt ist.

Wenn Ihre App in Google Cloud bereitgestellt wird und auf Funktionen angewiesen ist, die mit dem Google Cloud-Projekt verknüpft sind (z. B. die Standardidentität von App Engine), sollte der neue Code für einen Dienst bereitgestellt werden, der mit dem vorhandenen Google Chat-App-Projekt verknüpft ist.

Schritt 2: Kopierten Code ändern

Google Workspace-Add‑ons, die Google Chat erweitern, verwenden andere Anfrage- und Antwortstrukturen als Google Chat-Apps, die mit Chat API-Interaktionsereignissen erstellt wurden. Sie müssen Ihren Code aktualisieren, damit das Google Workspace-Add-on EventObject anstelle der Event der Google Chat API für Anfragen und Antworten verwendet wird. Verwenden Sie die Anleitung zur Codekonvertierung, um Ihren Code zu ändern.

Schritt 3: Google Workspace-Add‑on-Konfiguration für Testnutzer aktivieren

Konfigurieren Sie die Google Workspace-Add‑on-Einstellungen für Ihre Google Chat-App in der Google Cloud Console:

  1. Rufen Sie in der Google Cloud Console die Konfigurationsseite für die Google Chat API auf.

    Zur Seite „Google Chat API-Konfiguration“

  2. Klicken Sie unter Interaktive Funktionen auf In Add-on umwandeln.

  3. Aktivieren Sie Einstellungen für die Add-on-Konfiguration aktivieren.

  4. Fügen Sie im Bereich Sichtbarkeit die E‑Mail-Adressen Ihrer Testnutzer hinzu.

  5. Aktualisieren Sie bei Bedarf die Verbindungseinstellungen mit der Bereitstellungsendpunkt-URL oder der Apps Script-Bereitstellungs-ID des kopierten und geänderten Google Chat-App-Codes aus Schritt 2.

  6. Klicken Sie auf Speichern und testen.

Schritt 4: Konvertierte App testen

Testen Sie die Funktionen des Google Workspace-Add-ons gründlich mit den in Schritt 3 konfigurierten Testnutzerkonten. Prüfen Sie alle Funktionen und Interaktionen.

Schritt 5: Umstellung für alle Nutzer abschließen

Nachdem Sie überprüft haben, ob das konvertierte Google Workspace-Add-on richtig funktioniert, können Sie es allen Nutzern zur Verfügung stellen.

  1. Rufen Sie in der Google Cloud Console die Konfigurationsseite für die Google Chat API auf.

    Zur Seite „Google Chat API-Konfiguration“

  2. Klicken Sie unter Interaktive Funktionen auf In Add-on umwandeln. Eine Seitenleiste wird geöffnet.

  3. Klicken Sie in der Seitenleiste auf In Add-on umwandeln.

  4. Geben Sie Ihre Projekt-ID ein und klicken Sie auf Konvertieren.

Ihre Google Chat-App ist jetzt ein Google Workspace-Add‑on, das Google Chat erweitert.

Optional: Nicht verwendete Google Cloud-Ressourcen bereinigen oder freigeben

Nachdem Sie Ihre Google Chat-App in ein Google Workspace-Add-on umgewandelt haben, können Sie die Ressourcen, die von der Google Chat-App verwendet werden und nicht mehr in Gebrauch sind, deaktivieren, um zu vermeiden, dass Ihrem Google Cloud-Konto dafür Gebühren berechnet werden.

Leitfaden zur Codekonvertierung

In diesem Abschnitt wird die Zuordnung zwischen dem Event-Format der Google Chat API-Interaktion und dem EventObject-Format des Google Workspace-Add-ons beschrieben.

Zuordnung anfordern

In der folgenden Tabelle sehen Sie, wie Felder in der Google Chat API Event den entsprechenden Feldern im Google Workspace-Add-on EventObject zugeordnet werden.

Feld „Google Chat API-Interaktion“ Event Feld „Google Workspace-Add-on“ EventObject Hinweise
action.actionMethodName – Bei Karteninteraktionen kann der Methodenname als Parameter in commonEventObject.parameters übergeben werden. Weitere Informationen finden Sie unter Ersten Dialog öffnen.
action.parameters commonEventObject.parameters
appCommandMetadata chat.appCommandPayload.appCommandMetadata
common commonEventObject
configCompleteRedirectUrl
  • chat.appCommandPayload.configCompleteRedirectUri
  • chat.addedToSpacePayload.configCompleteRedirectUri
  • chat.messagePayload.configCompleteRedirectUri
 Je nach Ereignistyp in verschiedenen Nutzlasten verfügbar.
dialogEventType
  • chat.appCommandPayload.dialogEventType
  • chat.buttonClickedPayload.dialogEventType
 Je nach Ereignistyp in verschiedenen Nutzlasten verfügbar.
eventTime chat.eventTime
isDialogEvent
  • chat.appCommandPayload.isDialogEvent
  • chat.buttonClickedPayload.isDialogEvent
 Je nach Ereignistyp in verschiedenen Nutzlasten verfügbar.
message
  • chat.messagePayload.message
  • chat.buttonClickedPayload.message
  • chat.appCommandPayload.message
 Je nach Ereignistyp in verschiedenen Nutzlasten verfügbar.
space
  • chat.messagePayload.space
  • chat.addedToSpacePayload.space
  • chat.removedFromSpacePayload.space
  • chat.buttonClickedPayload.space
  • chat.widgetUpdatedPayload.space
  • chat.appCommandPayload.space
thread
  • chat.messagePayload.message.thread
  • chat.buttonClickedPayload.message.thread
  • chat.appCommandPayload.message.thread
 Je nach Ereignistyp in verschiedenen Nutzlasten verfügbar.
threadKey
  • chat.messagePayload.message.thread.threadKey
  • chat.buttonClickedPayload.message.thread.threadKey
  • chat.appCommandPayload.message.threadKey
 Je nach Ereignistyp in verschiedenen Nutzlasten verfügbar.
token – Die Bestätigung erfolgt anders. Weitere Informationen finden Sie unter Bestätigung für HTTP-Apps anfordern.
type – Der Ereignistyp kann aus dem Trigger abgeleitet werden.
user chat.user

Anforderungszuordnung nach Anwendungsfall

Die folgende Tabelle zeigt die Unterschiede bei den Anfrage-Nutzlasten für häufige Anwendungsfälle zwischen Google Chat-Apps, die mit Chat API-Interaktionsereignissen erstellt wurden, und Google Workspace-Add-ons, die Google Chat erweitern.

Anwendungsfall Chat API-Interaktion Event Nutzlast Nutzlast für Google Workspace-Add-on EventObject
App zum Gruppenbereich hinzugefügt 
{
  "type": "ADDED_TO_SPACE",
  "space": { ... }
}
 
{
  "chat": {
    "addedToSpacePayload": {
      "space": { ... }
    }
  }
}
App aus Gruppenbereich entfernen 
{
  "type": "REMOVED_FROM_SPACE",
  "space": { ... }
}
 
{
  "chat": {
    "removedFromSpacePayload": {
      "space": { ... }
    }
  }
}
Nutzer erwähnt eine App mit @ 
{
  "type": "MESSAGE",
  "message": { ... },
  "space": { ... },
  "configCompleteRedirectUrl": "..."
}
 
{
  "chat": {
    "messagePayload": {
      "message": { ... },
      "space": { ... },
      "configCompleteRedirectUri": "..."
    }
  }
}
Nutzer erwähnt eine App mit „@“, um sie dem Gruppenbereich hinzuzufügen Sie müssen eine Anfrage von Google Chat bearbeiten:
{
  "type": "ADDED_TO_SPACE",
  "space": { ... },
  "message": { ... }
}
 Sie müssen zwei Anfragen von Google Chat bearbeiten.

Erste Anfrage:
{
  "chat": {
    "addedToSpacePayload": {
      "space": { ... },
      "interactionAdd": true
    }
  }
}

Zweite Anfrage:
{
  "chat": {
    "messagePayload": {
      "message": { ... },
      "space": { ... }
    }
  }
}
Slash-Befehl 
{
  "type": "MESSAGE",
  "message": { "slashCommand": { ... } },
  "space": { ... }
}
 
{
  "chat": {
    "appCommandPayload": {
      "message": { ... },
      "space": { ... },
      "appCommandMetadata": { ... }
    }
  }
}
Slash-Befehl zum Hinzufügen einer App zum Gruppenbereich Sie müssen eine Anfrage von Google Chat bearbeiten:
{
  "type": "ADDED_TO_SPACE",
  "space": { ... },
  "message": { "slashCommand": { ... } }
}
 Sie müssen zwei Anfragen von Google Chat bearbeiten.

Erste Anfrage:
{
  "chat": {
    "addedToSpacePayload": {
      "space": { ... },
      "interactionAdd": true
    }
  }
}

Zweite Anfrage:
{
  "chat": {
    "appCommandPayload": {
      "message": { ... },
      "space": { ... },
      "appCommandMetadata": { ... }
    }
  }
}
Nutzer klickt auf eine Schaltfläche auf einer Karte oder in einem Dialogfeld 
{
  "type": "CARD_CLICKED",
  "common": { ... },
  "space": { ... },
  "message": { ... },
  "isDialogEvent": "...",
  "dialogEventType": "..."
}

Bei Dialogereignissen enthält common.formInputs Widget-Werte. Google Apps Script-Beispiel:

{
  "type": "CARD_CLICKED",
  "common": {
   "formInputs": {
    "contactName": {
      "": { "stringInputs": { "value": ["Kai 0"] }}
    }
  }
  },
  "space": { ... },
  "message": { ... },
  "isDialogEvent": true,
  "dialogEventType": "..."
}
 
{
  "commonEventObject": { ... },
  "chat": {
    "buttonClickedPayload": {
      "message": { ... },
      "space": { ... },
      "isDialogEvent": "...",
      "dialogEventType": "..."
    }
  }
}

Bei Dialogereignissen enthält commonEventObject.formInputs Widget-Werte. Google Apps Script-Beispiel:

{
  "commonEventObject": {
     "formInputs": {
      "contactName": {
        "stringInputs": {
          "value": ["Kai 0"]
        }
      }
    }
  },
  "chat": {
    "buttonClickedPayload": {
      "message": { ... },
      "space": { ... },
      "isDialogEvent": "true",
      "dialogEventType": "..."
    }
  }
}
Nutzer gibt Informationen auf einer App-Startseite ein 
{
  "type": "SUBMIT_FORM",
  "common": { ... },
  "space": { ... },
  "message": { ... },
  "isDialogEvent": "...",
  "dialogEventType": "..."
}
 
{
  "commonEventObject": { ... },
  "chat": {
    "buttonClickedPayload": {
      "message": { ... },
      "space": { ... },
      "isDialogEvent": "...",
      "dialogEventType": "SUBMIT_DIALOG"
    }
  }
}
Der Nutzer ruft einen App-Befehl mit einem Schnellbefehl auf. 
{
  "type": "APP_COMMAND",
  "space": { ... },
  "isDialogEvent": "...",
  "dialogEventType": "..."
}
 
{
  "chat": {
    "appCommandPayload": {
      "message": { ... },
      "space": { ... },
      "appCommandMetadata": { ... }
    }
  }
}
Linkvorschau 
{
  "type": "MESSAGE",
  "message": {
    "matchedUrl": "..."
  },
  "space": { ... }
}
 
{
  "chat": {
    "messagePayload": {
      "message": {
        "matchedUrl": "..."
      },
      "space": { ... }
    }
  }
}
Nutzer aktualisiert ein Widget in einer Kartenmitteilung oder einem Dialogfeld 
{
  "type": "WIDGET_UPDATED",
  "space": { ... },
  "common": { ... }
}
 
{
  "commonEventObject": { ... },
  "chat": {
    "widgetUpdatedPayload": {
      "space": { ... }
    }
  }
}

Antwortzuordnung nach Anwendungsfall

Google Workspace-Add‑ons, die Google Chat erweitern, geben Aktionen anstelle eines Message-Objekts zurück. In der folgenden Tabelle werden die Message-Antworttypen der Google Chat API den entsprechenden Google Workspace-Add‑on-Aktionen zugeordnet.

Anwendungsfall Google Chat API Message-Antwort Antwort auf die Google Workspace-Add-on-Chat-Aktion
Nachricht im aufgerufenen Gruppenbereich erstellen 
{
  "actionResponse": {
    "type": "NEW_MESSAGE"
  },
  "text": "..."
}

actionResponse ist optional. Weitere Informationen

 
{
  "hostAppDataAction": {
    "chatDataAction": {
      "createMessageAction": {
        "message": {
          "text": "..."
         }
       }
    }
  }
}

Weitere Informationen
Nachricht aktualisieren 
{
 "actionResponse": {
  "type": "UPDATE_MESSAGE"
  },
 "text": "..."
}

Weitere Informationen

 
{
  "hostAppDataAction": {
    "chatDataAction": {
      "updateMessageAction": {
        "message": {
          "text": "..."
         }
       }
    }
  }
}

Weitere Informationen
Linkvorschau 
{
  "actionResponse": {
    "type": "UPDATE_USER_MESSAGE_CARDS"
  },
  "cardsV2": [{ ... }]
}

Weitere Informationen

 
{
  "hostAppDataAction": {
    "chatDataAction": {
      "updateInlinePreviewAction": {
        "cardsV2": [{ ... }]
      }
    }
  }
}

Weitere Informationen
Erstes Dialogfeld öffnen 
{
  "actionResponse": {
    "type": "DIALOG",
    "dialogAction": {
      "dialog": {
        "body": { /* Card object */ }
      }
    }
  }
}

Weitere Informationen

 
{
  "action": {
    "navigations": [{
      "pushCard": { /* Card object */ }
     }]
   }
}
Die Karte, die Sie pushen, kann Widgets mit onClick-Aktionen enthalten. Konfigurieren Sie für HTTP-Google Workspace-Add-ons diese Aktionen, um einen Funktionsendpunkt aufzurufen: 
{
  "onClick": {
    "action": {
      "function": "https://...",
      "parameters": [{
        "key": "clickedButton",
        "value": "submit"
      }]
    }
  }
}

Weitere Informationen finden Sie unter Dialogfeld öffnen (Add-ons).
Dialogfeld schließen 
{
  "actionResponse": {
    "type": "DIALOG",
    "dialogAction": {
      "actionStatus": {
        "userFacingMessage": "..."
      }
    }
  }
}

Weitere Informationen

 
{
  "action": {
    "navigations": [{
      "endNavigation": "CLOSE_DIALOG"
    }],
    "notification": { "text": "..."}
  }
}

Weitere Informationen finden Sie unter Dialogfeld schließen (Add-ons).
Verbindung zu einem externen System herstellen (Konfiguration anfordern) 
{
  "actionResponse": {
    "type": "REQUEST_CONFIG",
    "url": "..."
  }
}

Weitere Informationen finden Sie unter Verbindung zu einem externen System herstellen.

 
{
  "basic_authorization_prompt": {
    "authorization_url": "...",
    "resource": "..."
  }
}

Weitere Informationen finden Sie unter Google Workspace-Add‑on mit einem Drittanbieterdienst verbinden.
Elemente in interaktiven Widgets automatisch vervollständigen 
{
  "actionResponse": {
    "type": "UPDATE_WIDGET",
    "updatedWidget": {
      "suggestions": {
        "items": ["..."]
      },
      "widget": "widget_id"
    }
  }
}

Weitere Informationen finden Sie unter Mehrfachauswahlmenü hinzufügen.

 
{
  "action": {
    "modifyOperations": [{
      "updateWidget": {
        "widgetId": "widget_id",
        "selectionInputWidgetSuggestions": {
          "suggestions": ["..."]
        }
      }
    }]
  }
}

Weitere Informationen

Karteninteraktionen für Nachrichten verarbeiten, die vor der Conversion erstellt wurden

Wenn Sie eine HTTP-Google Chat-App in ein Google Workspace-Add‑on umwandeln, müssen Karteninteraktionen in Nachrichten, die vor der Umwandlung erstellt wurden, speziell behandelt werden. Google Workspace-Add‑ons verwenden eine vollständige HTTP-URL für die action.function einer Karte, während Google Chat-Apps, die mit Google Chat API-Interaktionsereignissen erstellt wurden, einen Funktionsnamen verwenden. In der folgenden Tabelle sind diese Unterschiede zusammengefasst.

Google Chat-App, die mit Interaktionsereignissen der Google Chat API erstellt wurde Google Workspace-Add‑on, das Google Chat erweitert
Configuration Sie konfigurieren einen einzelnen Endpunkt für alle Ereignisse in der Google Cloud Console. Bei der Implementierung von Karteninteraktionen enthält das action einer Karte nur den Namen der auszuführenden Funktion. Der gemeinsame HTTP-Endpunkt wird für Kartenklickereignisse aufgerufen.

Weitere Informationen



{
  "onClick": {
    "action": {
      "function": "submit"
    }
  }
}
 Sie können optional Endpunkte pro Ereignis in der Google Cloud Console konfigurieren. Das gilt jedoch nicht für Ereignisse, die durch Klicken auf Karten ausgelöst werden. Bei der Implementierung von Karteninteraktionen muss das action einer Karte die vollständige URL des aufzurufenden HTTP-Endpunkts enthalten. Sie können für jede Schaltfläche einen eindeutigen HTTP-Endpunkt festlegen oder einen gemeinsamen Endpunkt verwenden und die Aktion als Parameter in action.parameters übergeben.

Weitere Informationen finden Sie unter Dialogfeld öffnen (Add-ons).



{
  "onClick": {
    "action": {
      "function": "https://...",
      "parameters": [{
        "key": "method",
        "value": "submit"
      }]
    }
  }
}

Damit Karteninteraktionen für Nachrichten, die vor der Umstellung erstellt wurden, funktionieren, konfigurieren Sie auf der Konfigurationsseite der Google Chat API eine URL für Karteninteraktionen.

Diese URL wird nur für Interaktionen mit Mitteilungen verwendet, die vor der Umstellung Ihrer App erstellt wurden. Wenn ein Nutzer mit einer dieser Mitteilungen interagiert, wird der ursprüngliche action.function-Wert als Parameter mit dem Namen __action_method_name__ übergeben.

Beispiel: Klick auf Infokarte

Wenn Sie die URL für Karteninteraktion als https://.../card-interaction-handler konfiguriert haben und ein Nutzer auf eine Karte in einer alten Nachricht klickt, die folgende Aktion auslöst:

{
  "onClick": {
    "action": {
     "function": "submit"
    }
  }
}

Ein Ereignis wird im folgenden Format an die konfigurierte Card Interaction URL gesendet:

{
  "commonEventObject": {
    "parameters": {
      "__action_method_name__": "submit"
    }
  },
  "chat": {
    "buttonClickedPayload": { ... }
  }
}

Beispiel: Mehrfachauswahl-Menü

Wenn ein Nutzer mit einem Mehrfachauswahlmenü mit einer externen Datenquelle interagiert:

{
  "selectionInput": {
    "name": "contacts",
    "type": "MULTI_SELECT",
    "externalDataSource": {
      "function": "getContacts"
    }
  }
}

Ein Ereignis wird im folgenden Format an die konfigurierte Card Interaction URL gesendet:

{
  "commonEventObject": {
    "parameters": {
      "__action_method_name__": "getContacts",
    }
  },
  "chat": {
    "widgetUpdatedPayload": { ... }
  }
}

Wenn Sie für Ihre HTTP-Trigger die Option Gemeinsame HTTP-Endpunkt-URL für alle Trigger verwenden aktivieren, wird die gemeinsame URL auch für Button Clicked-Ereignisse verwendet.

Anfragen für HTTP-Add‑ons für Google Workspace bestätigen, die Chat erweitern

Bei HTTP-basierten Google Chat-Apps muss die Logik zum Bestätigen, dass Anfragen von Google stammen, bei der Umstellung auf ein Google Workspace-Add‑on aktualisiert werden.

Die wichtigsten Unterschiede bei der Anfragenbestätigung sind:

App-Typ Unterstützte Zielgruppe E-Mail-Adresse des Dienstkontos
Google Chat-App, die mit Interaktionsereignissen der Google Chat API erstellt wurde Projektnummer chat@system.gserviceaccount.com
Google Workspace-Add‑on zur Erweiterung von Google Chat Nur HTTP-Endpunkt E-Mail-Adresse des Dienstkontos pro Projekt

Die eindeutige E-Mail-Adresse des Dienstkontos für Ihr Google Workspace-Add‑on finden Sie in der Google Cloud Console auf der Seite zur Google Chat API-Konfiguration im Abschnitt In Google Workspace-Add‑ons umwandeln.

So bestätigen Sie Anfragen in Ihrem aktualisierten Google Workspace-Add‑on:

  1. Wenn Sie Cloud Run-Funktionen verwenden, weisen Sie dem Dienstkonto des Add-ons die Rolle roles/cloudfunctions.invoker zu. Weitere Informationen finden Sie unter Zugriff mit IAM autorisieren.
  2. Aktualisieren Sie den Token-Bestätigungscode, damit die Signatur des Inhabertokens mit der E-Mail-Adresse des Google Workspace-Add-on-Dienstkontos bestätigt wird. Weitere Informationen finden Sie unter Anfragen von Google validieren.