服务概览
当用户在受支持的托管应用(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 对象,该对象必须是以下五种响应类型之一的实例:
RenderActions:呈现新卡片、浏览卡片堆栈或执行界面操作(例如{"action": {"navigations": [...]}}或{"renderActions": ...})。SubmitFormResponse:使用卡片呈现说明和可选的状态更新指示器(例如{"renderActions": {...}, "stateChanged": true})响应用户表单提交操作。GetAutocompletionResponse:为 widget 自动补全字段(例如{"autoComplete": {"items": [...]}})提供动态文本建议。DataActions:执行由回调触发的文档更改或 Chat 聊天室操作(例如{"hostAppDataAction": {...}})。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
- 请求架构片段: