Interfaz de extremo de los complementos de Google Workspace


Descripción general del servicio

Cuando un usuario activa una interacción en una aplicación host compatible (Gmail, Calendario de Google, Google Drive, Google Chat, Documentos de Google, Hojas de cálculo de Google, Presentaciones de Google o Workspace Studio), el host envía una carga útil de evento HTTP POST a la URL de devolución de llamada del complemento configurada (/*).

El extremo de tu complemento debe recibir una carga útil de solicitud EventObject y devolver uno de los cinco tipos de respuesta JSON válidos documentados en Respuesta: HandleEventResponse.


Contrato del extremo del webhook

Método Ruta de acceso del extremo Cuerpo de la solicitud Cuerpo de la respuesta
POST /* (o la ruta de devolución de llamada configurada) EventObject Uno de los 5 tipos de respuesta

Solicitud: EventObject

Un EventObject contiene metadatos de nivel superior, campos de eventos comunes y detalles contextuales de la aplicación host:

Contexto común y de autorización

  • commonEventObject: Configuración regional del usuario, enum de la aplicación alojada (GMAIL, CALENDAR, DRIVE, CHAT, DOCS, SHEETS, SLIDES, WORKFLOW), plataforma del usuario, zona horaria, valores de entrada del formulario del widget (formInputs) y parámetros personalizados. Consulta CommonEventObject.
  • authorizationEventObject: Son los tokens de acceso de OAuth del usuario, los tokens de ID de usuario y los permisos autorizados por el sistema. Consulta AuthorizationEventObject.

Objetos de eventos de la aplicación host

Según la aplicación que invoque la devolución de llamada, estará presente uno de los siguientes objetos host:

  • Gmail: ID de mensaje, ID de conversación, token de acceso temporal y listas de destinatarios de mensajes (toRecipients, ccRecipients, bccRecipients). Consulta GmailEventObject.
  • Calendario: ID del evento, ID del evento recurrente, ID del calendario, información del organizador, asistentes, datos de la conferencia y puntos de entrada. Consulta CalendarEventObject.
  • Drive: Archivos o carpetas seleccionados (selectedItems) y metadatos del elemento actual del cursor (activeCursorItem). Consulta DriveEventObject.
  • Chat: Tipo de evento (ADDED_TO_SPACE, REMOVED_FROM_SPACE, MESSAGE, CARD_CLICKED), metadatos del espacio, detalles del usuario y datos de carga útil. Consulta ChatEventObject.
  • Workspace Studio: Invocaciones de acciones, eventos del ciclo de vida de los activadores, configuraciones de elementos, recuperaciones de recursos y asignaciones de datos de variables. Consulta WorkflowEventObject.
  • Documentos: ID del documento, título, marca de permiso de alcance de archivo y patrón de URL coincidente. Consulta DocsEventObject.
  • Hojas de cálculo: ID de la hoja de cálculo, título, marca de permiso de alcance de archivo y patrón de URL coincidente. Consulta SheetsEventObject.
  • Presentaciones: ID de la presentación, título, marca de permiso de alcance de archivo y patrón de URL coincidente. Consulta SlidesEventObject.

Respuesta: HandleEventResponse

La respuesta HTTP que devuelve tu extremo de webhook es un objeto JSON raíz sin etiquetar que debe ser una instancia de uno de los siguientes cinco tipos de respuesta:

  1. RenderActions: Renderiza tarjetas nuevas, navega por pilas de tarjetas o ejecuta acciones de la IU (por ejemplo, {"action": {"navigations": [...]}} o {"renderActions": ...}).
  2. SubmitFormResponse: Responde a la acción de envío de un formulario de usuario con instrucciones de renderización de tarjetas y un indicador de actualización de estado opcional (por ejemplo, {"renderActions": {...}, "stateChanged": true}).
  3. GetAutocompletionResponse: Proporciona sugerencias de texto dinámicas para los campos de autocompletado de widgets (por ejemplo, {"autoComplete": {"items": [...]}}).
  4. DataActions: Realiza mutaciones de documentos o acciones de espacio de Chat activadas por la devolución de llamada (por ejemplo, {"hostAppDataAction": {...}}).
  5. AuthorizationError: Solicita al usuario que autorice credenciales externas de terceros o solicita permisos adicionales de OAuth de Google (por ejemplo, {"basicAuthorizationPrompt": {"authorizationUrl": "..."}}).

Especificación de OpenAPI 3.0 independiente y esquemas JSON

Para generar automáticamente resguardos de servidor, bibliotecas cliente de SDK o esquemas de validación de carga útil para tu extremo de devolución de llamada, consulta los siguientes archivos de especificación:

  • Especificación de OpenAPI 3.0.3: addon_callback_openapi.json
  • Definiciones del esquema JSON: endpoint_interface.schema.json
    • Fragmento del esquema de solicitud: endpoint_interface.schema.json#/definitions/GoogleAppsAddonsV1EventObject
    • Fragmento del esquema de respuesta: endpoint_interface.schema.json#/definitions/GoogleAppsAddonsV1HandleEventResponse