参数

“参数”用于捕获和引用最终用户在会话期间提供的值。每个参数都有一个名称和一个实体类型。与原始的最终用户输入不同,参数是结构化数据,可以轻松用于执行某些逻辑或生成响应。

CX 参数与 ES 参数类似,但实用性和范围已扩展,并且引用参数的语法已更改。

定义、引用、设置和获取参数

参数的使用方式有四种:

  • 在设计时定义:在设计时,您可以使用控制台或 API 来定义参数。例如,您可以定义一个意图参数,并在训练短语中使用该参数来指示应提取的最终用户输入。
  • 在设计时引用:参数引用是用于保存要在运行时提取参数值的变量。在设计过程中,您可以使用控制台或 API 来引用各种数据类型中的参数。例如,您可以在静态 fulfillment 响应中为路由引用会话参数。
  • 在运行时设置:在运行时,Dialogflow 服务、调用 API 的服务以及网络钩子服务都可以设置参数值。例如,当最终用户输入与意图匹配且输入包含参数数据时,Dialogflow 服务会设置意图参数的值。
  • 在运行时获取:在运行时,您的参数引用包含已设置的参数值,您可以使用 API 或网络钩子来获取参数值。例如,当某个意图匹配并调用网络钩子时,网络钩子服务会收到该意图的参数值。

意图参数

意图使用参数来提取在意图匹配时最终用户提供的数据。以下数据用于定义意图参数:

  • 名称(也称为 ID显示名):用于标识参数的名称。
  • 实体类型:与参数关联的实体类型
  • 为列表:如果为 true,则该参数会被视为值列表。

定义意图参数

在创建意图数据为训练短语添加注释时,系统会在设计时定义意图参数。

引用意图参数

意图参数引用可用于意图路由的静态 fulfillment 响应消息。

当文本在运行时与特定实体匹配时,系统通常会将其转换为更便于处理的值。例如,最终用户输入中的单词“apples”可以被提取为水果实体的“apple”。您可以引用最终用户书面或口头表达的 original 值,也可以引用实体提取的 resolved 值。

如需引用当前匹配的意图的参数,请使用以下格式之一:

$intent.params.parameter-id.original
$intent.params.parameter-id.resolved

例如,如果参数 ID 为 date,则可以引用解析后的值 $intent.params.date.resolved

您还可以访问参数的实体类型名称:

$intent.params.parameter-id.type

设置意图参数

当最终用户输入在运行时匹配意图时,任何用于关联训练短语的注释所使用的任何参数都将由 Dialogflow 设置。

意图路由的 fulfillment 可以使用 fulfillment 参数预设在运行时设置意图参数值。

获取意图参数

在匹配意图的每轮对话中,您的代码可以访问意图参数值。

与 API 的互动将返回意图参数值。请参阅中的 detectIntent 方法的 queryResult.parameters 响应字段

为会话参考选择协议和版本

协议 V3beta1
REST 会话资源
RPC 会话界面

网络钩子接收意图参数值。请参阅网络钩子请求中的 intentInfo.parameters 字段。

表单参数

您需要为每个页面定义一个表单,该表单上列出应从该页面的最终用户处收集的参数。代理会与最终用户进行多轮对话,直到收集到所有表单参数(也称为“页面参数”)。您还需要针对每个表单参数提供“提示”,供代理用于向最终用户询问该信息。此过程称为“表单填充”。

举例来说,您可以创建一个表单,用于为 Collect Customer Info 页面收集最终用户的姓名和电话号码。

CX 表单填充与 ES 槽位填充类似。

以下数据用于定义表单参数:

  • 名称(也称为 ID显示名):用于标识参数的名称。
  • 实体类型:与参数关联的实体类型
  • 为列表:如果为 true,则该参数会被视为值列表。
  • 必需:指明该参数是否是必需的。可选参数不会触发提示;但是,如果用户指定了这些参数,则系统会填充它们。在完成表单填充之前,必须填充必需的参数。
  • 默认值:可选参数的默认值。如果需要该参数,则系统将忽略默认值。
  • 初始提示 Fulfillment:您使用一个 fulfillment 配置此参数,在代理需要最初提示最终用户填充该参数时会用到此 fulfillment。
  • 重新提示处理程序:当代理在尝试失败后需要重新提示终端用户提供参数时,将使用这些处理程序。请参阅表单填充重新提示处理程序

