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

Wenn Sie eine Chat-App entwickelt und veröffentlicht haben, die kein Google Workspace-Add‑on ist, 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. So können Sie beispielsweise ein einzelnes Google Workspace-Add-on über den Google Workspace Marketplace vertreiben, das Chat-Apps zusammen mit anderen Google Workspace-Hostanwendungen wie Gmail, Kalender und Docs erweitert.

Beschränkungen

Bevor Sie mit der Umstellung beginnen, sollten Sie sich die Einschränkungen und Überlegungen für Google Workspace-Add‑ons ansehen, um sicherzustellen, dass Ihre Chat-App, die kein Add‑on ist, umgestellt 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 einen Fork oder eine Kopie Ihrer vorhandenen Codebasis und stellen Sie ihn 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 in einem 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 Chat-Apps, die keine Add‑ons sind. Sie müssen Ihren Code aktualisieren, damit für Anfragen und Antworten Google Workspace-Add‑on-Ereignisobjekte (EventObject) anstelle von Google Chat API-Interaktionsereignissen (Event) verwendet werden. Verwenden Sie die Anleitung zur Codekonvertierung, um Ihren Code zu ändern.

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

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

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

    Zur Seite „Google Chat API-Konfiguration“

  2. Aktivieren Sie unter Interaktive Funktionen die Option Interaktive Funktionen aktivieren.

  3. Klicken Sie unter In Google Workspace-Add-on umwandeln auf In Add-on umwandeln.

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

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

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

  7. 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: Konvertierung 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 der 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 nicht mehr verwendeten Google Chat-App verwendet werden, deaktivieren, um zu vermeiden, dass Ihrem Google Cloud-Konto Gebühren dafür 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.

Anfragezuordnung

In der folgenden Tabelle sehen Sie, wie Felder in der Google Chat API Event für eine Chat-App, die kein Add‑on ist, den entsprechenden Feldern im Google Workspace-Add‑on EventObject zugeordnet werden.

Chat-App, die kein Add‑on ist (Feld 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 wird anders gehandhabt. Weitere Informationen finden Sie unter Bestätigung für HTTP-Apps anfordern.
type – Der Ereignistyp kann aus dem Trigger abgeleitet werden.
user chat.user

Zuordnung von Anfragen nach Anwendungsfall

In der folgenden Tabelle sehen Sie die Unterschiede bei den Anfrage-Nutzlasten für häufige Anwendungsfälle zwischen Chat-Apps, die keine Add-ons sind, und Google Workspace-Add-ons, die Google Chat erweitern.

Anwendungsfall Chat-App, die kein Add‑on ist (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 aus Google Chat bearbeiten:
{
  "type": "ADDED_TO_SPACE",
  "space": { ... },
  "message": { ... }
}
 Sie müssen zwei Anfragen von Google Chat verarbeiten.

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 aus Google Chat bearbeiten:
{
  "type": "ADDED_TO_SPACE",
  "space": { ... },
  "message": { "slashCommand": { ... } }
}
 Sie müssen zwei Anfragen von Google Chat verarbeiten.

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

Zweite Anfrage
:
{
  "chat": {
    "appCommandPayload": {
      "message": { ... },
      "space": { ... },
      "appCommandMetadata": { ... }
    }
  }
}
Nutzer klickt auf einen Button 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 für eine Chat-App, die kein Add‑on ist, den entsprechenden Google Workspace-Add‑on-Aktionen zugeordnet.

Anwendungsfall Chat-App, die kein Add‑on ist (Message-Antwort) Antwort auf die Chat-Aktion eines Google Workspace-Add‑ons
Nachricht im aufgerufenen Gruppenbereich erstellen 
{
  "actionResponse": {
    "type": "NEW_MESSAGE"
  },
  "text": "..."
}

actionResponse ist optional. Weitere Informationen finden Sie unter Auf einen Slash-Befehl reagieren.

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

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

Weitere Informationen finden Sie unter Nachricht aktualisieren.

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

Weitere Informationen finden Sie unter Nachricht aktualisieren.
Linkvorschau 
{
  "actionResponse": {
    "type": "UPDATE_USER_MESSAGE_CARDS"
  },
  "cardsV2": [{ ... }]
}

Weitere Informationen finden Sie unter Vorschaulinks.

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

Weitere Informationen finden Sie unter Vorschaulinks.
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
Dialogfeld schließen 
{
  "actionResponse": {
    "type": "DIALOG",
    "dialogAction": {
      "actionStatus": {
        "userFacingMessage": "..."
      }
    }
  }
}

Weitere Informationen finden Sie unter Dialogfeld schließen.

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

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

Weitere Informationen

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

Weitere Informationen
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 bei Nachrichten verarbeiten, die vor der Konvertierung erstellt wurden

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

Chat-App, die kein Add‑on ist 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 die 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



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

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

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 Card Interaction URL als https://.../card-interaction-handler konfiguriert haben und ein Nutzer auf eine Karte in einer alten Nachricht klickt, wird Folgendes ausgeführt:

{
  "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: Menü mit Mehrfachauswahl

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 Bestätigung von Anfragen sind:

App-Typ Unterstützte Zielgruppe E-Mail-Adresse des Dienstkontos
Chat-App, die kein Add‑on ist 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 „Google Chat API-Konfiguration“ im Bereich 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 Code zur Tokenbestätigung, damit die E‑Mail-Adresse des Google Workspace-Add-on-Dienstkontos verwendet wird, um die Signatur des Bearer-Tokens zu bestätigen. Weitere Informationen finden Sie unter Anfragen von Google validieren.