参数

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

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

参数的使用方式有四种：

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

参数命名

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

  • 使用以下字符：[A-Z]、[a-z]、[0-9]、.、-、_
  • 参数名称不区分大小写，因此 Dialogflow CX 将 Apple 和 apple 视为同一参数。网络钩子和 API 客户端代码还应将参数名称视为不区分大小写，因为对于 Dialogflow CX 返回的参数名称，无法保证大小写。
  • 如果您在不同的 intent 或表单中创建具有相同 ID 或显示名称的参数，请确保所有定义具有相同的实体类型和其他设置。如果实体类型或其他参数设置不同，请为每个定义使用唯一的参数 ID 或显示名。

参数值类型

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

类型 说明
标量 单个数值或字符串值。
复合 通过匹配复合实体或填充意图参数而填充的 JSON 对象，其中包含 original 和 resolved 字段。
列表 为配置为列表的参数填充的标量值或复合值列表。请参阅以下 Is List 选项。

参数空字符串值和 null 值

您可以将字符串形参值设置为 ""，这样会将形参设置为空字符串。

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

参数原始值

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

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

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

意图参数

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

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

定义意图参数

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

引用意图参数

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

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

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

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

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

设置意图参数

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

意图路由的 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 页面收集最终用户的姓名和电话号码。

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

控制台选项名称 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 CX 会自动设置最终用户在表单填充期间提供的参数值。代理 (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 CX 会将填充的参数写入会话。

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

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

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