Überblick über den Service
Wenn ein Nutzer eine Interaktion in einer unterstützten Hostanwendung (Gmail, Google Kalender, Google Drive, Google Chat, Google Docs, Google Sheets, Google Präsentationen oder Workspace Studio) auslöst, sendet der Host eine HTTP-POST-Ereignisnutzlast an die konfigurierte Add-on-Callback-URL (/*).
Der Endpunkt Ihres Add-ons muss eine EventObject-Anfragenutzlast empfangen und einen der fünf gültigen JSON-Antworttypen zurückgeben, die unter Antwort: HandleEventResponse dokumentiert sind.
Webhook-Endpunktvertrag
| Methode | Endpunktpfad | Anfragetext | Antworttext |
|---|---|---|---|
POST |
/* (oder konfigurierter Callback-Pfad) |
EventObject |
Einer von fünf Antworttypen |
Anfrage: EventObject
Ein EventObject enthält Metadaten auf oberster Ebene, allgemeine Ereignisfelder und Kontextdetails zur Hostanwendung:
Allgemeiner und Autorisierungskontext
commonEventObject: Nutzer-Locale, gehostete Anwendungs-Enum (GMAIL,CALENDAR,DRIVE,CHAT,DOCS,SHEETS,SLIDES,WORKFLOW), Nutzerplattform, Zeitzone, Eingabewerte für Widget-Formulare (formInputs) und benutzerdefinierte Parameter. Weitere Informationen finden Sie unterCommonEventObject.authorizationEventObject: OAuth-Zugriffstokens, Nutzer-ID-Tokens und vom System autorisierte Bereiche. Weitere Informationen finden Sie unterAuthorizationEventObject.
Ereignisobjekte der gehosteten Anwendung
Je nachdem, welche Anwendung den Callback aufruft, ist eines der folgenden Hostobjekte vorhanden:
- Gmail: Nachrichten-ID, Thread-ID, temporäres Zugriffstoken und Empfängerlisten für Nachrichten (
toRecipients,ccRecipients,bccRecipients). Weitere Informationen finden Sie unterGmailEventObject. - Google Kalender: Termin-ID, ID des wiederkehrenden Termins, Kalender-ID, Informationen zum Organisator, Teilnehmer, Konferenzdaten und Einstiegspunkte. Weitere Informationen finden Sie unter
CalendarEventObject. - Drive: Ausgewählte Dateien oder Ordner (
selectedItems) und Metadaten des aktuellen Elements unter dem Cursor (activeCursorItem). Weitere Informationen finden Sie unterDriveEventObject. - Chat: Ereignistyp (
ADDED_TO_SPACE,REMOVED_FROM_SPACE,MESSAGE,CARD_CLICKED), Metadaten des Gruppenbereichs, Nutzerdetails und Nutzlastdaten. Weitere Informationen finden Sie unterChatEventObject. - Workspace Studio: Aktionsaufrufe, Trigger-Lebenszyklusereignisse, Elementkonfigurationen, Ressourcenabrufe und variable Datenzuordnungen.
Weitere Informationen finden Sie unter
WorkflowEventObject. - Docs: Dokument-ID, Titel, Berechtigungs-Flag auf Dateiebene und übereinstimmendes URL-Muster. Weitere Informationen finden Sie unter
DocsEventObject. - Google Sheets: Tabellen-ID, Titel, Berechtigungs-Flag auf Dateiebene und übereinstimmendes URL-Muster. Weitere Informationen finden Sie unter
SheetsEventObject. - Präsentationen: Präsentations-ID, Titel, Berechtigungs-Flag auf Dateiebene und übereinstimmendes URL-Muster. Weitere Informationen finden Sie unter
SlidesEventObject.
Antwort: HandleEventResponse
Die von Ihrem Webhook-Endpunkt zurückgegebene HTTP-Antwort ist ein nicht getaggtes JSON-Stammobjekt, das eine Instanz eines der folgenden fünf Antworttypen sein muss:
RenderActions: Rendert neue Karten, navigiert durch Kartenstapel oder führt UI-Aktionen aus (z. B.{"action": {"navigations": [...]}}oder{"renderActions": ...}).SubmitFormResponse: Antwortet auf die Aktion „Formular senden“ eines Nutzers mit Anweisungen zum Rendern der Karte und einem optionalen Indikator für die Statusaktualisierung (z. B.{"renderActions": {...}, "stateChanged": true}).GetAutocompletionResponse: Stellt dynamische Textvorschläge für Felder zur automatischen Vervollständigung von Widgets bereit (z. B.{"autoComplete": {"items": [...]}}).DataActions: Führt Dokumentänderungen oder Chatbereichsaktionen aus, die durch den Callback ausgelöst werden (z. B.{"hostAppDataAction": {...}}).AuthorizationError: Fordert den Nutzer auf, externe Drittanbieter-Anmeldedaten zu autorisieren, oder fordert zusätzliche Google OAuth-Bereiche an (z. B.{"basicAuthorizationPrompt": {"authorizationUrl": "..."}}).
Eigenständige OpenAPI 3.0-Spezifikation und JSON-Schemas
Wenn Sie Server-Stubs, SDK-Clientbibliotheken oder Schemas zur Validierung von Nutzlasten für Ihren Callback-Endpunkt automatisch generieren möchten, lesen Sie die folgenden Spezifikationsdateien:
- OpenAPI 3.0.3-Spezifikation:
addon_callback_openapi.json - JSON-Schemadefinitionen:
endpoint_interface.schema.json- Anfrageschemafragment:
endpoint_interface.schema.json#/definitions/GoogleAppsAddonsV1EventObject - Fragment des Antwortschemas:
endpoint_interface.schema.json#/definitions/GoogleAppsAddonsV1HandleEventResponse
- Anfrageschemafragment: