Webhook

Webhook 是代管商業邏輯或呼叫其他服務的服務。 在工作階段期間，您可以透過 Webhook 使用 Dialogflow CX 自然語言處理程序擷取的資料，產生動態回應、驗證收集到的資料，或在後端觸發動作。

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

您也可以使用 $request.webhook_status_code 要求參數，存取 Webhook 呼叫的 HTTP 狀態碼。

標準 Webhook

使用標準 Webhook 時，您會使用 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 資源時設定的逾時時間。
  • 回覆大小不得超過 64 KiB。

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

標準 Webhook 資源設定

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

X 項目
顯示名稱 Webhook 在控制台中顯示的名稱。
Webhook 逾時 當 Dialogflow CX 向 Webhook 服務傳送 HTTP 要求時，這項設定會控管每次嘗試要求時的逾時秒數，而非整體對話回合。如果嘗試逾時或因暫時性錯誤而失敗，Dialogflow CX 會自動重試一次。重試後，系統可能會在總處理時間達到設定逾時值的兩倍時，才傳回錯誤。如果重試後發生逾時，Dialogflow CX 會叫用 webhook.error.timeout 事件。詳情請參閱「自動重試」。
類型 如果您使用 Service Directory 進行私人網路存取，請設為「Service Directory」，否則請設為「Generic web service」。
Webhook 網址 提供 Webhook 服務的網址。
子類型 設為「標準」。
特定環境的 Webhook 您可以提供環境專屬的 Webhook。
驗證 請參閱驗證專區。
自訂 CA 憑證 用於上傳自訂 CA 憑證。

彈性 Webhook

使用彈性 Webhook 時，您可以定義要求 HTTP 方法、要求網址參數，以及要求和回應訊息的欄位。要求只能提供所選參數值，回應也只能提供參數覆寫值。這樣一來，代理程式和 Webhook 之間的介面就會簡化，因為除了工作階段參數值之外，很少需要傳送其他內容。此外，由於要求和回應訊息只包含您需要的內容，且您可以為各種情境提供專屬的 Webhook 訊息，因此也能簡化 Webhook 實作程序。

彈性 Webhook 要求

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

  • 傳送至 Webhook 服務的 Webhook 要求所用的 HTTP 方法。
  • Dialogflow CX 應使用網址傳送至 Webhook 服務的工作階段參數值。
  • 如果您選擇 POST、PUT 或 PATCH 做為方法，Dialogflow CX 應透過要求 JSON 內文傳送至 Webhook 服務的工作階段參數值。

如要使用要求網址或 JSON 內文傳送工作階段參數值，請使用參數參照。您不需要對參數參照進行網址逸出，也不必加上引號。在執行時，Dialogflow CX 會根據需要對參數值進行 URL 轉義。清單或複合值以 JSON 格式提供。

在 JSON 主體中使用參數參照時，無論參數類型為何，都必須將參照括在引號中。如果參數實際上是數值純量、清單或複合值，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 資源時，您可以指定 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 資源設定。

X 項目
顯示名稱 Webhook 在控制台中顯示的名稱。
Webhook 逾時 當 Dialogflow CX 向 Webhook 服務傳送 HTTP 要求時，這項設定會控管每次嘗試要求時的逾時秒數，而非整體對話回合。如果嘗試逾時或因暫時性錯誤而失敗，Dialogflow CX 會自動重試一次。重試後，系統可能會在總處理時間達到設定逾時值的兩倍時，才傳回錯誤。如果重試後發生逾時，Dialogflow CX 會叫用 webhook.error.timeout 事件。詳情請參閱「自動重試」。
類型 如果您使用 Service Directory 進行私人網路存取，請設為「Service Directory」，否則請設為「Generic web service」。
Webhook 網址 提供 Webhook 服務的網址，其中可能包含工作階段參數的參照。
子類型 設為「彈性」。
方法 設定 Webhook 要求的 HTTP 方法。
要求主體 如上所述，提供 JSON 要求主體。
回覆設定 提供應設為回應欄位的會期參數，如上所述。
特定環境的 Webhook 您可以提供環境專屬的 Webhook
驗證 請參閱驗證部分。
自訂 CA 憑證 用於上傳自訂 CA 憑證。

