服務總覽
當使用者在支援的代管應用程式 (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。 - 試算表:試算表 ID、標題、檔案範圍權限標記,以及相符的網址模式。請參閱
SheetsEventObject。 - 簡報:簡報 ID、標題、檔案範圍權限標記,以及相符的網址模式。請參閱
SlidesEventObject。
回覆:HandleEventResponse
Webhook 端點傳回的 HTTP 回應是未標記的根 JSON 物件,且必須是下列五種回應類型之一的例項:
RenderActions:算繪新資訊卡、瀏覽資訊卡堆疊,或執行 UI 動作 (例如{"action": {"navigations": [...]}}或{"renderActions": ...})。SubmitFormResponse:回應使用者提交表單的動作,並提供資訊卡算繪操作說明和選用的狀態更新指標 (例如{"renderActions": {...}, "stateChanged": true})。GetAutocompletionResponse:為小工具自動完成欄位 (例如{"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 - 回覆結構定義片段:
endpoint_interface.schema.json#/definitions/GoogleAppsAddonsV1HandleEventResponse
- 要求結構定義片段: