Webhook

Webhook 是托管业务逻辑或调用其他服务的服务。在会话期间，网络钩子可让您使用 Dialogflow CX 的自然语言处理技术所提取的数据来生成动态响应、验证收集的数据或在后端触发操作。

Webhook 可以是标准 Webhook，也可以是灵活 Webhook。对于标准网络钩子，请求和响应字段由 Dialogflow CX 定义。使用灵活的 webhook 时，您可以定义请求和响应字段。

您还可以使用 $request.webhook_status_code 请求参数访问 webhook 调用的 HTTP 状态代码。

标准网络钩子

使用标准网络钩子时，您可以使用 Dialogflow CX 定义的请求和响应消息。请求消息提供了有关会话的许多详细信息。例如，当前活跃页面、最近匹配的 intent、会话参数值和代理定义的回答都包含在内。

标准网络钩子请求

当调用具有网络钩子的执行方式时，Dialogflow CX 会向您的网络钩子服务发送 HTTPS POST 网络钩子请求。此请求的正文是一个 WebhookRequest JSON 对象，其中包含有关会话的信息。

某些集成会使用其他信息填充 WebhookRequest.payload 字段。例如，Dialogflow CX 电话网关集成会提供最终用户来电显示。

如需了解详情，请参阅 WebhookRequest (V3) 或 WebhookRequest (V3Beta1) 参考文档。

标准网络钩子响应

Webhook 服务收到请求后，必须发送满足以下要求的响应：

如需了解详情，请参阅 WebhookResponse (V3) 或 WebhookResponse (V3Beta1) 参考文档。

标准 webhook 资源设置

下表介绍了标准网络钩子的网络钩子资源设置：

X 项
显示名称 在控制台中显示的 webhook 名称。
网络钩子超时 当 Dialogflow CX 向您的 webhook 服务发送 HTTP 请求时，此设置控制每次请求尝试的超时时间（以秒为单位），而不是整个对话轮次的超时时间。如果尝试超时或因暂时性错误而失败，Dialogflow CX 会自动重试一次。这种重试可能会导致总周转时间达到所配置超时值的两倍，然后才会返回错误。如果重试后发生超时，Dialogflow CX 会调用 webhook.error.timeout 事件。如需了解详情，请参阅自动重试。
类型 如果您使用 Service Directory 进行专用网络访问，请设置为 Service Directory，否则设置为通用 Web 服务。
网络钩子网址 提供 Webhook 服务的网址。
子类型 设置为标准。
特定于环境的 webhook 您可以提供特定于环境的 webhook。
身份验证 请参阅“身份验证”部分。
自定义 CA 证书 此选项用于上传自定义 CA 证书。

灵活的 webhook

借助灵活的 webhook，您可以定义请求 HTTP 方法、请求网址参数以及请求和响应消息的字段。请求只能提供所选参数值，响应只能提供参数替换值。这简化了代理与网络钩子之间的接口，因为除了会话参数值之外，几乎不需要传达任何其他内容。它还简化了 webhook 实现，因为请求和响应消息仅包含您需要的内容，并且您可以为各种场景提供唯一的 webhook 消息。

灵活的网络钩子请求

为代理创建 webhook 资源时，您可以为 webhook 请求指定以下内容：

  • 用于向您的 webhook 服务发送 webhook 请求的 HTTP 方法。
  • Dialogflow CX 应使用网址发送到 webhook 服务的会话参数值。
  • 如果您选择 POST、PUT 或 PATCH 作为方法，则 Dialogflow CX 应通过请求 JSON 正文发送到 webhook 服务的会话参数值。

如需使用请求网址或 JSON 正文发送会话参数值，请使用参数引用。您无需对参数引用进行网址转义，也无需将其用引号括起来。在运行时，Dialogflow CX 会根据需要对参数值进行网址转义。列表或复合值以 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 响应的特定字段的会话参数。

您的回答必须满足以下限制：

  • 响应必须在创建网络钩子资源时配置的超时时间内发生，否则请求将超时。
  • 响应的大小不得超过 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 资源设置

下表介绍了灵活网络钩子的网络钩子资源设置。

