请求客户机操作

将客户机操作添加到对话节点，以请求客户机端进程将结果返回到对话。

如果助手与使用 API 的定制客户机集成，那么可以使用客户机操作来启动客户机应用程序完成的功能。客户机操作以外部客户机应用程序可理解的标准化格式定义客户机端进程的请求。外部客户机应用程序必须使用提供的信息来运行请求的操作，该操作可以是本地程序化函数，对外部服务的调用或客户机可以执行的任何其他操作。然后，客户机将结果从操作返回到对话框，该对话框可以对其进行进一步处理，将其显示给用户，或者将其用作确定后续流的条件。

与其他操作类型不同，客户机操作本身不会进行直接调用。相反，它会以来自对话的响应中包含的操作对象 (以及任何输出文本) 的形式，请求客户机应用程序执行某些操作。此对象包含用于标识所请求操作的名称，以及任何必需参数和用于存储结果的上下文变量的名称。客户机应用程序负责执行所请求的操作，将结果存储在上下文中，并将其发送回包含下一条消息的对话。

您可以调用客户机应用程序来执行以下类型的操作:

验证从用户那里收集的信息。
对用户输入执行对于受支持 SpEL 表达式方法来说太复杂而无法处理的计算或字符串操作。
从其他应用程序或服务获取数据。

下图说明了客户机操作的工作方式。

显示请求天气预报的人员以及向客户机应用程序发送请求的对话框，该应用程序将请求发送到外部服务并返回结果 — 客户机操作示例

请求和响应流遵循以下模式:

客户机应用程序发送一条消息，其中包含要求天气预报的用户输入 (通过使用 message 或 message_stateless 方法)。
用户输入将触发以 #weather 意向为条件的对话节点。在对客户机的响应中，此节点指定 get_weather 客户机操作，这是客户机应用程序可识别的名称。 (这是对任何文本响应的补充，例如 Checking the weather forecast...。)
当它收到此响应时，客户机应用程序会识别正在请求 get_weather 操作。它调用外部 Web Service (/weather) 以获取实际预测信息，传递任何指定的参数 (例如用户的位置)。然后，客户机应用程序将返回的信息存储在操作请求 ($weather_forecast) 中指定的上下文变量中。
客户机应用程序向服务发送另一条消息，包括包含天气预报信息的更新上下文。从对话的角度来看，此消息实际上是下一轮用户输入，尽管实际输入文本为空白。
#weather 节点的子节点由 $weather_forecast 上下文变量的存在触发。此节点通过包含天气预报的文本输出进行响应，客户机应用程序向用户显示天气预报。 (如果未设置 $weather_forecast 变量，那么另一个子节点可以处理此情况并报告错误。)

还可以通过定义 Webhook 直接从对话节点调用外部 Web Service，而不涉及客户机应用程序。有关如何使用 Webhook 来调用外部服务的更多信息，请参阅从对话节点进行程序化调用。

过程

要从对话节点请求客户机操作，请完成以下步骤:

单击 对话框 以打开对话框树。
打开要调用操作的对话节点。
在 助手响应中，单击选项菜单菜单，然后选择 打开 JSON 编辑器。
使用以下语法来定义要请求的客户机操作。
```
{
  "context": {
    "variable_name" : "variable_value"
  },
  "actions": [
    {
      "name":"<actionName>",
      "type":"client",
      "parameters": {
        "<parameter_name>":"<parameter_value>",
        "<parameter_name>":"<parameter_value>"
      },
      "result_variable": "<result_variable_name>"
    }
  ],
  "output": {
    "text": "response text"
  }
}
```
actions 数组指定您希望客户机应用程序执行的操作。它最多可以定义五个单独的操作。在 JSON 数组中指定以下名称和值对：
- <actionName>：必需。您希望客户机应用程序执行的操作的名称。此名称可以采用任何格式 (例如，calculateRate 或 get_balance)，但必须是客户机应用程序识别并知道如何处理的名称。名称长度不能超过 256 个字符。
- <type>: 指示要进行的调用的类型。对于客户机操作，此属性是可选的 (client 是缺省值)。
- <action_parameters>: 客户机操作所需的任何参数 (指定为 JSON 对象)。如果操作不需要任何参数，请省略此属性。
- <result_variable_name>: 要用于存储客户机操作返回的 JSON 对象的上下文变量的名称。期望客户机应用程序使用指定的变量在下一个 /message 输入的上下文中发送返回值，然后后续对话节点可以对其进行访问。可以使用以下语法来指定 result_variable_name：
  - my_result
  - $my_result
  名称长度不能超过 64 个字符。变量名称不能包含以下字符: 括号 ()，方括号 ([])，单引号 (')，引号 (") 或反斜杠 (\)。
  
  您可以选择为此变量指定 context. 位置关键字前缀 (例如，context.my_result)。但是，这不是必需的，因为缺省情况下，所有上下文变量都存储在此位置中。
  
  可以在变量名称中包含句点以创建嵌套的 JSON 对象。例如，可以定义以下变量，以捕获对天气服务发出的两个独立请求（用于预测今天和明天天气）的结果：
  - context.weather.today
  - context.weather.tomorrow
  结果 (在此示例中，temp 和 rain 属性) 存储在此结构的上下文中:
```
{
  "weather": {
    "today": {
      "temp": "20",
      "rain": "30"
    },
    "tomorrow": {
      "temp": "23",
      "rain": "80"
    }
  }
}
```
  如果单个 JSON 操作数组中的多个操作将其程序化调用的结果添加到同一个上下文变量中，那么更新上下文的顺序就很重要。根据操作类型，操作的顺序定义确定设置上下文变量值的顺序。数组中最后一个操作返回的上下文变量值将覆盖由任何其他操作计算的值。
  
  result_variable 属性是必需的。如果客户机操作未返回任何结果，请指定 null 作为值。

客户机操作示例

以下示例显示了调用外部天气服务的请求可能类似的内容。该调用会添加到与节点响应关联的 JSON 编辑器中。槽在触发节点级别响应时从用户收集并存储日期和位置信息。此示例假定客户机操作名为 weather_forecast，它采用 location 参数，并且结果将存储在 weather_forecast 上下文变量中。

{
 "actions": [
   {
     "name": "get_weather",
     "type": "client",
     "parameters": {
       "location": "$location"
     },
     "result_variable": "weather_forecast"
   }
 ]
}

客户机应用程序必须检查其发送给助手的消息的响应中是否存在任何客户机操作。当它识别 get_weather 操作的请求时，它将运行该操作 (调用外部天气服务)，并将结果存储在指定的上下文变量 (weather_forecast) 中。然后，它会向服务发送一条消息，包括更新后的上下文。

要在对话中处理此消息，请在请求操作的节点之后创建子节点。您可以将此子节点的条件设置为特殊条件 true，以确保它始终由客户机在完成所请求的操作后发送的消息触发。在此子节点中，添加响应以显示用户，从 $my_forecast 上下文变量读取存储的操作结果:

{
  "output": {
    "text": {
      "values": [
        "It will be $weather_forecast in $location.literal today."
      ]
    }
  }