使用預先定義的自訂範本

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

  1. 前往「管理」分頁標籤，選取「Webhook」，然後點選「建立」。
  2. 在「Subtype」(子類型) 下方選取「Flexible」(彈性)。
  3. 按一下「使用預先定義的範本設定」。
  4. 在「整合類型」選單中，選取「Salesforce」。
  5. 在 API 名稱 選單中，選擇一個 API 名稱。範本會根據您選擇的 API 名稱，自動填寫 Webhook 表單。
    1. 根據參數手動設定下列欄位 (如適用)：
      • Webhook 網址
      • 方法
      • 要求主體 JSON
      • 回覆設定
    2. 「Authentication」(驗證) 部分會醒目顯示必要的 OAuth 欄位。
  6. 按一下 [儲存]。

Webhook 服務規定

Webhook 服務必須符合下列規定：

驗證

保護 Webhook 服務，確保只有您或 Dialogflow CX 虛擬服務專員可以提出要求。建立或編輯 Webhook 資源時，請設定這項屬性。 Dialogflow CX 支援下列驗證機制：

X 項目
驗證標頭 如要設定 Webhook，可以指定選用的 HTTP 標頭鍵/值組合。如果提供這些標頭，Dialogflow CX 會將這些 HTTP 標頭新增至 Webhook 要求。通常會提供單一鍵值對，且鍵為 authorization。標頭值支援工作階段參數參照和系統函式剖析，就像靜態回應訊息一樣。如果您使用 authorization 標頭的靜態憑證，建議您使用 Secret Manager 提供憑證。
使用使用者名稱和密碼進行基本驗證 在 Webhook 設定中，您可以指定選用的登入使用者名稱和密碼值。如果提供這項資訊，Dialogflow CX 會在 Webhook 要求中新增授權 HTTP 標頭。這個標頭的格式為："authorization: Basic <base 64 encoding of the string username:password>"。建議您使用 Secret Manager 提供使用者名稱和密碼。
第三方 OAuth 您可以指定第三方 OAuth 設定，讓 Dialogflow CX 從 OAuth 系統交換存取權杖，並將其新增至授權 HTTP 標頭。僅支援用戶端憑證流程。建議您使用 Secret Manager 提供用戶端密鑰。
服務代理存取權杖 已停售。
服務帳戶 您可以使用服務帳戶進行驗證。可用於存取其他 Google Cloud API。
服務代理 ID 權杖 您可以在「服務代理驗證」部分選擇 ID 權杖，使用服務代理 ID 權杖進行驗證。這樣一來，您就能存取 Cloud Run 資源。
雙向傳輸層安全標準 (TLS) 驗證 請參閱雙向傳輸層安全標準 (TLS) 驗證說明文件。

第三方 OAuth

Dialogflow CX 會從第三方 OAuth 提供者收集存取權杖，並在發出 Webhook 要求時，將權杖新增至授權 HTTP 標頭。

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

X 項目
用戶端 ID 要求 OAuth 權杖時要使用的用戶端 ID。
用戶端密鑰 要求 OAuth 權杖時要使用的密鑰。建議您使用 Secret Manager 提供用戶端密鑰。
OAuth 端點網址 用來要求 OAuth 權杖的網址。
OAuth 範圍 以逗號分隔的範圍清單，OAuth 權杖可用於這些範圍。

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

服務代理 ID 權杖

Dialogflow CX 可使用 Dialogflow CX 服務代理程式產生 ID 權杖。Dialogflow CX 呼叫 Webhook 時，系統會將這個權杖新增至 Authorization HTTP 標頭。

授予Cloud Run Invoker 角色 (roles/run.invoker) 後，您可以使用 ID 權杖存取 Cloud Run 資源。

service-agent-project-number@gcp-sa-dialogflow.iam.gserviceaccount.com
 如果 Cloud Run 資源位於同一個資源專案中，您不需要額外的 Identity and Access Management (IAM) 權限即可呼叫這些資源。

產生 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 用戶端程式庫或開放原始碼程式庫 (例如 Node.js 適用的 Google Auth 程式庫) 驗證權杖。

如果您的 Webhook 託管於 Cloud Run，並透過負載平衡器存取，請將負載平衡器的網址新增為 Cloud Run 的自訂目標對象。如要進一步瞭解自訂目標對象，請參閱「設定服務的自訂目標對象」。

服務帳戶

服務帳戶可用於驗證對任何支援服務帳戶的 Google API 發出的 Webhook 要求。

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

由於服務帳戶是主體，因此可以授予角色，存取專案中的資源，就像其他主體一樣。服務帳戶電子郵件地址用於產生存取權杖，並在 Webhook 要求的 Authorization 標頭中傳送。

如要設定 Webhook 使用服務帳戶，您必須具備下列權限：

  • roles/iam.serviceAccountUser