X 项
显示名称 在控制台中显示的 webhook 名称。
网络钩子超时 当 Dialogflow CX 向您的 webhook 服务发送 HTTP 请求时，此设置控制每次请求尝试的超时时间（以秒为单位），而不是整个对话轮次的超时时间。如果尝试超时或因暂时性错误而失败，Dialogflow CX 会自动重试一次。这种重试可能会导致总周转时间达到所配置超时值的两倍，然后才会返回错误。如果重试后发生超时，Dialogflow CX 会调用 webhook.error.timeout 事件。如需了解详情，请参阅自动重试。
类型 如果您使用 Service Directory 进行专用网络访问，请设置为 Service Directory，否则设置为通用 Web 服务。
网络钩子网址 提供 Webhook 服务的网址，其中可能包含对会话参数的引用。
子类型 设置为灵活。
方法 设置 Webhook 请求的 HTTP 方法。
请求正文 如上所述，提供请求 JSON 正文。
回答配置 提供应设置为响应字段的会话参数，如上所述。
特定于环境的 webhook 您可以提供特定于环境的 webhook
身份验证 请参阅身份验证部分。
自定义 CA 证书 此选项用于上传自定义 CA 证书。

使用预定义的自定义模板

Dialogflow 提供预定义的自定义模板，您可以使用这些模板将灵活的 webhook 与 Salesforce CRM 集成。

  1. 前往管理标签页，选择 Webhook，然后点击创建。
  2. 在子类型下，选择灵活。
  3. 点击使用预定义模板进行配置。
  4. 在集成类型菜单中，选择 Salesforce。
  5. 在 API 名称菜单中，选择一个 API 名称。该模板会根据您选择的 API 名称自动填写 webhook 表单。
    1. 根据您的参数，手动配置以下字段（如果适用）：
      • 网络钩子网址
      • 方法
      • 请求正文 JSON
      • 回答配置
    2. 所需的 OAuth 字段将在身份验证部分中突出显示。
  6. 点击保存。

网络钩子服务要求

您的 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 令牌的受众群体是整个网络钩子网址（不包括任何查询参数）。如果您使用的是 Cloud Run，请确保 Cloud Run 受众群体支持此网址。

例如，如果网络钩子网址为：

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 Service Agent 必须具有以下权限：

  • roles/iam.serviceAccountTokenCreator

服务账号还必须具有访问托管 webhook 的服务的权限。

Secret Manager 身份验证

如果您使用身份验证标头、使用用户名和密码的基本身份验证或第三方 OAuth，则可以使用 Secret Manager 将凭据存储为 Secret。以下是使用密钥对 webhook 进行身份验证的必要步骤：

  1. 如果您没有密钥，请创建密钥。
  2. 为 Dialogflow Service Agent 授予新 Secret 的 Secret Manager Secret Accessor (roles/secretmanager.secretAccessor) 角色。
  3. 将凭证复制到剪贴板。
  4. 向 Secret 添加新的 Secret 版本，并将凭据粘贴为 Secret 值：
    • 如果您使用身份验证标头，请输入 Bearer <YOUR_CREDENTIAL>。
    • 如果您使用基本的用户名和密码身份验证，请输入 <YOUR_USERNAME>:<YOUR_PASSWORD>。
    • 省略末尾的所有换行符。
  5. 复制您添加的 Secret 版本的名称。名称格式为 projects/<var>PROJECT_ID</var>/secrets/<var>SECRET_ID</var>/versions/<var>VERSION_ID</var>。
  6. 打开 webhook 修改界面。
  7. 配置身份验证设置：
    • 如果您使用身份验证标头，请创建新的 Secret 版本请求标头。在密钥字段中输入“Authorization”，然后将 Secret 版本名称粘贴到 Secret 版本字段中。
    • 对于基本用户名和密码身份验证，请点击基本身份验证下的 Secret 版本，然后将 Secret 版本名称粘贴到 Secret 版本字段中。
    • 如果您使用第三方 OAuth，请点击第三方 OAuth 下的密钥版本，然后将密钥版本名称粘贴到密钥版本字段中。
  8. 点击保存。

HTTPS 证书验证

默认情况下，Dialogflow CX 使用 Google 的默认受信任证书存储区来验证 HTTPS 证书。如果您打算为 HTTPS 服务器使用 Google 默认受信任证书存储区无法识别的证书（例如自签名证书或自定义根证书），请参阅自定义 CA 证书。

特定于环境的 webhook

如果您使用环境将生产与开发隔离开来，则可以将网络钩子配置为特定于环境。您可以为每个 webhook 资源提供特定于环境的网址和身份验证设置。

