如何從 Workspace Studio 呼叫外部 API

Google Workspace Studio 工作流程可能需要 Gmail、雲端硬碟或聊天以外的資料：例如訂單狀態、資料庫中的數位或內部工具的回應。若要檢索這些資料或將資訊傳送至其他服務，您可以新增相應的步驟。 發送 webhook這會向您指定的 API 位址發出 HTTP 請求。

您無需配置 Gemini 函數呼叫即可發出該請求。在 Workspace Studio 中，流程會執行 webhook 步驟並接收回應。然後，如果您覺得有用，可以將該回應傳遞到另一個步驟，以便對其進行匯總、提取資料或傳達結果。

連接 API 之前需要準備什麼？

第一步是驗證您的組織是否可以使用 Webhook。此功能位於： 限量預覽 預設情況下處於禁用狀態。管理員必須登入。 應用程式 > Google Workspace > Workspace Studio > Webhook 設定 並為對應的組織單元啟用此功能。

在某些版本中，管理員也可以將連線數限制為一個。 允許的網域名稱和網址列表如果該步驟出現在 Studio 中但無法與您的 API 通信，請驗證目標位址是否已獲得授權。此外，預設情況下，涉及 Webhook 的操作需要使用者在執行前審核並確認該步驟。

對於外部服務，您需要了解其 URL、支援的 HTTP 方法以及期望的資料格式。此外，也要檢查其驗證方式：公用唯讀 API 的要求與需要令牌或特殊標頭的私有 API 的要求不同。

如何從 Workspace Studio 呼叫 API（逐步指南）

進入 studio.workspace.google.com 然後建立包含所需觸發器的工作流程。例如，您可以將其設定為在收到符合特定條件的電子郵件時啟動。接下來，請依照以下步驟操作：

1. 按 新增步驟 並選擇 發送 webhook.
2. 進入 完整網址 API，包括前綴 https://位址必須固定：此欄位不支援流變數。
3. 選擇HTTP方法。 得到 它用於查詢資料； 郵政可以傳送或建立記錄。它們也可用。 PUT、PATCH 和 DELETE.
4. 如果 API 需要請求體，請將其寫入內容欄位或 有效載荷Google建議在接收服務需要JSON格式時使用JSON。
5. 製作一個 測試執行檢查結果，確認其有效後啟動流程。

請記住，測試 執行該操作如果您設定了 POST 要求來建立記錄或 DELETE 要求來刪除記錄，請先使用測試環境或您可以無故障修改的資料。

例如：向外部工具發送通知

想像一下，你的團隊有一個 API，可以建立警報 https://api.ejemplo.com/v1/avisos這個地址是 舉例說明您需要將其替換為您服務中的相應組件。如果它的文件表明它接受 POST 請求和 JSON 請求體，您可以配置該步驟並添加類似以下內容： {"tipo":"nuevo_correo","origen":"Workspace Studio"}.

您也可以插入一個 流量變數 例如，可以在正文中包含觸發郵件的主題。透過 Studio 的變數選擇器執行此操作並檢查結果：如果插入的文字包含引號或其他特殊字符，則可能會導致 JSON 格式錯誤。變數可以在內容中使用，但是… 不在 URL 欄位中.

如果需要檢索數據，請選擇 GET 請求並輸入已包含必要參數的固定 URL。 Workspace Studio 將忽略您在 GET 請求正文中編寫的任何內容。

如何處理 API 回應

webhook 步驟會離開 服務回應（文字） 數據將以變數的形式提供給後續步驟。您可以使用它來傳送通知、產生摘要，或指示 AI 步驟提取特定資料。

例如，如果 API 傳回訂單狀態，下一步可以將該狀態傳達給團隊。請明確選擇包含回應的變數：後續步驟不會自動接收流程中先前發生的所有內容。建議在編寫依賴返回內容的指令之前，先測試返回的內容。

如果 API 需要身份驗證或更複雜的邏輯

文件中記錄的基本配置 發送 webhook 它包含 URL、方法以及可選的請求體。如果您的整合需要取得 OAuth 令牌、建立具有可變參數的 URL、新增特定標頭或在繼續操作之前轉換回應，請檢查此步驟是否符合這些要求。

如果這種方法行不通，另一個選擇是開發一種 Workspace Studio 的自訂步驟 透過插件。在 Google Apps Script 實作中，該服務 UrlFetchApp 它允許您向外部 API 發出請求並處理 JSON 回應。此解決方案需要開發和適當的權限配置；對於原生步驟已經可以處理的簡單請求，則無需此方案。

避免將私鑰貼到流程的可見欄位中，或將其嵌入到共用 URL 中。在從 Gmail、Chat 或日曆發送資料之前，請確認外部服務將接收哪些訊息，以及它是否已獲得處理這些資訊的授權。

如何定位 webhook 中的錯誤

如果連線失敗，請開啟選項卡 活動 在流程圖中，您可以查看完整的錯誤訊息以及目標伺服器發送的回應。這些資訊有助於區分 Studio 設定問題和 API 拒絕的請求。

• 該步驟未顯示： 請向管理員確認您的組織單位是否已啟用 Webhook。
• 該網址已被封鎖： 如果您的版本使用了位址限制，請查看允許的位址清單。
• 錯誤 400： 檢查請求體格式和 API 要求的欄位。
• 錯誤代碼 401 或 403： 檢查服務所需的權限和身份驗證方法。
• 錯誤 429： 檢查您是否已超過目標 API 的請求限制。
• 錯誤 500： 查看接收請求的服務的狀態和記錄。

另請注意 Workspace Studio 的一般限制：它目前最多支持 每位用戶 25 個流量 y 每個流程 20 個步驟此外，還有一個每 24 小時重置一次的合併執行次數限制。如果多個流程停止運行，請先檢查它們的活動，然後再將故障歸咎於 API。

對於大多數簡單的 HTTP 連接，流程很簡單：啟用 Webhook，配置固定 URL 和正確的方法，測試請求，然後在後續步驟中使用回應。如果整合需要高級身份驗證或透過程式碼轉換數據，則需要準備一個自訂步驟。