Webhook

快訊可以是標準快訊或彈性快訊。使用標準 webhook 時，要求和回應欄位是由 Conversational Agents (Dialogflow CX) 定義。您可以使用彈性 Webhook 定義要求和回應欄位。

標準 Webhook

使用標準 webhook 時，您會使用 Conversational Agents (Dialogflow CX) 定義的要求和回應訊息。要求訊息會提供許多工作階段的詳細資料。舉例來說，系統會納入目前的有效網頁、最近相符的意圖、工作階段參數值，以及服務專員定義的回應。

標準 Webhook 要求

當系統呼叫含有 Webhook 的執行要求時，對話方塊代理程式 (Dialogflow CX) 會將 HTTPS POST Webhook 要求傳送至 Webhook 服務。這項要求的主體是 WebhookRequest JSON 物件，其中包含工作階段的相關資訊。

部分整合會在 WebhookRequest.payload 欄位中填入額外資訊。舉例來說，Dialogflow CX Phone Gateway 整合可提供使用者來電者 ID。

詳情請參閱 WebhookRequest(V3) 或 WebhookRequest(V3Beta1) 參考說明文件。

標準 Webhook 回應

您的 Webhook 服務收到 Webhook 要求後，就需要傳送 Webhook 回應。您的回覆有以下限制：

• 回應必須在建立 webhook 資源時設定的逾時期限內發生，否則要求會逾時。
• 回應大小必須小於或等於 64 KiB。

詳情請參閱 WebhookResponse(V3) 或 WebhookResponse(V3Beta1) 參考說明文件。

標準 Webhook 資源設定

以下說明標準 Webhook 的 Webhook 資源設定：

彈性 Webhook

透過彈性 webhook，您可以定義要求的 HTTP 方法、要求網址參數，以及要求和回應訊息的欄位。要求只能提供所選參數值，回應只能提供參數覆寫值。這項限制其實很有幫助，因為它可簡化介面，讓使用者介面與 webhook 之間的連結更為緊密。除了在代理程式和 webhook 之間傳遞工作階段參數值以外，通常不需要傳遞其他資訊。這也簡化了 Webhook 的導入作業，因為要求和回應訊息只包含您需要的內容，而且您可以為各種情境提供專屬的 Webhook 訊息。

彈性 webhook 要求

為代理程式建立 Webhook 資源時，您可以為 Webhook 要求指定下列項目：

• 用於傳送至 Webhook 服務的 Webhook 要求的 HTTP 方法。
• Conversational Agents (Dialogflow CX) 應使用網址傳送至 Webhook 服務的會話參數值。
• 如果您選擇 POST、PUT 或 PATCH 做為方法，可以透過要求 JSON 主體指定會話方塊應傳送至 webhook 服務的會話方塊參數值。

如要使用要求網址或 JSON 主體傳送工作階段參數值，請按照平常的方式使用參數參照。您不需要為參數參照加上網址轉義字元，也不需要將參照包裝在引號中。在執行階段，Conversational Agents (Dialogflow CX) 會視需要為參數值加上網址轉義字元。清單或複合值會以 JSON 格式提供。

在 JSON 主體中使用參數參照時，無論參數類型為何，都必須以引號包圍參照。如果參數實際上是數值向量、清單或複合值，Conversational Agents (Dialogflow CX) 會在執行階段傳送要求時移除引號，以保留參數的資料類型。字串標量類型會保留引號。如果在字串值中參照數值單元、清單或複合值 (例如：「This is a number: $session.params.size」)，系統會將參數視為字串 (例如：「This is a number: 3」)。

舉例來說，您可以將 fruit 和 size 工作階段參數值提供給要求網址，如下所示：

https://your-webhook-service.com/handler?f=$session.params.fruit&s=$session.params.size

並將要求 JSON 主體設為如下格式：

{
  "fruitParameter": "$session.params.fruit",
  "sizeParameter": "$session.params.size"
}

彈性的 Webhook 回應

為代理程式建立 Webhook 資源時，您可以指定會話參數，讓 Conversational Agents (Dialogflow CX) 在執行階段將其設為 Webhook 回應的特定欄位。

您的回覆有以下限制：

• 回應必須在建立 webhook 資源時設定的逾時期限內發生，否則要求會逾時。
• 回應大小必須小於或等於 64 KiB。