如要產生權杖，Dialogflow 服務代理必須具備下列權限：

  • roles/iam.serviceAccountTokenCreator

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

Secret Manager 驗證

如果您使用驗證標頭、基本驗證 (含使用者名稱和密碼)，或第三方 OAuth，可以使用 Secret Manager 將憑證儲存為 Secret。如要使用私密金鑰驗證 Webhook，請按照下列步驟操作：

  1. 如果沒有 Secret，請建立一個。
  2. 授予 Dialogflow 服務代理程式新密鑰的 Secret Manager 密鑰存取者 (roles/secretmanager.secretAccessor) 角色。
  3. 將憑證複製到剪貼簿。
  4. 在密鑰中新增密鑰版本，然後將憑證貼為密鑰值：
    • 如果您使用驗證標頭，請輸入 Bearer <YOUR_CREDENTIAL>。
    • 如果您使用基本使用者名稱和密碼驗證，請輸入 <YOUR_USERNAME>:<YOUR_PASSWORD>。
    • 結尾請省略任何換行字元。
  5. 複製您新增的密鑰版本名稱。名稱格式為 projects/<var>PROJECT_ID</var>/secrets/<var>SECRET_ID</var>/versions/<var>VERSION_ID</var>。
  6. 開啟網路鉤子編輯畫面。
  7. 設定驗證機制：
    • 如果您使用驗證標頭，請建立新的密鑰版本要求標頭。在「Key」欄位中輸入「Authorization」，然後將密鑰版本名稱貼到「Secret version」欄位。
    • 如要進行基本使用者名稱和密碼驗證，請按一下「基本驗證」下方的「密鑰版本」，然後將密鑰版本名稱貼到「密鑰版本」欄位。
    • 如果您使用第三方 OAuth，請按一下「第三方 OAuth」下方的「密鑰版本」，然後將密鑰版本名稱貼到「密鑰版本」欄位。
  8. 按一下 [儲存]。

HTTPS 憑證驗證

Dialogflow CX 預設會使用 Google 的預設信任存放區驗證 HTTPS 憑證。如果您打算使用 Google 預設信任存放區無法辨識的憑證 (例如自行簽署的憑證或自訂根憑證) 做為 HTTPS 伺服器憑證，請參閱「自訂 CA 憑證」。

特定環境的 Webhook

如果您使用環境將正式版與開發版隔離，可以將網路鉤子設定為環境專屬。您可以為每個 Webhook 資源提供環境專屬的網址和驗證設定。

您可以在這個設定中安全地開發及測試 Webhook 程式碼更新，再部署至正式環境。

建立或編輯 Webhook 資源

執行 Webhook 服務後，請在代理程式中建立 Webhook 資源，其中包含連線和驗證資訊。您隨時可以編輯 Webhook 資源設定。

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

控制台

  1. 開啟 Dialogflow CX 控制台。
  2. 前往專案。
  3. 選取代理程式。
  4. 按一下「管理」分頁標籤。
  5. 按一下「Webhook」。
  6. 按一下「建立」，或選取現有 Webhook 進行編輯。
  7. 設定標準 Webhook 資源設定或彈性 Webhook 資源設定。
  8. 按一下 [儲存]。

API

如要瞭解如何建立 Webhook 資源，請參閱 Webhook 類型的 create 方法。如要瞭解如何編輯 Webhook 資源 (環境專屬設定除外)，請參閱 Webhook 類型的 patch 或 update 方法。

為 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
小茹 不適用 不適用

如要瞭解如何編輯 Webhook 的環境專屬設定，請參閱 Environment 類型的 patch 或 update 方法。

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

通訊協定 V3 V3beta1
REST 環境資源 環境資源
RPC 環境介面 環境介面
C++ EnvironmentsClient 不適用
C# EnvironmentsClient 不適用
Go EnvironmentsClient 不適用
Java EnvironmentsClient EnvironmentsClient
Node.js EnvironmentsClient EnvironmentsClient
PHP 不適用 不適用
Python EnvironmentsClient EnvironmentsClient
小茹 不適用 不適用

Webhook 錯誤

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

  • 400：要求無效
  • 401：未獲授權
  • 403：禁止存取
  • 404：找不到
  • 500：伺服器錯誤
  • 503：服務無法使用

在下列錯誤情況中，Dialogflow CX 會叫用 Webhook 錯誤或逾時內建事件，並照常繼續處理：

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

如果 Webhook 服務呼叫是由 detect intent API 呼叫觸發，detect intent 回應中的 queryResult.webhookStatuses 欄位會包含 Webhook 狀態資訊。

