状态处理程序

状态处理程序（简称“处理程序”）用于通过为最终用户创建响应和/或转换当前页面来控制对话。对于每轮对话，系统都会评估处理程序，而处理程序可能会影响会话。处理程序包含三种常规类型的数据：

术语 定义
处理程序要求 必须满足这些要求，才能使处理程序对会话产生影响。如果处理程序满足其要求并以某种方式影响会话，才可以说“已调用”处理程序。
处理程序 fulfillment 如果调用处理程序，则使用可选的 fulfillment 为最终用户创建响应。这些响应可以在静态代理数据中定义，也可以从网络钩子服务中动态检索。
处理程序转换目标 如果调用了处理程序，则使用可选的转换目标来更改当前页面。下一页只能是流初始页面或当前活跃流中的页面。

状态处理程序的类型有以下两种，而且处理程序要求也不同：

术语 定义
路线 当最终用户输入匹配某个意图和/或会话状态的某个条件得以满足时，系统将调用路由。具有意图要求的路由也称为意图路由。 仅具有条件要求的路由也称为条件路由。
事件处理程序 事件处理程序在调用事件时调用。在收到意外的最终用户输入或发生网络钩子错误时，系统会触发一些内置事件。您还可以定义在对话之外发生什么情况时调用的自定义事件。

处理状态处理程序共需三个步骤：

术语 定义
1.范围 处理程序必须在范围内才能对会话产生影响。范围取决于处理程序是应用于流、页面还是表单参数，也取决于关联的流是否处于活跃状态、关联的页面是否处于活跃状态，或者代理当前是否正在尝试填充关联的表单参数。
2. 评估版 范围内的每个处理程序都会被按顺序评估。如果处理程序的要求得到满足，则其通过了评估。
3.通话 如果处理程序在范围内，并且通过了评估，则系统将调用它。系统会调用所有关联的 fulfillment，并且任何关联的转换目标都将应用到会话。

范围

要评估处理程序，该处理程序必须在“范围”内。“处理程序范围”是帮助您控制对话的重要且强大的工具。通过控制处理程序的范围，您可以控制：

X 项
何时可以匹配意图
何时应检查条件
何时处理特定事件
何时可以发生页面转换
何时提供静态 fulfillment 响应
何时为动态响应调用启用网络钩子的 fulfillment

范围取决于处理程序是应用于流、页面还是表单参数，也取决于关联的流是否处于活跃状态、关联的页面是否处于活跃状态，或者代理当前是否正在尝试填充关联的表单参数。

详细的范围规则如下：

  • 应用于活跃流的路由：
    • 如果当前页面是流初始页面，则转换路由在范围内。
    • 如果当前页面不是流初始页面，则转换路由仅在满足意图要求时才会在范围内。
  • 应用于当前页面的路由在范围内。
  • 应用活跃流的事件处理程序位于范围内。
  • 应用于当前网页的事件处理脚本在范围内。
  • 应用于代理当前尝试填充的表单参数的事件处理脚本在范围内。

路线

路由有两个要求，而且必须提供其中一个或两个都提供。如果同时提供这两个要求，则必须同时满足这两个要求才能调用路由：

术语 定义
意图要求 意图，必须与当前对话轮次的最终用户输入相匹配。 如果路由具有意图要求，则称为“意图路由”。
条件要求 条件，必须得以满足。如果路由具有条件要求，则称为“条件路由”。

您可以将路由应用于流（流级路由）和页面（页面级路由）。例如，您可能会在以下情况下使用路由：

X 项
当最终用户输入匹配某个意图时，该匹配应触发静态 fulfillment 响应。
当最终用户输入匹配某个意图时，该匹配应针对动态响应触发启用网络钩子的 fulfillment。
当最终用户输入提供了必需的最终表单参数时，条件检查会触发会话转换到其他页面。
当最终用户输入提供特定的表单参数时，条件检查会触发静态 fulfillment 响应。
设置为 true 并强制页面转换的条件检查。

意图传播

正常情况下，当路由由于有匹配的意图而被调用时，该意图将被“使用”。除非新的最终用户输入触发了新的意图匹配，否则无法再次匹配所使用的意图。但是，在以下场景中，可以将意图匹配从一个流传播到另一个流：

  • flow F1 中的路由将 intent I1 作为要求，而将 flow F2 作为转换目标。
  • Flow F2 的路由也将 intent I1 作为要求。

在这种情况下，调用 flow F1 中的路由时，系统会针对单个最终用户输入将 intent I1 匹配两次，并同时调用这两个路由。

传播意图有助于：

X 项
将当前页面更改为其他流中的特定页面（转换目标流的路由具有特定的转换目标页面）。
为流的初始页创建一个条目消息（转换目标流的路由具有 fulfillment）。

路由组

构建代理时，您可能会发现许多页面都有一组通用的路由。要使路由可重复使用，您可以定义“路由组”。这些组是整个流的资源。

例如，您可能想要让您的流来处理最终用户输入，如“I want to add a topping to my pizza”和“I want to change my drup size”。当流的多个页面中的任何一个页面处于活跃状态时，系统应处理这些输入。您可以定义两个具有意图的路由，以便为所有相关页面处理这些输入，但这将是大量重复的工作。您可以改为定义一次路由组，并在所有相关页面上添加对该组的引用。

流级路由

流级路由是应用于流的路由。这些类型的处理程序具有以下用例：

X 项
意图或条件要求在流初始页面范围内的处理程序。
意图要求在流中所有页面范围内的处理程序。

页面级路由

网页级路由是应用于页面的路由。 这些类型的处理程序具有以下用例：

X 项
当特定页面处于活跃状态时，意图或条件要求在范围内的处理程序。

事件处理程序

事件处理程序必须调用一个要求：