請使用下列格式指定標量、清單或複合欄位：

$.fully.qualified.path.to.field

例如，請參考以下 JSON 回應：

{
  "routes" : [
    {
      "legs" : [
        {
          "distance" : {
            "text" : "2,064 mi",
            "value" : 3321004
          }
        }
      ]
    }
  ]
}

如要指定「value」欄位，請使用以下語法：

$.routes[0].legs[0].distance.value

彈性的 webhook 資源設定

以下說明彈性 Webhook 的 Webhook 資源設定：

使用預先定義的自訂範本

Dialogflow 提供預先定義的自訂範本，可用於將彈性 Webhook 與 Salesforce CRM 整合。

1. 在「管理」分頁下方，依序點選「Webhook」和「+ 建立」。

2. 在「子類型」下方，選取「彈性」。

3. 按一下「使用預先定義的範本進行設定」，即可啟用這項功能。

4. 在「Integration type」下拉式選單中，選取「Salesforce」。

5. 在「API 名稱」下拉式選單中，選取 API 名稱。範本會根據您選擇的 API 名稱，自動填入 webhook 表單。

   1. 您可以根據參數，手動設定下列欄位 (如適用)：

      • Webhook 網址
      • 方法
      • JSON 要求主體
      • 回應設定

   2. 驗證部分會醒目顯示 OAuth 必要欄位。

6. 按一下「儲存」即可建立 webhook。

Webhook 服務規定

您的 webhook 服務必須符合下列規定：

• 必須處理 HTTPS 要求。不支援 HTTP。如果您使用Compute 或無伺服器運算解決方案，在 Google Cloud Platform 上代管 webhook 服務，請參閱產品說明文件，瞭解如何透過 HTTPS 提供服務。如需其他代管選項，請參閱「取得網域的安全資料傳輸層 (SSL) 憑證」。
• 除非要求的網址是以 Cloud Run 資源形式託管，或以 服務目錄 webhook 形式存取，否則必須可公開存取。
• 必須依照「標準 Webhook」或「彈性 Webhook」一節所述的方式處理要求和回應。
• 如果您的服務代理未與 Service Directory 私人網路存取權整合，系統會將 webhook 呼叫視為服務範圍以外的內容，並在啟用 VPC Service Controls 時封鎖這些呼叫。Service Directory 支援的端點有限，詳情請參閱 Service Directory。

驗證

請務必保護 Webhook 服務，以便只有您或 Conversational Agents (Dialogflow CX) 代理程式有權提出要求。這項設定是在建立或編輯 webhook 資源時設定。Conversational Agents (Dialogflow CX) 支援下列驗證機制：

第三方 OAuth

Conversational Agents (Dialogflow CX) 可以從第三方 OAuth 供應商收集存取權權杖，並在發出 webhook 要求時將權杖新增至授權 HTTP 標頭。

以下說明第三方 OAuth 的資源設定：

傳送至 OAuth 端點網址以接收權杖的要求，不會包含為 Webhook 要求設定的自訂要求標頭。您可以將自訂資訊做為參數，透過 OAuth 端點網址的查詢字串傳遞至 OAuth 伺服器。

服務代理 ID 權杖

Conversational Agents (Dialogflow CX) 可使用 Conversational Agents (Dialogflow CX) 服務專員產生 ID 權杖。

當 Conversational Agents (Dialogflow CX) 呼叫 Webhook 時，系統會在授權 HTTP 標頭中加入權杖。

授予 Invoker 角色權限後，您就可以使用 ID 權杖存取 Cloud Run 資源

service-agent-project-number@gcp-sa-dialogflow.iam.gserviceaccount.com

用於產生 ID 權杖的目標對象將是整個 webhook 網址 (不含任何查詢參數)。如果您使用的是 Cloud Run，請確認 Cloud Run 目標對象支援這個網址。舉例來說，如果 webhook 網址為

https://myproject.cloudfunctions.net/my-function/method1?query=value

下列網址必須位於自訂目標對象中。

https://myproject.cloudfunctions.net/my-function/method1

任何 webhook 也可以視需要使用 Google 用戶端程式庫或開放原始碼程式庫 (例如 github.com/googleapis/google-auth-library-nodejs) 驗證權杖。

服務帳戶

服務帳戶可用於驗證任何支援的 Google API 的 webhook 要求。

