Interface de point de terminaison des modules complémentaires Google Workspace


Présentation générale du service

Lorsqu'un utilisateur déclenche une interaction dans une application hôte compatible (Gmail, Google Agenda, Google Drive, Google Chat, Google Docs, Google Sheets, Google Slides ou Workspace Studio), l'hôte envoie une charge utile d'événement HTTP POST à l'URL de rappel du module complémentaire que vous avez configurée (/*).

Le point de terminaison de votre module complémentaire doit recevoir une charge utile de requête EventObject et renvoyer l'un des cinq types de réponses JSON valides documentés dans Réponse : HandleEventResponse.


Contrat de point de terminaison de webhook

Méthode Chemin du point de terminaison Corps de la requête Corps de la réponse
POST /* (ou chemin de rappel configuré) EventObject Un des cinq types de réponses

Requête : EventObject

Un EventObject contient des métadonnées de premier niveau, des champs d'événement courants et des détails contextuels de l'application hôte :

Contexte commun et d'autorisation

  • commonEventObject : paramètres régionaux de l'utilisateur, énumération de l'application hébergée (GMAIL, CALENDAR, DRIVE, CHAT, DOCS, SHEETS, SLIDES, WORKFLOW), plate-forme de l'utilisateur, fuseau horaire, valeurs d'entrée du formulaire du widget (formInputs) et paramètres personnalisés. Consultez CommonEventObject.
  • authorizationEventObject : jetons d'accès OAuth utilisateur, jetons d'ID utilisateur et champs d'application autorisés par le système. Consultez AuthorizationEventObject.

Objets d'événement de l'application hôte

Selon l'application qui appelle le rappel, l'un des objets hôtes suivants est présent :

  • Gmail : ID du message, ID du fil de discussion, jeton d'accès temporaire et listes des destinataires du message (toRecipients, ccRecipients, bccRecipients). Voir GmailEventObject.
  • Agenda : ID d'événement, ID d'événement périodique, ID d'agenda, informations sur l'organisateur, participants, données de conférence et points d'entrée. Consultez CalendarEventObject.
  • Drive : fichiers ou dossiers sélectionnés (selectedItems) et métadonnées de l'élément de curseur actuel (activeCursorItem). Voir DriveEventObject.
  • Chat : type d'événement (ADDED_TO_SPACE, REMOVED_FROM_SPACE, MESSAGE, CARD_CLICKED), métadonnées de l'espace, informations sur l'utilisateur et données de la charge utile. Consultez ChatEventObject.
  • Workspace Studio : appels d'actions, événements de cycle de vie des déclencheurs, configurations d'éléments, récupérations de ressources et mappages de données variables. Consultez WorkflowEventObject.
  • Docs : ID du document, titre, indicateur d'autorisation au niveau du fichier et format d'URL correspondant. Consultez DocsEventObject.
  • Sheets : ID de la feuille de calcul, titre, indicateur d'autorisation au niveau du fichier et format d'URL correspondant. Consultez SheetsEventObject.
  • Slides : ID de la présentation, titre, indicateur d'autorisation au niveau du fichier et format d'URL correspondant. Consultez SlidesEventObject.

Réponse : HandleEventResponse

La réponse HTTP renvoyée par votre point de terminaison de webhook est un objet JSON racine sans tag qui doit être une instance de l'un des cinq types de réponses suivants :

  1. RenderActions : affiche de nouvelles fiches, parcourt les piles de fiches ou exécute des actions d'UI (par exemple, {"action": {"navigations": [...]}} ou {"renderActions": ...}).
  2. SubmitFormResponse : répond à l'envoi d'un formulaire par l'utilisateur avec des instructions d'affichage de la fiche et un indicateur de mise à jour d'état facultatif (par exemple, {"renderActions": {...}, "stateChanged": true}).
  3. GetAutocompletionResponse : fournit des suggestions de texte dynamiques pour les champs de saisie semi-automatique des widgets (par exemple, {"autoComplete": {"items": [...]}}).
  4. DataActions : effectue des mutations de document ou des actions dans l'espace Chat déclenchées par le rappel (par exemple, {"hostAppDataAction": {...}}).
  5. AuthorizationError : invite l'utilisateur à autoriser des identifiants tiers externes ou demande des champs d'application Google OAuth supplémentaires (par exemple, {"basicAuthorizationPrompt": {"authorizationUrl": "..."}}).

Spécification OpenAPI 3.0 et schémas JSON autonomes

Pour générer automatiquement des bouchons de serveur, des bibliothèques clientes de SDK ou des schémas de validation de charge utile pour votre point de terminaison de rappel, consultez les fichiers de spécification suivants :

  • Spécification OpenAPI 3.0.3 : addon_callback_openapi.json
  • Définitions de schéma JSON : endpoint_interface.schema.json
    • Fragment de schéma de requête : endpoint_interface.schema.json#/definitions/GoogleAppsAddonsV1EventObject
    • Fragment de schéma de réponse : endpoint_interface.schema.json#/definitions/GoogleAppsAddonsV1HandleEventResponse