参数

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

参数的使用方式有四种：

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

参数命名

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

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

参数值类型

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

参数空字符串和 null 值

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

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

参数原始值

当文本在运行时与特定实体匹配时，系统通常会将其解析为更便于处理的值。例如，对于水果实体，系统会将最终用户输入中的“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 CX) 设置。

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

获取意图参数

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

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

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

表单参数

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

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

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

定义和管理表单参数

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

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

如需删除表单参数，请点击页面上的参数部分标题，将鼠标悬停在相应参数上，然后点击“删除”图标 delete。

引用表单参数

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

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

$page.params.status = "FINAL"

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

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

设置表单参数

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

默认参数值

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

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

表单填充

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

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

意图和会话参数传播

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

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

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

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

Fulfillment 参数预设

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

网络钩子参数设置

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

获取表单参数

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

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

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

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

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

如果最终用户因意外输入做出响应，则系统会调用 sys.no-match-* 或 sys.no-input-* 事件，并调用为这些事件定义的任何重新提示处理程序。

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

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

会话参数

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

引用会话参数

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

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

这些参考文档还可用于：

• 用于身份验证的 Webhook 标头值。
• 灵活的 webhook 请求，用于向 webhook 发送参数值。

如需引用会话参数，请使用以下格式：

$session.params.parameter-id

设置会话参数

完成表单填充后，对话式代理 (Dialogflow CX) 会将填充的参数写入会话。

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

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

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

获取会话参数

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

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

参数传播

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

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

用于电话集成的 DTMF

您可以为参数启用和配置 DTMF（双音多频信令）。启用后，使用电话集成的代理的最终用户可以使用电话拨号键盘提供参数值。

为减少歧义，DTMF 输入可以使用常规和 DTMF 特定（推荐）形式解释：

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

在为参数匹配实体类型时，Conversational Agents (Dialogflow CX) 会尝试匹配特定于常规格式和 DTMF 的形式。当实体类型用于 DTMF 输入时，建议您定义 dtmf_digits_123 等同义词以改进 NLU 匹配。

如果 DTMF 输入不满足终止条件（DTMF 输入尚未达到最大数字长度或尚未被结束数字终止），则对话式代理 (Dialogflow CX) 代理将继续等待更多输入。在此期间，如果触发无语音超时，则代理将改为调用无输入事件。 如果仅检测到语音内容，则代理会与语音输入进行匹配。如果同时检测到语音和 DTMF 输入，则会丢弃语音输入，并仅考虑 DTMF 输入。

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

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

智能端点

如果为代理启用了智能端点设置，您可以为数字参数自定义智能端点设置行为。

1. 设置最小数字数，以提示智能端点指示器等待收集所有数字。
2. 设置修正转写内容，以修正常见的数字转写错误，从而改进数字语音识别功能。只有指定 en 或 en-* 语言代码的请求才支持此功能。
3. 设置等待超时，以指定对话式 AI 助理 (Dialogflow CX) 等待用户提供更多输入的额外时间。

流级范围的参数

流级范围的参数可以定义为 fulfillment 参数预设或表单参数。这些参数只能在其所定义的流程处于活跃状态时引用，并且不会保留到会话参数中。

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

$flow.parameter-name

例如，如果参数名称为 date，您可以将该参数定义或引用为 $flow.date。

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

流级范围参数定义示例：

流程级范围的参数值生命周期

这种情况并不常见，但在某些高级情况下，您可能需要了解当流程变为非活动状态，然后又变为活动状态时，流程级范围的参数值会如何保留（或舍弃）。

当流程变为非活动状态，然后再次变为活动状态时，流程级范围的参数值是否会保留取决于流程堆栈以及堆栈上的流程实例。

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

示例：

请求级范围的参数

请求级范围的参数是由对话式代理 (Dialogflow CX) 创建的短时有效参数，只能在当前请求的生命周期内引用，并且不会保留在会话参数中。

请求级范围的参数由 Conversational Agents (Dialogflow CX) 为以下功能生成。

内置参数

您可以使用以下方法访问与请求关联的各种数据：

自定义负载

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

情感分析

启用情感分析后，您可以使用以下情感参考：

参数隐去

对于任何 intent 或表单参数，您可以启用参数隐去，以隐去日志和对话式 AI 客服 (Dialogflow CX) 内部存储空间中的最终用户运行时参数数据。隐去的参数在日志中显示为 $parameter-name_redacted。

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

如需启用参数遮盖，请执行以下操作：

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