网络钩子

网络钩子是托管您的业务逻辑的服务。在会话期间,借助网络钩子,开发者可以使用通过 Dialogflow 的自然语言处理提取的数据来生成动态响应、验证收集的数据或在后端触发操作。

CX 网络钩子类似于 ES 网络钩子,不同之处在于为支持 CX 功能而更改了请求和响应字段。

网络钩子服务要求

您的网络钩子服务必须满足以下要求:

  • 它必须处理 HTTPS 请求。不支持 HTTP。如果您使用计算无服务器计算解决方案在 Google Cloud Platform 上托管网络钩子服务,请参阅使用 HTTPS 服务的产品文档。对于其他托管项,请参阅获取您网域的 SSL 证书
  • 其请求的网址须可公开访问。
  • 它必须使用 JSON WebhookRequest 正文处理 POST 请求。
  • 它必须使用 JSON WebhookResponse 正文来响应 WebhookRequest 请求。

身份验证

请务必保护您的网络钩子服务,确保只有您或您的 Dialogflow 代理才有权发出请求。这是在创建网络钩子资源时进行配置。Dialogflow CX 支持以下身份验证机制:

网络钩子请求

调用具有网络钩子的 fulfillment 时,Dialogflow 会向您的网络钩子服务发送 HTTPS POST 网络钩子请求。此请求的正文是一个 JSON 对象,其中包含有关匹配意图的信息。

如需了解详情,请参阅 WebhookRequest 参考文档。

网络钩子响应

一旦网络钩子服务收到网络钩子请求,其需要发送一个网络钩子响应。您的响应会受到以下限制:

  • 响应必须在您创建网络钩子资源时配置的超时时间内发生,否则请求将超时。
  • 响应大小不得超过 64 KiB。

如需了解详情,请参阅 WebhookResponse 参考文档。

创建网络钩子资源

运行网络钩子服务后,您需要在代理中创建具有连接和身份验证信息的网络钩子资源。要创建网络钩子资源,请执行以下操作:

控制台

  1. 打开 Dialogflow CX 控制台
  2. 选择 GCP 项目。
  3. 选择您的代理。
  4. 选择管理标签页。
  5. 点击网络钩子
  6. 点击创建
  7. 输入网络钩子数据。
  8. 点击保存

API

请参阅 Webhook 类型的 create 方法。

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

协议 V3 V3beta1
REST 网络钩子资源 网络钩子资源
RPC 网络钩子界面 网络钩子界面
C# 不可用 不可用
Go 不可用 不可用
Java WebhooksClient WebhooksClient
Node.js WebhooksClient WebhooksClient
PHP 不可用 不可用
Python WebhooksClient WebhooksClient
Ruby 不可用 不可用

网络钩子错误

如果您的网络钩子服务在处理网络钩子请求时发生错误,则网络钩子代码应返回以下某个 HTTP 状态代码:

  • 400 Bad Request
  • 401 Unauthorized
  • 403 Forbidden
  • 404 Not found
  • 500 Server fault
  • 503 Service Unavailable

在以下任何一种错误情况下,Dialogflow 都会调用网络钩子错误或超时内置事件,并继续照常处理:

  • 响应已超时。
  • 收到错误状态代码。
  • 无效响应。
  • 网络钩子服务不可用。

此外,如果网络钩子服务调用是由检测意图 API 调用触发的,则检测意图响应中的 queryResult.webhookStatuses 字段包含网络钩子状态信息。

使用 Cloud Functions

Dialogflow 与 Cloud Functions 相集成,因此您可以轻松创建安全的无服务器网络钩子。如果您创建了一个与您的代理位于同一项目的函数,则您的代理可以安全地调用您的网络钩子,而无需任何特殊配置。

不过,在以下两种情况下,您必须手动设置此集成:

  1. 代理项目必须具有以下 Dialogflow 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. 如果网络钩子函数位于与代理不同的项目中,则必须提供 Cloud Functions Invoker IAM 角色 Dialogflow 服务代理服务帐号。

服务身份令牌

Dialogflow 调用网络钩子时,会为请求提供 Google 身份令牌。任何网络钩子都可以选择性地使用 Google 客户端库或 github.com/googleapis/google-auth-library-nodejs 等开源库验证令牌。