如果您尚未建立服務帳戶，請建立。

由於服務帳戶是使用者，因此只要授予服務帳戶角色，即可存取專案中的資源，就像為任何其他使用者授予角色一樣。服務帳戶電子郵件會用來產生存取權存證，並在 webhook 要求的 Authorization 標頭中傳送。

設定 webhook 以使用服務帳戶的使用者必須具備下列權限：

• roles/iam.serviceAccountUser

如要讓 Conversational Agents (Dialogflow CX) 產生權杖，Dialogflow 服務專員必須具備下列權限：

• roles/iam.serviceAccountTokenCreator

服務帳戶也必須具備存取主機代管 webhook 的服務權限。

Secret Manager 驗證

如果您使用驗證標頭、含有使用者名稱和密碼的基本驗證，或第三方 OAuth，可以使用 Secret Manager 將憑證儲存為密鑰。以下是使用密鑰驗證 Webhook 的必要步驟：

1. 如果尚未建立機密金鑰，請建立機密金鑰。
2. 為新密鑰授予 Dialogflow 服務代理 Secret Manager 密鑰存取者 (roles/secretmanager.secretAccessor) 角色。
3. 將憑證複製到剪貼簿。
4. 新增密鑰版本。將憑證貼上做為 Secret 值。
   • 如果您使用驗證標頭，請輸入 Bearer <YOUR_CREDENTIAL>。
   • 如果您使用基本使用者名稱和密碼驗證，請改為輸入 <YOUR_USERNAME>:<YOUR_PASSWORD>。
   • 請省略結尾的任何換行字元。
5. 複製剛新增的密鑰版本名稱。名稱格式為 projects/{project_id}/secrets/{secret_id}/versions/{version_id}"。
6. 開啟 webhook 編輯畫面，然後執行以下操作：
   • 如果您使用驗證標頭，請建立新的密鑰版本要求標頭。將「Authorization」輸入「Key」，然後將密鑰版本名稱貼到「Secret version」輸入框。
   • 如果您使用基本驗證 (使用者名稱和密碼)，請按一下「基本驗證」下方的「密鑰版本」，然後將密鑰版本名稱貼到「密鑰版本」輸入框。
   • 如果您使用第三方 OAuth，請按一下「第三方 OAuth」下方的「Secret version」，然後將 Secret 版本名稱貼到「Secret version」輸入框。
7. 按一下 [儲存]。

HTTPS 憑證驗證

根據預設，Conversational Agents (Dialogflow CX) 會使用 Google 的預設信任存放區來驗證 HTTPS 憑證。如果您想使用 Google 的預設信任存放區不支援的 HTTPS 伺服器憑證，例如自行簽署的憑證或自訂根憑證，請參閱「自訂 CA 憑證」。

特定環境的 webhook

如果您使用環境將正式版系統與開發版系統區隔開來 (建議)，可以將 webhook 設為特定環境。針對您定義的每個 webhook 資源，您可以為代理程式定義的每個環境提供專屬的網址和驗證設定。

這樣一來，您就能在部署至正式環境前，安全地開發及測試 webhook 程式碼更新。

建立或編輯 Webhook 資源

Webhook 服務執行完畢後，您需要在 Bot 中建立 Webhook 資源，其中包含連線和驗證資訊。建立後，您隨時可以編輯 webhook 資源設定。

如要建立或編輯 webhook 資源，請按照下列步驟操作：

Webhook 錯誤

如果 webhook 服務在處理 webhook 要求時發生錯誤，則 webhook 程式碼應傳回下列其中一項 HTTP 狀態碼：

• 400 不正確的要求
• 401 未經授權
• 403 禁止
• 404 找不到
• 500 伺服器錯誤
• 503 服務無法使用

在下列任何錯誤情況下，Conversational Agents (Dialogflow CX) 會叫用 webhook 錯誤或逾時內建事件，並照常繼續處理：

• 回應逾時。
• 收到錯誤狀態碼。
• 回應無效。
• Webhook 服務無法使用。

此外，如果 webhook 服務呼叫是由 detectIntent API 呼叫觸發，則 detectIntent 回應中的 queryResult.webhookStatuses 欄位會包含 webhook 狀態資訊。

自動重試

Conversational Agents (Dialogflow CX) 內建機制可自動重試特定 webhook 錯誤，以提升健全性。只有非終端錯誤會重試 (例如逾時或連線錯誤)。

