Interface de endpoint dos complementos do Google Workspace


Visão geral do serviço

Quando um usuário aciona uma interação em um aplicativo host compatível (Gmail, Google Agenda, Google Drive, Google Chat, Documentos Google, Planilhas Google, Apresentações Google ou Workspace Studio), o host envia um payload de evento HTTP POST para o URL de callback do complemento configurado (/*).

O endpoint do complemento precisa receber um payload de solicitação EventObject e retornar um dos cinco tipos de resposta JSON válidos documentados em Resposta: HandleEventResponse.


Contrato de endpoint do webhook

Método Caminho do endpoint Corpo da solicitação Corpo da resposta
POST /* (ou caminho de callback configurado) EventObject Um dos cinco tipos de resposta

Solicitação: EventObject

Um EventObject contém metadados de nível superior, campos de eventos comuns e detalhes contextuais do aplicativo host:

Contexto comum e de autorização

  • commonEventObject: localidade do usuário, tipo enumerado do aplicativo hospedado (GMAIL, CALENDAR, DRIVE, CHAT, DOCS, SHEETS, SLIDES, WORKFLOW), plataforma do usuário, fuso horário, valores de entrada do formulário do widget (formInputs) e parâmetros personalizados. Consulte CommonEventObject.
  • authorizationEventObject: tokens de acesso OAuth do usuário, tokens de ID do usuário e escopos autorizados pelo sistema. Consulte AuthorizationEventObject.

Objetos de evento do aplicativo host

Dependendo de qual aplicativo invoca o callback, um dos seguintes objetos host está presente:

  • Gmail: ID da mensagem, ID da conversa, token de acesso temporário e listas de destinatários da mensagem (toRecipients, ccRecipients, bccRecipients). Consulte GmailEventObject.
  • Agenda: ID do evento, ID do evento recorrente, ID da agenda, informações do organizador, convidados, dados da videoconferência e pontos de entrada. Consulte CalendarEventObject.
  • Drive: arquivos ou pastas selecionados (selectedItems) e metadados do item atual do cursor (activeCursorItem). Consulte DriveEventObject.
  • Chat: tipo de evento (ADDED_TO_SPACE, REMOVED_FROM_SPACE, MESSAGE, CARD_CLICKED), metadados do espaço, detalhes do usuário e dados do payload. Consulte ChatEventObject.
  • Workspace Studio: invocações de ações, eventos de ciclo de vida de gatilhos, configurações de elementos, recuperações de recursos e mapeamentos de dados de variáveis. Consulte WorkflowEventObject.
  • Documentos: ID do documento, título, flag de permissão do escopo do arquivo e padrão do URL correspondente. Consulte DocsEventObject.
  • Planilhas: ID da planilha, título, flag de permissão de escopo de arquivo e padrão do URL correspondente. Consulte SheetsEventObject.
  • Slides: ID da apresentação, título, flag de permissão de escopo de arquivo e padrão do URL correspondente. Consulte SlidesEventObject.

Resposta: HandleEventResponse

A resposta HTTP retornada pelo endpoint do webhook é um objeto JSON raiz sem tag que precisa ser uma instância de um dos cinco tipos de resposta a seguir:

  1. RenderActions: renderiza novos cards, navega por pilhas de cards ou executa ações de interface (por exemplo, {"action": {"navigations": [...]}} ou {"renderActions": ...}).
  2. SubmitFormResponse: responde a uma ação de envio de formulário do usuário com instruções de renderização de card e um indicador opcional de atualização de estado (por exemplo, {"renderActions": {...}, "stateChanged": true}).
  3. GetAutocompletionResponse: fornece sugestões de texto dinâmicas para campos de preenchimento automático de widgets (por exemplo, {"autoComplete": {"items": [...]}}).
  4. DataActions: realiza mutações de documentos ou ações de espaço do Chat acionadas pelo callback (por exemplo, {"hostAppDataAction": {...}}).
  5. AuthorizationError: solicita que o usuário autorize credenciais de terceiros ou solicita outros escopos do OAuth do Google (por exemplo, {"basicAuthorizationPrompt": {"authorizationUrl": "..."}}).

Especificação independente da OpenAPI 3.0 e esquemas JSON

Para gerar automaticamente stubs de servidor, bibliotecas de cliente do SDK ou esquemas de validação de payload para seu endpoint de callback, consulte os seguintes arquivos de especificação:

  • Especificação OpenAPI 3.0.3: addon_callback_openapi.json
  • Definições de esquema JSON: endpoint_interface.schema.json
    • Solicitar fragmento de esquema: endpoint_interface.schema.json#/definitions/GoogleAppsAddonsV1EventObject
    • Fragmento do esquema de resposta: endpoint_interface.schema.json#/definitions/GoogleAppsAddonsV1HandleEventResponse