定义表单参数

在创建页面时,系统会在设计时定义表单参数。

引用表单参数

表单参数引用不是直接使用的。您只能检查单个表单参数的填充状态或整个表单的填充状态。您可以在条件路由条件要求中使用这些表单状态引用。

如需检查当前页面的整个表单是否已填充,请使用以下条件:

$page.params.status = "FINAL"

如需检查上轮对话中是否填充了特定表单参数,请使用以下条件:

$page.params.parameter-id.status = "UPDATED"

设置表单参数

路由、事件处理程序或表单重新提示的 fulfillment 可以使用 fulfillment 参数预设在运行时设置表单参数值。

您的网络钩子可以在运行时设置表单参数的值。请参阅网络钩子响应中的 pageInfo.formInfo.parameterInfo 字段。

获取表单参数

与 API 的互动将返回表单参数值。请参阅中的 detectIntent 方法的 queryResult.parameters 响应字段

为会话参考选择协议和版本

协议 V3beta1
REST 会话资源
RPC 会话界面

网络钩子接收表单参数值。请参阅网络钩子请求中的 pageInfo.formInfo.parameterInfo 字段。

表单填充重新提示处理程序

在表单填充期间,代理会要求最终用户提供参数值。如果最终用户使用意外的输入进行响应,则系统会调用 sys.no-match-*sys.no-input-* 事件。您可以定义重新提示处理程序(也称为参数级事件处理程序),以重新提示最终用户提供参数值。

与其他事件处理程序一样,重新提示处理程序也是一种状态处理程序,可通过以下一种或两种方式进行配置:

  • 用于提供最终用户重新提示消息和/或参数预设的 fulfillment。
  • 用于更改当前页面的转换目标。

会话参数

当在运行时设置任何类型的参数时,该参数将被写入会话并成为会话参数。这些参数在设计时未明确定义。您可以在会话期间随时引用这些会话参数。

引用会话参数

会话参数引用可用于以下类型的 fulfillment 的静态响应消息中:

  • 页面条目 fulfillment
  • 路由 fulfillment
  • 事件处理程序 fulfillment
  • 表单提示 fulfillment
  • 表单重新提示 fulfillment

如需引用会话参数,请使用以下格式:

标量

访问标量实体类型的参数:

$session.params.parameter-id

例如,如果参数 ID 为 date,则可以引用值 $session.params.date

复合索引

访问复合实体类型的参数的成员:

$session.params.parameter-id.member-name

例如,如果参数 ID 为 location,则可以引用 zip-code 成员值为 $session.params.location.zip-code

列表视图

访问列表参数的第 i 个元素:

$session.params.parameter-id[i]

例如,如果列表参数 ID 为 colors,则可以将第一个值引用为 $session.params.colors[0]

设置会话参数

完成表单填充后,Dialogflow 会将填充的参数写入会话。

路由、事件处理程序或表单重新提示的 fulfillment 可以使用 fulfillment 参数预设在运行时设置会话参数值。

网络钩子可以在运行时设置会话参数的值。请参阅网络钩子响应中的 sessionInfo.parameters 字段。

与 API 的互动可以设置会话参数值。请参阅中的 detectIntent 方法的 queryParams.parameters 请求字段

为会话参考选择协议和版本

协议 V3beta1
REST 会话资源
RPC 会话界面

获取会话参数

与 API 的互动将返回会话参数值。请参阅中的 detectIntent 方法的 queryResult.parameters 响应字段

为会话参考选择协议和版本

协议 V3beta1
REST 会话资源
RPC 会话界面

网络钩子接收会话参数值。请参阅网络钩子请求中的 sessionInfo.parameters 字段。

参数传播

当最终用户输入提供参数值时,该参数可能会传播到其他级别:

  • 当意向参数由意向匹配设置时,活动页面的相似名称表单参数会被设置为相同的值。参数的实体类型取决于意向参数定义。
  • 如果意向参数由意向匹配设置,或者在填写表单时设置了表单参数,则该参数会变为会话参数。