如要減少重複呼叫的可能性，請按照下列步驟操作：

• 設定較長的 webhook 逾時門檻。
• 在 webhook 邏輯中支援同構性或去重。

使用 Cloud Run

Conversational Agents (Dialogflow CX) 可與 Cloud Run 整合，讓您建立安全的無伺服器 webhook。如果您建立的 Cloud Run 資源與代理程式位於同一個專案中，請在驗證設定中選取「Service Agent Auth -> ID Token」，讓代理程式可安全地呼叫 webhook。

不過，有兩種情況下，您必須手動設定這項整合：

1. Conversational Agents (Dialogflow CX) 服務代理 服務帳戶必須具有下列地址，才能為您的服務專員專案運作：

   service-agent-project-number@gcp-sa-dialogflow.iam.gserviceaccount.com

   您為專案建立第一個代理程式時，系統通常會自動建立這個特殊服務帳戶和相關金鑰。如果您的代理程式是在 2020 年 11 月 1 日前建立，您可以觸發此特殊服務帳戶的建立程序：
   1. 為專案建立新的代理程式。
   2. 執行下列指令：

      gcloud beta services identity create --service=dialogflow.googleapis.com --project=agent-project-id

2. 如果 webhook 函式位於與代理程式不同的專案中，您必須為 Cloud Run 資源專案中的 Conversational Agents (Dialogflow CX) Service Agent 服務帳戶提供 Cloud Run Invoker 或 Cloud Functions Invoker IAM 角色。
3. 在「驗證」設定部分，依序選取「Service Agent Auth」->「ID Token」。

使用容器化 webhook 和 Go ezcx 架構

如果您想使用 Go 實作容器化 webhook，請參閱 Go ezcx 架構。這個架構可簡化建立 webhook 時所需的許多步驟。

搭配僅限內部流量使用 Cloud Run

只要代理程式位於相同專案或相同 VPC Service Controls 範圍內，Cloud Run 資源就能設定為接受相同專案或相同 VPC Service Controls 範圍內虛擬私有雲網路產生的內部流量，並用於 webhook。

使用 Service Directory 取得私人網路存取權

對話方塊 (Dialogflow CX) 會整合Service Directory 私人網路存取權，以便連線至虛擬私人雲端網路中的 webhook 目標。這麼做可確保流量保留在 Google Cloud 網路中，並強制執行 IAM 和 VPC Service Controls。

如要設定指定私人網路的 webhook，請按照下列步驟操作：

1. 請按照Service Directory 私人網路設定設定虛擬私有雲網路和 Service Directory 端點。

2. Conversational Agents (Dialogflow CX) 服務代理 服務帳戶必須具有下列地址，才能為您的服務專員專案運作：

   service-agent-project-number@gcp-sa-dialogflow.iam.gserviceaccount.com

   在服務目錄所在的專案中，將下列角色授予 Conversational Agents (Dialogflow CX) Service Agent 服務帳戶：

   • servicedirectory.viewer
   • servicedirectory.pscAuthorizedService

   此外，如果服務目錄位於與 Dialogflow CX 服務專員不同的專案中，您也必須將 servicedirectory.viewer 角色授予服務專員 (Dialogflow CX) 服務專員帳戶，該帳戶位於代管 Dialogflow CX 服務專員的專案中。

3. 建立 webhook 時，請一併提供 Service Directory 服務、網址和選用的驗證資訊。

   主控台

   

   API

   請參閱 Webhook 類型的 serviceDirectory 欄位。前往 Webhook API 參考資料

   選取 Webhook 參照的通訊協定和版本：

   通訊協定	V3	V3beta1
   REST	Webhook 資源	Webhook 資源
   RPC	Webhook 介面	Webhook 介面
   C++	WebhooksClient	不適用
   C#	WebhooksClient	不適用
   Go	WebhooksClient	不適用
   Java	WebhooksClient	WebhooksClient
   Node.js	WebhooksClient	WebhooksClient
   PHP	不適用	不適用
   Python	WebhooksClient	WebhooksClient
   Ruby	不適用	不適用

   關閉

如要排解問題，您可以設定私人運作時間檢查，確認 Service Directory 設定正確無誤。

範例和疑難排解

請參閱webhook 使用指南。