术语 定义
事件要求 必须调用的事件。事件通过其名称标识。在收到意外的最终用户输入或发生网络钩子错误时，系统会调用一些内置事件。您还可以定义在对话之外发生事情事情时调用的自定义事件。

您可以将事件处理脚本应用于流（流级事件处理脚本）、页面（页面级事件处理脚本）和参数（参数级事件处理脚本）。例如，您可能会在以下情况下使用事件处理程序：

X 项
当最终用户输入不匹配任何意图时，“无匹配”事件处理程序会提供特定的静态 fulfillment 响应。
计时器在您的系统中过期，您希望向最终用户提供具有特定静态 fulfillment 响应的提醒信息。

流级事件处理程序

流级事件处理程序是应用于流的事件处理程序。这些类型的处理程序具有以下用例：

X 项
事件要求在流初始页面范围内的处理程序。
事件要求在流中所有页面范围内的处理程序。
处理由流中的所有页面共享的意外最终用户输入。
处理网络钩子错误（由流中的所有页面共享）。
处理系统调用的、由流中所有页面共享的自定义事件。

每个流都有针对 no-match 和 no-input 内置事件的事件处理脚本。这些事件处理脚本会在您创建流时自动创建，并且不能删除。

页面级事件处理程序

页面级事件处理脚本是指适用于一个页面的事件处理脚本。这些类型的处理程序具有以下用例：

X 项
特定页面处于活跃状态时，在范围内有事件要求的处理程序。
处理特定于页面的意外最终用户输入。
处理特定于页面的网络钩子错误。
处理系统调用的特定于页面的自定义事件。

参数级事件处理程序

参数级事件处理程序是应用于表单参数的事件处理程序。它们也称为重新提示处理程序。这些事件处理程序不允许有自定义事件，因为它们专门用于在表单填充过程中处理无效的最终用户输入。

这些类型的处理程序具有以下用例：

X 项
当系统要求填入表单参数时，最终用户没有提供有效的输入。

内置事件

以下事件是内置的。有些事件受限于某些级层。

事件名称
 流级 页面级 参数级 调用发生条件
sys.no-match-default ✔ ✔ ✔ 最终用户输入与范围内的处理程序的任何意图都不匹配，也不符合任何表单参数。
sys.no-match-[1-6] ✔ ✔ ✔ 如果您为这些数字排序的事件提供了处理程序，则系统会调用它们（而不是 sys.no-match-default），并且顺序为：sys.no-match-1、sys.no-match-2、...
sys.no-input-default ✔ ✔ ✔ 未收到最终用户输入。
sys.no-input-[1-6] ✔ ✔ ✔ 如果您为这些数字排序的事件提供了处理程序，则系统会调用它们（而不是 sys.no-input-default），并且顺序为：sys.no-input-1、sys.no-input-2、...
sys.invalid-parameter ✔ 在网络钩子使参数无效时调用。
webhook.error ✔ ✔ 网络钩子调用返回了错误。
webhook.error.timeout ✔ ✔ 网络钩子调用超时。

自定义事件

您可以创建自定义事件和事件处理脚本。事件仅按名称标识。您应该避免使用以 sys. 或 webhook. 开头的事件名称，以避免与内置事件冲突。

要使用 API 调用事件，请参阅中 detectIntent 方法的 queryInput.event 字段

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

协议 V3beta1
REST 会话资源
RPC 会话界面

评估顺序

系统会按特定顺序评估处理程序。以下通用规则适用：

  1. 仅评估范围内的处理程序。
  2. 只能调用满足要求的处理程序。
  3. 如果调用了没有转换目标的处理程序，则系统会继续评估处理程序列表。由于存在此规则，多个 fulfillment 可以向响应队列添加多个消息。
  4. 如果调用了具有转换目标的处理程序，则对处理程序列表的评估即会结束。
  5. 如果调用了具有 fulfillment 的处理程序，且 fulfillment 导致网络钩子错误：
    • 如果事件处理程序在事件范围内，则处理程序将处理事件，而处理程序列表评估将结束。
    • 如果事件范围内没有事件处理程序，则网络钩子将会失败且无任何提示。
  6. 当满足意图或条件要求时，不会使用意图或条件，因此可以调用具有相同意图或条件的多个路由。
  7. 当满足事件要求后，系统将使用事件，以便调用为事件找到的第一个事件处理程序。

评估包括三个阶段：

  1. 具有意图要求的路由按以下顺序进行评估：
    1. 页面级：按照提供的顺序应用到当前页面的各个路由。
    2. 页面级组：按照提供的顺序应用到当前页面的路由组。
    3. 流级：按照提供的顺序应用到活跃流的路由。
  2. 仅具有条件要求的路由会按以下顺序进行评估：
    1. 页面级：按照提供的顺序应用到当前页面的各个路由。
  3. 事件处理程序按以下顺序进行评估：
    1. 参数级：应用于当前页面的表单参数的事件处理程序，代理会尝试按提供的顺序填充这些表单参数（重新提示处理程序）。
    2. 页面级：按提供的顺序应用于当前页面的事件处理程序。
    3. 流级：按提供的顺序应用于活跃流的事件处理程序。

符号转换目标

在为处理程序输入目标时，您可以输入特定流或页面，也可以输入符号转换目标：

符号转换目标
 说明
START_PAGE 目标为同名活跃流的初始页面的转换。
END_FLOW 结束当前活跃的流并转换回到导致当前流的转换的页面。
END_SESSION 清除当前会话并转换到名为 END_SESSION 的特殊页面。下一个用户输入将在默认初始流的初始页面上重启会话。
PREVIOUS_PAGE 转换到上一页面。
CURRENT_PAGE 重新转换到当前页面。如果您希望代理重复执行某些操作，这将非常有用。
上一页
页面
下一页
意图