通过此配置，您可以安全地开发和测试 webhook 代码更新，然后再将其部署到生产环境。

创建或修改 webhook 资源

运行网络钩子服务后，在代理中创建网络钩子资源，其中包含连接和身份验证信息。您可以随时修改 webhook 资源设置。

如需创建或修改 webhook 资源，请执行以下操作：

控制台

  1. 打开 Dialogflow CX 控制台。
  2. 前往您的项目。
  3. 选择您的代理。
  4. 点击管理标签页。
  5. 点击网络钩子。
  6. 点击创建，或选择现有 webhook 进行修改。
  7. 配置标准 webhook 资源设置或灵活 webhook 资源设置。
  8. 点击保存。

API

如需了解如何创建 webhook 资源，请参阅 Webhook 类型的 create 方法。如需了解如何修改 webhook 资源（环境特定设置除外），请参阅 Webhook 类型的 patch 或 update 方法。

为网络钩子参考选择协议和版本：

协议 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 不可用 不可用

如需了解如何修改 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
Ruby 不可用 不可用

网络钩子错误

如果您的 webhook 服务在处理 webhook 请求时遇到错误，您的 webhook 代码应返回以下 HTTP 状态代码之一：

  • 400：请求无效
  • 401：未经授权
  • 403：禁止访问
  • 404：未找到
  • 500：服务器故障
  • 503：服务不可用

在以下错误情况下，Dialogflow CX 会调用网络钩子错误或超时内置事件，并照常继续处理：

  • 响应超时。
  • 收到错误状态代码。
  • 回答无效。
  • Webhook 服务不可用。

如果 webhook 服务调用是由检测 intent API 调用触发的，则检测 intent 响应中的 queryResult.webhookStatuses 字段包含 webhook 状态信息。

自动重试

Dialogflow CX 会在发生某些网络钩子错误时自动重试请求，以提高稳健性。自动重试默认处于启用状态，并且无法停用。

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 资源与代理位于同一项目中，请在身份验证配置中选择服务代理身份验证，然后选择身份令牌，以便代理可以安全地调用 webhook。

在以下两种情况下，您必须手动设置此集成：

  1. 您的代理项目必须存在具有以下地址的 Dialogflow CX Service Agent 服务账号：
    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 资源项目中的 Dialogflow CX Service Agent 服务账号提供 Cloud Run Invoker 或 Cloud Functions Invoker IAM 角色。

接下来，在身份验证配置部分中，依次选择服务代理身份验证 > 身份令牌。

使用容器化 webhook 和 Go ezcx 框架

如需使用 Go 实现容器化 webhook，请参阅 Go ezcx 框架。此框架简化了创建 webhook 所需的许多步骤。

将 Cloud Run 与仅限内部流量搭配使用

您可以使用配置为接受来自同一项目或同一 VPC Service Controls 边界内的 Virtual Private Cloud (VPC) 网络的内部流量的 Cloud Run 资源作为 webhook，前提是代理位于同一项目或同一 VPC Service Controls 边界内。

使用 Service Directory 进行专用网络访问

Dialogflow CX 与 Service Directory 专用网络访问集成，因此可以连接到 VPC 网络内的网络钩子目标。这样可以将流量保持在 Google Cloud 网络内，并强制执行 IAM 和 VPC Service Controls。

如需设置以专用网络为目标的网络钩子，请执行以下操作：

  1. 按照 Service Directory 专用网络配置中的说明配置 VPC 网络和 Service Directory 端点。

  2. 您的代理项目必须存在具有以下地址的 Dialogflow CX 服务代理 服务账号：

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

    在 Service Directory 所在的项目中，向 Dialogflow CX Service Agent 服务账号授予以下角色：

    • servicedirectory.viewer
    • servicedirectory.pscAuthorizedService

    此外，如果您的 Service Directory 与 Dialogflow CX 智能体位于不同的项目中，您还需要向托管 Dialogflow CX 智能体的项目中的 Dialogflow CX Service Agent 账号授予 servicedirectory.viewer 角色。

  3. 在创建网络钩子时，指定 Service Directory 服务、网址和任何可选的身份验证信息。

    控制台

    Service Directory 网络钩子屏幕截图。

    API

    请参阅 Webhook 类型的 serviceDirectory 字段。

    为网络钩子参考选择协议和版本：

    协议 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 操作指南。

上一页
Fulfillment
下一页
生成器