参数

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

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

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

参数的使用方式有四种:

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

参数命名

以下规则适用于参数命名:

  • 使用以下字符:[A-Z][a-z][0-9].-_
  • 参数名称不区分大小写,因此 Dialogflow 将 Appleapple 视为同一参数。网络钩子和 API 客户端代码还应将参数名称视为不区分大小写,因为对于 Dialogflow 返回的参数名称,无法保证大小写。

参数值类型

参数值支持多种值类型。下文的“会话”部分介绍了如何引用每种参数值类型。系统支持以下类型:

类型 说明
标量 单个数字或字符串值。
Composite 通过匹配复合实体或填充包含 originalresolved 字段的 intent 参数来填充的 JSON 对象。
列表 为配置为列表的参数填充的标量或复合值列表。请参阅下面的是列表选项。

参数为空字符串和 null 值

您可以将字符串参数值设置为 "",这会将参数设置为空字符串。

您可以将任何参数值设置为 null,这表示未设置该参数。

参数原始值

当文本在运行时与特定实体匹配时,通常会将其解析为更便于处理的值。例如,对于 fruit 实体,最终用户输入中的单词“apples”可能会被解析为“apple”。

intent 参数引用的所有值类型都可以引用原始值或解析值。

只有会话参数引用的复合值类型才能引用原始值。

意图参数

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

  • 名称(也称为 ID显示名):用于标识参数的名称。
  • 实体类型:与参数关联的实体类型
  • 为列表:如果为 true,则该参数会被视为值列表。
  • 在日志中隐去 (Redact in log):如果设置为 true,最终用户提供的参数数据会隐去

定义意图参数

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

引用意图参数

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

您可以引用原始值或解析值。

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

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

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

设置意图参数

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

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

获取意图参数

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

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

选择会话引用的协议和版本

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

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

表单参数

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

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

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

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

控制台选项名称 API 字段链 说明
显示名 Page.form.parameters[].displayName 用于标识参数的名称。
实体类型 Page.form.parameters[].entityType 与参数关联的实体类型
必需 Page.form.parameters[].required 指示该参数是否是必需的。在完成表单填充之前,必须填充必需参数,代理将提示最终用户输入值。如需了解详情,请参阅下面的设置表单参数部分。
默认值(仅在未勾选必需时才会显示) Page.form.parameters[].defaultValue 可选参数的默认值。如需了解详情,请参阅下面的设置表单参数部分。
为列表 Page.form.parameters[].isList 如果为 true,则该参数会被视为值列表。
在日志中隐去 Page.form.parameters[].redact 如果为 true,则最终用户提供的参数数据会隐去
初始提示 fulfillment Page.form.parameters[].fillBehavior.initialPromptFulfillment fulfillment 的形式初始提示,向最终用户请求所需的参数值。如需了解详情,请参阅下面的设置表单参数部分。
重新提示事件处理程序 Page.form.parameters[].fillBehavior.repromptEventHandlers 当代理在尝试失败后需要重新提示最终用户填充参数时,将使用这些处理程序。请参阅表单填充重新提示处理程序。 如果未定义重新提示事件处理程序,则代理会在尝试失败后使用初始提示重新提示。
DTMF 不可用 请参阅下面的 DTMF 部分。

定义和管理表单参数

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

如需使用控制台更改表单参数的顺序,请点击页面上的参数部分标题,然后在参数表中拖动参数行。

如需删除表单参数,请点击页面上的参数部分标题,将鼠标悬停在某个参数上,然后点击删除按钮

引用表单参数

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

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

$page.params.status = "FINAL"

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

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

设置表单参数

可以通过多种方式设置表单参数值。以下各小节介绍了设置表单参数值的每种机制。

默认参数值

您可以为可选表单参数提供默认值。 表单填写开始时,所有未设置的可选表单参数都设置为其默认值。这些值可以通过以下某些机制进行初始化或替换。

如果某参数为必需参数,则系统会忽略其默认值。

表单填充

Dialogflow 会自动设置最终用户在表单填充期间提供的参数值。 代理 (Agent) 会按照页面中定义的顺序收集必需参数。代理会利用您为每个必需参数提供的初始提示 fulfillment 来提示最终用户输入必需值。可选参数不会触发提示。

如果最终用户在代理提示后未提供必需的参数值,则系统将重复初始提示,除非重新提示处理程序中定义了其他行为。如果定义了多个初始文本提示,则代理行为会与任何 fulfillment 文本响应的行为相同。

意图和会话参数传播

当在运行时设置任何类型的参数时,该参数会被写入会话并成为会话参数

当页面最初处于活跃状态时,以及在其活跃期间,任何与会话参数同名的表单参数都会自动设置为会话参数值。

如果意图路由参数传播中具有匹配的意图参数时,可能会发生这种情况。

意图和会话参数传播是将可选表单参数设置为最终用户输入的值的唯一机制,但此机制还可以设置或替换必需的表单参数值。

Fulfillment 参数预设

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

网络钩子参数设置

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

获取表单参数

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

选择会话引用的协议和版本

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

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

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

重新提示处理程序(也称为参数级事件处理程序)用于为必需的参数定义复杂的参数提示行为。例如,如果最终用户在初始提示后无法提供值,以及在 N 次失败尝试后无法转换到其他页面,则可以使用重新提示处理程序来更改提示。

如果未定义重新提示处理程序,则将使用初始提示来根据需要重新提示最终用户。

如果最终用户因意外输入做出响应,则系统会调用 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.original
  • 如需访问复合实体类型的参数的完整对象,请使用 IDENTITY 系统函数

