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。
  • 試算表:試算表 ID、標題、檔案範圍權限標記,以及相符的網址模式。請參閱 SheetsEventObject。
  • 簡報:簡報 ID、標題、檔案範圍權限標記,以及相符的網址模式。請參閱 SlidesEventObject。

回覆:HandleEventResponse

Webhook 端點傳回的 HTTP 回應是未標記的根 JSON 物件,且必須是下列五種回應類型之一的例項:

  1. RenderActions:算繪新資訊卡、瀏覽資訊卡堆疊,或執行 UI 動作 (例如 {"action": {"navigations": [...]}} 或 {"renderActions": ...})。
  2. SubmitFormResponse:回應使用者提交表單的動作,並提供資訊卡算繪操作說明和選用的狀態更新指標 (例如 {"renderActions": {...}, "stateChanged": true})。
  3. GetAutocompletionResponse:為小工具自動完成欄位 (例如 {"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
    • 回覆結構定義片段: endpoint_interface.schema.json#/definitions/GoogleAppsAddonsV1HandleEventResponse