Google Workspace 插件端点接口


服务概览

当用户在受支持的托管应用(Gmail、Google 日历、Google 云端硬盘、Google Chat、Google 文档、Google 表格、Google 幻灯片或 Workspace Studio)中触发互动时,宿主会向您配置的插件回调网址 (/*) 发送 HTTP POST 事件载荷。

您的插件端点必须接收 EventObject 请求载荷,并返回响应:HandleEventResponse中记录的五种有效 JSON 响应类型之一。


Webhook 端点协定

方法 端点路径 请求正文 响应正文
POST /*(或配置的回调路径) EventObject 5 种回答类型之一

请求:EventObject

EventObject 包含顶级元数据、常见事件字段和宿主应用上下文详细信息:

通用和授权上下文

  • commonEventObject:用户语言区域、托管应用枚举(GMAIL、CALENDAR、DRIVE、CHAT、DOCS、SHEETS、SLIDES、WORKFLOW)、用户平台、时区、微件表单输入值 (formInputs) 和自定义参数。请参阅 CommonEventObject。
  • authorizationEventObject:用户 OAuth 访问令牌、用户 ID 令牌和系统授权的范围。请参阅 AuthorizationEventObject。

托管应用事件对象

根据调用回调的应用,系统会显示以下宿主对象之一:

  • Gmail:邮件 ID、会话串 ID、临时访问令牌和邮件收件人列表(toRecipients、ccRecipients、bccRecipients)。请参阅 GmailEventObject。
  • 日历:活动 ID、周期性活动 ID、日历 ID、组织者信息、参加者、会议数据和入口点。请参阅 CalendarEventObject。
  • 云端硬盘:所选文件或文件夹 (selectedItems) 以及当前光标项元数据 (activeCursorItem)。请参阅 DriveEventObject。
  • Chat:事件类型(ADDED_TO_SPACE、REMOVED_FROM_SPACE、MESSAGE、CARD_CLICKED)、聊天室元数据、用户详细信息和载荷数据。请参阅 ChatEventObject。
  • Workspace Studio:操作调用、触发器生命周期事件、元素配置、资源检索和变量数据映射。请参阅 WorkflowEventObject。
  • 文档:文档 ID、标题、文件范围权限标志和匹配的网址格式。请参阅 DocsEventObject。
  • Google 表格:电子表格 ID、标题、文件范围权限标志和匹配的网址格式。请参阅 SheetsEventObject。
  • 幻灯片:演示文稿 ID、标题、文件范围权限标志和匹配的网址格式。请参阅 SlidesEventObject。

回复:HandleEventResponse

Webhook 端点返回的 HTTP 响应是一个未标记的根 JSON 对象,该对象必须是以下五种响应类型之一的实例:

  1. RenderActions:呈现新卡片、浏览卡片堆栈或执行界面操作(例如 {"action": {"navigations": [...]}} 或 {"renderActions": ...})。
  2. SubmitFormResponse:使用卡片呈现说明和可选的状态更新指示器(例如 {"renderActions": {...}, "stateChanged": true})响应用户表单提交操作。
  3. GetAutocompletionResponse:为 widget 自动补全字段(例如 {"autoComplete": {"items": [...]}})提供动态文本建议。
  4. DataActions:执行由回调触发的文档更改或 Chat 聊天室操作(例如 {"hostAppDataAction": {...}})。
  5. AuthorizationError:提示用户授权外部第三方凭据或请求其他 Google OAuth 范围(例如 {"basicAuthorizationPrompt": {"authorizationUrl": "..."}})。

独立的 OpenAPI 3.0 规范和 JSON 架构

如需为回调端点自动生成服务器桩、SDK 客户端库或载荷验证架构,请参阅以下规范文件:

  • OpenAPI 3.0.3 规范:addon_callback_openapi.json
  • JSON 架构定义: endpoint_interface.schema.json
    • 请求架构片段: endpoint_interface.schema.json#/definitions/GoogleAppsAddonsV1EventObject
    • 响应 schema 片段: endpoint_interface.schema.json#/definitions/GoogleAppsAddonsV1HandleEventResponse