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. ConsultaCommonEventObject.authorizationEventObject: token di accesso OAuth utente, token ID utente e ambiti autorizzati dal sistema. ConsultaAuthorizationEventObject.
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). ConsultaGmailEventObject. - 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). ConsultaDriveEventObject. - Chat: tipo di evento (
ADDED_TO_SPACE,REMOVED_FROM_SPACE,MESSAGE,CARD_CLICKED), metadati dello spazio, dettagli dell'utente e dati del payload. ConsultaChatEventObject. - 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:
RenderActions: esegue il rendering di nuove schede, naviga tra gli stack di schede o esegue azioni della UI (ad esempio{"action": {"navigations": [...]}}o{"renderActions": ...}).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}).GetAutocompletionResponse: fornisce suggerimenti di testo dinamici per i campi di completamento automatico dei widget (ad esempio{"autoComplete": {"items": [...]}}).DataActions: esegue le mutazioni dei documenti o le azioni dello spazio di Chat attivate dal callback (ad esempio,{"hostAppDataAction": {...}}).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
- Frammento dello schema della richiesta: