定义、引用、设置和获取参数
参数的使用方式有四种：
- 在设计时定义：在设计时，您可以使用控制台或 API 来定义参数。例如，您可以定义一个意图参数，并在训练短语中使用该参数来指示应提取的最终用户输入。
- 在设计时引用：参数引用是用于保存要在运行时提取参数值的变量。在设计过程中，您可以使用控制台或 API 来引用各种数据类型中的参数。例如，您可以在静态 fulfillment 响应中为路由引用会话参数。
- 在运行时设置： 在运行时，对话代理 (Dialogflow CX) 服务（调用该 API 的服务） 网络钩子服务都可以设置参数值。 例如，对话代理 (Dialogflow CX) 服务会设置 intent 参数的值 当最终用户输入与意图匹配，并且输入包含参数时 数据。
- 在运行时获取：在运行时，您的参数引用包含已设置的参数值，您可以使用 API 或网络钩子来获取参数值。例如，当某个意图匹配并调用网络钩子时，网络钩子服务会收到该意图的参数值。
参数命名
以下规则适用于参数命名：
- 使用以下字符：
[A-Z]、[a-z]、[0-9]、.、-、_ - 参数名称不区分大小写，因此对话式 AI 助理 (Dialogflow CX) 将
Apple和apple视为同一参数。网络钩子和 API 客户端代码 参数名称也应不区分大小写 因为对对话代理 (Dialogflow CX) 返回的参数名称没有大小写保证。 - 如果您在不同位置创建具有相同 ID 或显示名称的参数 intent 或表单，请确保实体类型和其他设置是 所有定义都一样如果实体类型或其他参数设置不同，请为每个定义使用唯一的参数 ID 或显示名称。
参数值类型
参数值支持多种值类型。 下文的“会话”部分介绍了 如何引用每种参数值类型。 系统支持以下类型：
| 类型 | 说明 |
|---|---|
| 标量 | 一个数值或字符串值。 |
| Composite | 通过匹配复合实体或填充 intent 参数（其中包含 original 和 resolved 字段）来填充的 JSON 对象。 |
| 列出 | 为配置为列表的参数填充的标量值或复合值列表。请参阅下方的是否为列表选项。 |
参数为空字符串和 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。
设置意图参数
当最终用户输入在运行时与 intent 匹配时， 任何参数 注解 由 Conversational Agents (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 部分。 |
定义和管理表单参数
在创建页面时，系统会在设计时定义表单参数。
如需使用控制台更改表单参数顺序，请执行以下操作： 点击该页面上的参数部分标题， 然后拖动参数表中的参数行。
如需删除表单参数，请执行以下操作： 点击该页面上的参数部分标题， 将鼠标悬停在某个参数上 然后点击“删除delete”按钮。
引用表单参数
表单参数引用不是直接使用的。您只能检查单个表单参数的填充状态或整个表单的填充状态。您可以在条件路由的条件要求中使用这些表单状态引用。
如需检查当前页面的整个表单是否已填充，请使用以下条件：
$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
这些参考文档还可用于：
- 网络钩子标头值 进行身份验证。
- 灵活的 Webhook 请求， 用于将参数值发送到 webhook。
如需引用会话参数，请使用以下格式：
标量
访问标量实体类型的参数：
$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 请求字段。
选择会话引用的协议和版本：
| 协议 | 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 CX) 会尝试匹配特定于常规格式和 DTMF 的形式。当实体类型用于 DTMF 输入时，建议您定义 dtmf_digits_123 等同义词以改进 NLU 匹配。
如果 DTMF 输入不满足终止条件（ 未达到最大数位长度，或未在完成时终止 对话代理 (Dialogflow CX) 代理将继续等待更多输入。在此期间，如果触发无语音超时，则代理将改为调用无输入事件。 如果仅检测到语音内容，则代理会与语音输入进行匹配。如果同时检测到语音和 DTMF 输入，则会丢弃语音输入，并仅考虑 DTMF 输入。
如需为参数启用和自定义 DTMF，请执行以下操作：
控制台
- 在代理语音和 IVR 设置中启用高级设置（如果尚未启用）。
- 创建一个页面参数。
- 在参数窗格中，将启用 DTMF (Enable DTMF) 切换为开启。
- 将最大位数 (Max digits) 设置为最终用户可以为此参数提供的最大位数。
- 将结束数字 (Finish digit) 设置为将终止参数的 DTMF 输入的拨号键盘值。此设置通常使用
#。结束数字不会添加到代理的对话式客服 (Dialogflow CX) 查询中，因此如果结束数字为 # 且输入为 123#，则实际查询输入将为“123”
构建代理时，您可以在模拟器中测试 DTMF 输入。
智能端点
如果为代理启用了智能端点设置，您可以为数字参数自定义智能端点设置行为。
- 设置最小位数，以提示智能端点等待，直到 收集的数字。
- 设置修正转写内容，通过修正常见的数字转写错误来改进数字语音识别功能。只有指定 en 或 en-* 语言代码的请求才支持此功能。
- 设置等待超时以指定对话代理 (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 的不同实例，并且具有唯一的流程级范围参数。
示例：
| 转换 | 结果 |
|---|---|
| 流 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) 使用特定转换目标变为活跃状态。 |
在第二次转换 (B1) 后，流程 B (B2) 不会保留在其处于活动状态时设置的参数值。 |
请求范围内的参数
请求范围内的参数是由对话代理 (Dialogflow CX) 创建的短期参数，只能在当前请求的生命周期内引用，不会持久保留在会话参数中。
请求范围内的参数由对话代理 (Dialogflow CX) 针对以下功能生成。
内置参数
您可以使用以下方法访问与请求关联的各种数据：
| 参考 | 说明 |
|---|---|
| $request.agent-id | 代理的标识符。 |
| $request.session-id | 会话的标识符。 |
| $request.language | QueryInput.language_code 中指定的语言代码。 |
| $request.resolved-language | 代理在处理期间使用的实际语言代码。解析出的语言可能与请求中指定的语言不同。例如，如果客服人员仅支持“英语”，而请求中指定的语言是“英语（美国）”，则解析出的语言将是“英语”。 |
| $request.user-utterance | 请求中指定的当前用户语音指令。 |
| $request.last-agent-utterance | 代理最近发送的语音内容。 |
自定义负载
设置 QueryParameters.payload 后，您可以通过 $request.payload.param-id 访问相应的参数。
情感分析
启用情感分析后，您可以使用以下情感参考：
| 参考 | 类型 | 说明 |
|---|---|---|
| $request.sentiment.score | 数字 | 情感得分介于 -1.0（负面情绪）与 1.0（正面情绪）之间。 |
| $request.sentiment.magnitude | 数字 | 表示情绪（包括积极和消极）的整体强度，介于 0.0 和 +inf 之间。与得分不同，量级没有归一化；最终用户输入中的每种情绪表达（积极和消极）都会影响输入的量级。较长的输入可能具有更大的量级。 |
| $request.sentiment.succeeded | 布尔值 | 如果情感分析成功，则为 true，否则为 false。 |
参数隐去
对于任何 intent 或表单参数，
您可以启用参数隐去功能
这会隐去日志中的最终用户运行时参数数据
和对话代理 (Dialogflow CX) 内部存储空间。
隐去的参数在日志中显示为 $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 | intent 资源 | intent 资源 |
| 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 | 不可用 | 不可用 |
作为替代方案，您可以隐去特定实体类型的所有参数。