本指南介绍如何使用 webhook,让您的代理更具动态性。Cloud Functions 因其简单易用而用于托管 webhook,但您还可以通过许多其他方式托管 webhook 服务。该示例也使用 Go 编程语言,但您可以使用 Cloud Functions 支持的语言。您无需修改本指南的代码。
示例 webhook 代码会执行以下操作:
- 从 webhook 请求中读取参数值。
- 将参数值写入 webhook 响应。
- 在 webhook 响应中提供文本响应。
准备工作
如果您不打算使用 webhook,可以跳过此快速入门。
在阅读本指南之前,请先完成以下事项:
- 阅读 Dialogflow CX 基础知识。
- 执行设置步骤。
- 执行构建代理快速入门指南中的步骤。以下步骤将继续处理同一代理。如果您不再拥有该代理,可以下载该代理并恢复该代理。
创建 Cloud Function
您可以通过 Google Cloud 控制台创建 Cloud Functions 函数(查看文档,打开控制台)。如需针对本指南创建函数,请执行以下操作:
- 您的 Dialogflow 代理和函数必须位于同一项目中,这一点非常重要。这是 Dialogflow 要安全访问函数的最简单方法。如需选择项目,请转到项目选择器。
- 转到 Cloud Functions 概览页面。
- 点击创建函数,然后设置以下字段:
- 环境:第 1 代
- 函数名称:shirts-agent-webhook
- 区域:如果您为代理指定了区域,请使用同一区域。
- HTTP Trigger type:HTTP
- 网址:点击此处的复制按钮并保存相应的值。 配置 webhook 时需要使用此网址。
- Authentication:需要身份验证
- Require HTTPS(需要 HTTPS):选中
- 点击保存。
- 点击下一步(您不需要特殊的运行时、构建、连接或安全设置)。
- 设置以下字段:
- Runtime:选择最新的 Go 运行时。
- 源代码:内嵌编辑器
- 入口点:HandleWebhookRequest
- 将代码替换为以下代码:
// Package cxwh contains an example Dialogflow CX webhook package cxwh import ( "encoding/json" "fmt" "log" "net/http" ) type fulfillmentInfo struct { Tag string `json:"tag"` } type sessionInfo struct { Session string `json:"session"` Parameters map[string]interface{} `json:"parameters"` } type text struct { Text []string `json:"text"` } type responseMessage struct { Text text `json:"text"` } type fulfillmentResponse struct { Messages []responseMessage `json:"messages"` } // webhookRequest is used to unmarshal a WebhookRequest JSON object. Note that // not all members need to be defined--just those that you need to process. // As an alternative, you could use the types provided by the Dialogflow protocol buffers: // https://pkg.go.dev/google.golang.org/genproto/googleapis/cloud/dialogflow/cx/v3#WebhookRequest type webhookRequest struct { FulfillmentInfo fulfillmentInfo `json:"fulfillmentInfo"` SessionInfo sessionInfo `json:"sessionInfo"` } // webhookResponse is used to marshal a WebhookResponse JSON object. Note that // not all members need to be defined--just those that you need to process. // As an alternative, you could use the types provided by the Dialogflow protocol buffers: // https://pkg.go.dev/google.golang.org/genproto/googleapis/cloud/dialogflow/cx/v3#WebhookResponse type webhookResponse struct { FulfillmentResponse fulfillmentResponse `json:"fulfillmentResponse"` SessionInfo sessionInfo `json:"sessionInfo"` } // confirm handles webhook calls using the "confirm" tag. func confirm(request webhookRequest) (webhookResponse, error) { // Create a text message that utilizes the "size" and "color" // parameters provided by the end-user. // This text message is used in the response below. t := fmt.Sprintf("You can pick up your order for a %s %s shirt in 5 days.", request.SessionInfo.Parameters["size"], request.SessionInfo.Parameters["color"]) // Create session parameters that are populated in the response. // The "cancel-period" parameter is referenced by the agent. // This example hard codes the value 2, but a real system // might look up this value in a database. p := map[string]interface{}{"cancel-period": "2"} // Build and return the response. response := webhookResponse{ FulfillmentResponse: fulfillmentResponse{ Messages: []responseMessage{ { Text: text{ Text: []string{t}, }, }, }, }, SessionInfo: sessionInfo{ Parameters: p, }, } return response, nil } // handleError handles internal errors. func handleError(w http.ResponseWriter, err error) { w.WriteHeader(http.StatusInternalServerError) fmt.Fprintf(w, "ERROR: %v", err) } // HandleWebhookRequest handles WebhookRequest and sends the WebhookResponse. func HandleWebhookRequest(w http.ResponseWriter, r *http.Request) { var request webhookRequest var response webhookResponse var err error // Read input JSON if err = json.NewDecoder(r.Body).Decode(&request); err != nil { handleError(w, err) return } log.Printf("Request: %+v", request) // Get the tag from the request, and call the corresponding // function that handles that tag. // This example only has one possible tag, // but most agents would have many. switch tag := request.FulfillmentInfo.Tag; tag { case "confirm": response, err = confirm(request) default: err = fmt.Errorf("Unknown tag: %s", tag) } if err != nil { handleError(w, err) return } log.Printf("Response: %+v", response) // Send response if err = json.NewEncoder(w).Encode(&response); err != nil { handleError(w, err) return } }
- 点击部署。
- 等待状态指示器显示函数已成功部署。在等待期间,请检查您刚刚部署的代码。代码注释描述了重要细节。
创建网络钩子
现在,Webhook 已经作为 Cloud Functions 函数存在,接下来您可以将此 Webhook 与您的代理相关联。如需为代理创建 webhook,请执行以下操作:
- 打开 Dialogflow CX 控制台。
- 选择您的 Google Cloud 项目。
- 选择您的代理。
- 选择管理标签页。
- 点击网络钩子。
- 点击创建。
- 填写以下字段:
- 显示名:shirts-agent-webhook
- 网络钩子网址:提供您在创建函数时保存的网络钩子网址。
- 子类型:标准。
- 所有其他字段均使用默认值。
- 点击保存。
使用网络钩子
现在,Webhook 可供代理使用,您可以在 fulfillment 中使用该 webhook。Order Confirmation 页面具有条目执行方式,该条目执行方式当前具有静态文本响应。如需将 fulfillment 更新为使用 webhook,请执行以下操作:
- 选择 Build 标签页。
- 点击订单确认页面,以展开代理构建器图表上的该页面。
- 点击页面上的 Entry Fulfillment 字段以打开执行方式面板。
- 删除 Agent say 标题下的现有文本响应。当您将鼠标悬停在文本上时,系统会显示删除 delete 按钮。
- 点击启用 webhook。
- 从 Webhook 下拉菜单中选择
shirts-agent-webhook
选项。 - 在代码字段中输入
confirm
。 - 点击保存。
- 关闭履单面板。
已部署的网络钩子代码会发送一个响应,该响应会创建一个名为 cancel-period
的参数。更新代理以在同一订单确认页面的最终代理响应中引用此参数:
- 点击显示
true
条件的条件路由以打开路由面板。 - 向下滚动到路由面板的 Fulfillment 部分,然后在 Agent say 标题下添加以下文本响应:
You can cancel your order within $session.params.cancel-period days. Goodbye.
- 点击保存。
- 关闭路线面板。
在模拟器中测试代理
您现在可以使用模拟器测试代理和 webhook:
- 点击测试代理。
- 输入
I want to buy a large red shirt
,然后按 Enter 键。
由于您同时提供了尺寸和颜色,因此您为代理提供了创建衬衫订单所需的一切,因此它直接过渡到订单确认页面。
下面介绍了代理响应:
响应 | 说明 |
---|---|
好的,我们新建一个订单。 | New Order 页面变为活动状态后,系统会调用条目 fulfillment。响应是从此执行方式触发的。 |
您选择了一件大码的红色衬衫。 | 为 New Order 页面提供所有表单参数后,系统会调用条件路由检查表单是否已完成。响应是从此路线的执行方式触发的。此路由也会转换到 Order Confirmation 页面。 |
你可以在 5 天内自提大号红色衬衫的订单。 | Order Confirmation 页面的条目 fulfillment 调用 webhook。请参阅网络钩子代码中的 confirm 函数。该函数会创建此文本响应,并使用 webhook 请求中提供的参数。 |
您可以在 2 天内取消订单。再见。 | Order Confirmation 页面有一个条件路由,其条件始终为 true。此响应由该路线的执行方式触发。请注意,该响应会使用 webhook 响应中 webhook 设置的参数。 |