自動重試

Dialogflow CX 會在發生特定 Webhook 錯誤時自動重試要求，以提升穩定性。自動重試功能預設為啟用，且無法停用。

Dialogflow CX 會針對暫時性失敗執行單一重試，例如要求逾時、網路連線中斷，以及 5xx 範圍內的 HTTP 狀態碼 (例如 500 Server fault 或 503 Service unavailable)。終端用戶端錯誤 (例如 HTTP 狀態碼 404 Not found) 會立即失敗，不會重試。

累計延遲時間和逾時預算

由於 Dialogflow CX 會重試暫時性失敗一次，因此如果 Webhook 端點沒有回應，Dialogflow CX 最多可能需要等待設定的逾時值兩倍的時間，才會傳回錯誤。舉例來說，如果逾時設定為預設的 5 秒，無回應的端點會在第一次嘗試後逾時 5 秒，重試後再逾時 5 秒。因此，Dialogflow CX 呼叫錯誤處理常式 (例如 webhook.error.timeout 事件處理常式或 sys.no-match-default 事件處理常式) 前，總延遲時間約為 10 秒。

如果您的架構有嚴格的上游延遲時間限制 (例如電話或互動式語音回應 (IVR) 系統會在 10 秒逾時視窗後終止通話)，請將網路鉤子逾時時間設為允許視窗的一半 (例如 2.5 到 4 秒之間)，為兩次嘗試預留時間。

重試的最佳做法

如要在 Webhook 服務中有效處理重試要求，請採取下列做法：

  • 在 Webhook 服務邏輯中導入冪等或要求簡化功能，安全地處理重複要求。
  • 如果 Webhook 作業超過設定的逾時時間，請立即傳回 HTTP 狀態碼 200 OK 回應和備用訊息，並以非同步方式處理長時間執行的工作。

使用 Cloud Run

Dialogflow CX 與 Cloud Run 整合，因此您可以建立安全的無伺服器 Webhook。如果您建立的 Cloud Run 資源與代理程式位於同一專案，請選取「服務代理程式驗證」，然後在驗證設定中選取「ID 權杖」，讓代理程式安全地呼叫 Webhook。

在下列兩種情況中，您必須手動設定這項整合：

  1. 虛擬服務專員專案必須有下列地址的 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 資源專案中，將 Cloud Run Invoker 或 Cloud Functions Invoker IAM 角色提供給 Dialogflow CX 服務代理服務帳戶。

接著，在「Auth configuration」(驗證設定) 專區中，選取「Service Agent Auth」>「ID Token」(服務代理程式驗證 > ID 權杖)。

使用容器化 Webhook 和 Go ezcx 架構

如要使用 Go 實作容器化 Webhook，請參閱 Go ezcx 架構。這個框架簡化了建立 Webhook 的許多必要步驟。

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

只要代理程式位於相同專案或相同 VPC Service Controls 範圍內，您就可以使用設定為接受來自相同專案或相同 VPC Service Controls 範圍內虛擬私有雲 (VPC) 網路內部流量的 Cloud Run 資源做為 Webhook。

使用 Service Directory 存取私人網路

Dialogflow CX 與 Service Directory 私人網路存取權整合，因此可以連線至虛擬私有雲網路中的 Webhook 目標。這樣可確保流量留在 Google Cloud 網路中，並強制執行 IAM 和 VPC Service Controls。

如要設定以私人網路為目標的 Webhook，請按照下列步驟操作：

  1. 按照服務目錄私人網路設定，設定虛擬私有雲網路和服務目錄端點。

  2. 您的虛擬服務專員專案必須有 Dialogflow CX 服務代理 服務帳戶，且地址如下：

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

    在 Service Directory 所在的專案中，將下列角色授予 Dialogflow CX 服務代理服務帳戶：

    • servicedirectory.viewer
    • servicedirectory.pscAuthorizedService

    此外，如果您的服務目錄與 Dialogflow CX 服務專員位於不同專案，您也需要在 Dialogflow CX 服務專員所在的專案中，將 servicedirectory.viewer 角色授予 Dialogflow CX 服務代理帳戶。

  3. 建立 Webhook 時，請指定 Service Directory 服務、網址和任何選用驗證資訊。

    控制台

    Service Directory Webhook 螢幕截圖。

    API

    如需 Webhook 類型，請參閱 serviceDirectory 欄位。

    為 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
    小茹 不適用 不適用

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

範例和疑難排解

詳情請參閱 Webhook 使用指南。

上一頁
執行要求
下一頁
發電機