列表

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

    $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++ SessionsClient 不可用
C# SessionsClient 不可用
Go SessionsClient 不可用
Java SessionsClient SessionsClient
Node.js SessionsClient SessionsClient
PHP 不可用 不可用
Python SessionsClient SessionsClient
Ruby 不可用 不可用

获取会话参数

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

选择会话引用的协议和版本

协议 V3 V3beta1
REST 会话资源 会话资源
RPC 会话接口 会话接口
C++ SessionsClient 不可用
C# SessionsClient 不可用
Go SessionsClient 不可用
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 输入不满足终止条件(DTMF 输入尚未达到最大数字长度或尚未被结束数字终止),则 Dialogflow 代理将继续等待更多输入。在此期间,如果触发无语音超时,则代理将改为调用无输入事件。 如果仅检测到语音内容,则代理会与语音输入进行匹配。如果同时检测到语音和 DTMF 输入,则会丢弃语音输入,并仅考虑 DTMF 输入。

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

控制台

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

构建代理时,您可以在模拟器中测试 DTMF 输入。

流范围的参数

流范围的参数可以定义为 fulfillment 参数预设表单参数这些参数只能在用于定义它们的流处于活跃状态时引用,并且不会持久保留到会话参数中。

如需定义或引用流级范围的参数,请使用以下语法:

$flow.parameter-name

例如,如果参数名称为 date,您可以采用 $flow.date 的形式定义或引用该参数。

请注意,在定义参数时使用 $ 前缀与不使用 $ 进行参数定义的其他参数类型不同。

流范围的参数定义示例如下: 流限定的参数屏幕截图。

流范围的参数值生命周期

这种情况并不常见,但在某些高级情况下,您可能需要了解当数据流变为非活动状态并再次处于活跃状态时,如何保留(或舍弃)流范围的参数值。

当流变为非活跃状态时,是否保留流范围的参数值并再次处于活跃状态,取决于流堆栈和堆栈上的流实例

  • 当流 A 使用特定转换目标转换为流 B 时,流 A(父流)会保留在堆栈上,流 A 保留其流范围内的参数值,并且流 B 的新实例(子流)会添加到堆栈。
  • 当子流使用符号转换目标(例如 END_FLOW)转换回父流时,该子流会从堆栈中移除,所有子流作用域参数值都会被舍弃,并保留所有父流作用域参数值。
  • 通过具有特定过渡目标的一系列过渡,流堆栈可以包含同一流类型的多个实例。流类型的每个实例都有唯一的流级范围参数值。例如:A1 -> B1 -> C1 -> B2,其中 A、B 和 C 是流类型,数字表示这些流类型的实例。在此示例中,B1 和 B2 是流 B 的不同实例,并且具有唯一的流级范围参数。

示例:

转换 结果
流 A (A1) 变为活跃状态。
流程 B (B1) 根据特定的过渡目标变为活动状态。
流程 B 使用符号转换目标转换回启动该流程的数据流 A (A1)。
流 A 保留参数值。
流 A (A1) 变为活跃状态。
流程 B (B1) 根据特定的过渡目标变为活动状态。
流程 B 使用特定过渡目标过渡到流程 A (A2) 的新实例。
堆栈顶部的流 A (A2) 的新实例无法访问堆栈底部的流 A (A1) 的参数值。
流 A (A1) 变为活跃状态。
流程 B (B1) 根据特定的过渡目标变为活动状态。
流程 A (A1) 使用符号转换目标变为活跃状态。
流程 B (B2) 根据特定的过渡目标变为活动状态。
流程 B (B2) 不会保留其在第二次转换 (B1) 后处于活动状态时设置的参数值。

请求级范围的参数

请求范围的参数是由 Dialogflow 创建的短期参数,只能在当前请求的生命周期内引用,不会保留在会话参数中。

Dialogflow 会为以下特征生成请求级范围的参数。

语言和用户输入

您可以通过以下方式访问与该请求关联的语言代码和用户输入:

参考文档 说明
$request.language QueryInput.language_code 中指定的语言代码。
$request.resolved-language 代理在处理过程中使用的实际语言代码。已解析的语言可以与请求中指定的语言不同。例如,如果代理仅支持“en”,而请求中指定的语言为“en-US”,则解析后的语言将为“en”。
$request.user-utterance 请求中指定的当前用户话语。

自定义负载

设置 QueryParameters.payload 后,您可以通过 $request.payload.param-id 访问相应的参数。

情感分析

启用情感分析后,您可以使用以下情感参考:

参考文档 类型 说明
$request.sentiment.score 数字 情感得分介于 -1.0(消极情绪)和 1.0(积极情绪)之间。
$request.sentiment.magnitude 数字 表示情绪的整体强度(包括积极和消极),介于 0.0 到 +inf 之间。与得分不同,magnitude 没有归一化;最终用户输入中的每一次情绪表达(积极和消极)都会影响输入的量。较长的输入量可能较大。
$request.sentiment.succeeded 布尔值 如果情感分析成功,则为 true,否则为 false。

参数隐去

对于任何意图或形式参数,您可以启用参数隐去,以隐去日志和 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 intent 接口 intent 接口
C++ IntentsClient 不可用
C# IntentsClient 不可用
Go IntentsClient 不可用
Java IntentsClient IntentsClient
Node.js IntentsClient IntentsClient
PHP 不可用 不可用
Python IntentsClient IntentsClient
Ruby 不可用 不可用

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

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

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

作为替代方案,您可以隐去特定实体类型的所有参数