Interfaccia dell'endpoint dei componenti aggiuntivi di Google Workspace


Panoramica del servizio

Quando un utente attiva un'interazione in un'applicazione host supportata (Gmail, Google Calendar, Google Drive, Google Chat, Documenti Google, Fogli Google, Presentazioni Google o Workspace Studio), l'host invia un payload dell'evento HTTP POST all'URL di callback del componente aggiuntivo configurato (/*).

L'endpoint del componente aggiuntivo deve ricevere un payload della richiesta EventObject e restituire uno dei cinque tipi di risposta JSON validi documentati in Risposta: HandleEventResponse.


Contratto dell'endpoint del webhook

Metodo Percorso endpoint Corpo della richiesta Corpo della risposta
POST /* (o percorso di callback configurato) EventObject Uno dei 5 tipi di risposta

Richiesta: EventObject

Un EventObject contiene metadati di primo livello, campi di eventi comuni e dettagli contestuali dell'applicazione host:

Contesto comune e di autorizzazione

  • commonEventObject: impostazioni internazionali dell'utente, enum dell'applicazione in hosting (GMAIL, CALENDAR, DRIVE, CHAT, DOCS, SHEETS, SLIDES, WORKFLOW), piattaforma utente, fuso orario, valori di input del modulo del widget (formInputs) e parametri personalizzati. Consulta CommonEventObject.
  • authorizationEventObject: token di accesso OAuth utente, token ID utente e ambiti autorizzati dal sistema. Consulta AuthorizationEventObject.

Oggetti evento dell'applicazione in hosting

A seconda dell'applicazione che richiama il callback, è presente uno dei seguenti oggetti host:

  • Gmail: ID messaggio, ID thread, token di accesso temporaneo ed elenchi dei destinatari dei messaggi (toRecipients, ccRecipients, bccRecipients). Consulta GmailEventObject.
  • Calendar: ID evento, ID evento ricorrente, ID calendario, informazioni sull'organizzatore, partecipanti, dati della conferenza e punti di accesso. Consulta CalendarEventObject.
  • Drive: file o cartelle selezionati (selectedItems) e metadati dell'elemento del cursore corrente (activeCursorItem). Consulta DriveEventObject.
  • Chat: tipo di evento (ADDED_TO_SPACE, REMOVED_FROM_SPACE, MESSAGE, CARD_CLICKED), metadati dello spazio, dettagli dell'utente e dati del payload. Consulta ChatEventObject.
  • Workspace Studio: chiamate di azioni, eventi del ciclo di vita dei trigger, configurazioni degli elementi, recuperi delle risorse e mappature dei dati delle variabili. Consulta WorkflowEventObject.
  • Documenti: ID documento, titolo, flag di autorizzazione per l'ambito del file e pattern URL corrispondente. Consulta DocsEventObject.
  • Fogli: ID foglio di lavoro, titolo, flag di autorizzazione per l'ambito del file e pattern URL corrispondente. Consulta SheetsEventObject.
  • Presentazioni: ID presentazione, titolo, flag di autorizzazione con ambito file e pattern URL corrispondente. Consulta SlidesEventObject.

Risposta: HandleEventResponse

La risposta HTTP restituita dall'endpoint del webhook è un oggetto JSON principale non codificato che deve essere un'istanza di uno dei seguenti cinque tipi di risposta:

  1. RenderActions: esegue il rendering di nuove schede, naviga tra gli stack di schede o esegue azioni della UI (ad esempio {"action": {"navigations": [...]}} o {"renderActions": ...}).
  2. SubmitFormResponse: risponde all'azione di invio di un modulo utente con istruzioni per il rendering della scheda e un indicatore di aggiornamento dello stato facoltativo (ad esempio {"renderActions": {...}, "stateChanged": true}).
  3. GetAutocompletionResponse: fornisce suggerimenti di testo dinamici per i campi di completamento automatico dei widget (ad esempio {"autoComplete": {"items": [...]}}).
  4. DataActions: esegue le mutazioni dei documenti o le azioni dello spazio di Chat attivate dal callback (ad esempio, {"hostAppDataAction": {...}}).
  5. AuthorizationError: chiede all'utente di autorizzare credenziali di terze parti esterne o richiede ambiti OAuth di Google aggiuntivi (ad esempio {"basicAuthorizationPrompt": {"authorizationUrl": "..."}}).

Specifica OpenAPI 3.0 e schemi JSON autonomi

Per generare automaticamente stub del server, librerie client SDK o schemi di convalida del payload per l'endpoint di callback, consulta i seguenti file di specifica:

  • Specifica OpenAPI 3.0.3: addon_callback_openapi.json
  • Definizioni dello schema JSON: endpoint_interface.schema.json
    • Frammento dello schema della richiesta: endpoint_interface.schema.json#/definitions/GoogleAppsAddonsV1EventObject
    • Frammento dello schema di risposta: endpoint_interface.schema.json#/definitions/GoogleAppsAddonsV1HandleEventResponse