参数

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

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

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

参数的使用方式有四种:

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

意图参数

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

  • 名称(也称为 ID显示名):用于标识参数的名称。
  • 实体类型:与参数关联的实体类型
  • 为列表:如果为 true,则该参数会被视为值列表。
  • 在日志中隐去 (Redact in log):如果设置为 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 的互动将返回意图参数值。请参阅 Session 类型的 detectIntent 方法的 queryResult.parameters 响应字段。

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

协议 V3 V3beta1
REST 会话资源 会话资源
RPC 会话界面 会话界面
C# 不可用 不可用
Go 不可用 不可用
Java SessionsClient SessionsClient
Node.js SessionsClient SessionsClient
PHP 不可用 不可用
Python SessionsClient SessionsClient
Ruby 不可用 不可用

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

表单参数

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

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

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

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

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

定义表单参数

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

引用表单参数

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

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

$page.params.status = "FINAL"

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

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

设置表单参数

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

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

获取表单参数

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

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

协议 V3 V3beta1
REST 会话资源 会话资源
RPC 会话界面 会话界面
C# 不可用 不可用
Go 不可用 不可用
Java SessionsClient SessionsClient
Node.js SessionsClient SessionsClient
PHP 不可用 不可用
Python SessionsClient SessionsClient
Ruby 不可用 不可用

网络钩子接收表单参数值。请参阅网络钩子请求中的 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

列表

  • 如需访问完整的元素列表,请执行以下操作:

    $session.params.parameter-id

    例如,如果列表参数 ID 为 colors 并且从用户查询中提取的值为 ["red", "blue", "yellow"],则您可以采用 $session.params.colors 形式引用所有值。

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

    $session.params.parameter-id[i]

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

设置会话参数

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

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

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

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

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

协议 V3 V3beta1
REST 会话资源 会话资源
RPC 会话界面 会话界面
C# 不可用 不可用
Go 不可用 不可用
Java SessionsClient SessionsClient
Node.js SessionsClient SessionsClient
PHP 不可用 不可用
Python SessionsClient SessionsClient
Ruby 不可用 不可用

获取会话参数

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

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

协议 V3 V3beta1
REST 会话资源 会话资源
RPC 会话界面 会话界面
C# 不可用 不可用
Go 不可用 不可用
Java SessionsClient SessionsClient
Node.js SessionsClient SessionsClient
PHP 不可用 不可用
Python SessionsClient SessionsClient
Ruby 不可用 不可用

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

参数传播

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

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

用于电话合作伙伴集成的 DTMF

您可以为参数启用和配置 DTMF(双音多频信令)。启用后,使用电话合作伙伴集成的代理的最终用户可以使用电话拨号键盘提供参数值。

为减少歧义,DTMF 输入可以使用常规和 DTMF 特定(推荐)形式解释:

  • 常规形式就是最终用户输入的拨号键盘值。例如 123#
  • DTMF 特定形式将输入转换为 dtmf_digits_[digits],其中 [digits] 是原始 DTMF 数字(* 替换为 star# 替换为 pound)。例如,123# 会被解释为 dtmf_digits_123pound

当匹配参数的实体类型时,Dialogflow 会尝试匹配常规和 DTMF 特定形式。将实体类型用于 DTMF 输入时,建议定义 dtmf_digits_123 等同义词,以改进 NLU 匹配。

如果 DTMF 输入不符合终止条件(未达到最大数字长度或者没有以结束数字终止),则 Dialogflow 代理会继续等待更多输入。在此期间,如果触发无语音超时,代理将改为调用无输入事件。如果检测到语音话语,代理将改为匹配语音转录。在这两种情况下,系统都会舍弃现有的 DTMF 输入。

如需为参数启用和自定义 DTMF,请执行以下操作:

控制台

  1. 启用代理语音和 IVR 设置中的高级设置(如果您尚未启用)。
  2. 创建 page 参数。
  3. 在参数窗格中,开启启用 DTMF
  4. 最大位数 (Max digits) 设置为最终用户可以为此参数提供的最大位数。
  5. 结束数字 (Finish digit) 设置为将终止参数的 DTMF 输入的拨号键盘值。此设置通常使用 #。结束数字不会添加到代理的 Dialogflow 查询中,因此如果结束数字为 # 且输入为 123#,则实际查询输入将为“123”。

参数隐去

对于任何意图或形式参数,您可以启用参数隐去,以隐去日志和 Dialogflow 内部存储空间中的最终用户运行时参数数据。隐去的参数在日志中显示为 $parameter-name_redacted

例如,假设最终用户输入“My address is 1600 Amphitheatre Parkway”,则 address 参数会设置为“1600 Amphitheatre Parkway”。日志记录的文字将为“My address is $address_redacted”。

如需启用参数遮盖,请执行以下操作:

控制台

创建或更新参数时,请选中在日志中隐去 (Redact in log) 复选框。

API

对于 Intent 类型,将 parameters[].redact 字段设置为 true。

为意图参考选择协议和版本

协议 V3 V3beta1
REST 意图资源 意图资源
RPC 意图界面 意图界面
C# 不可用 不可用
Go 不可用 不可用
Java IntentsClient IntentsClient
Node.js IntentsClient IntentsClient
PHP 不可用 不可用
Python IntentsClient IntentsClient
Ruby 不可用 不可用

对于 Page 类型,将 form.parameters[].redact 字段设置为 true。

为页面参考选择协议和版本

协议 V3 V3beta1
REST 页面资源 页面资源
RPC 页面界面 页面界面
C# 不可用 不可用
Go 不可用 不可用
Java PagesClient PagesClient
Node.js PagesClient PagesClient
PHP 不可用 不可用
Python PagesClient PagesClient
Ruby 不可用 不可用