用于在对话框中访问对象的表达式

可以使用 Spring 表达式 (SpEL) 语言来编写用于访问对象及其属性的表达式。更多信息，请参阅 Spring Expression Language(SpEL)。

求值语法

要在其他变量内部扩展变量值或调用属性和全局对象的方法，请使用 <? expression ?> 表达式语法。例如：

扩展属性

"output":{"text":"Your name is <? context.userName ?>"}

对全局对象的属性调用方法

"context":{"email": "<? @email.literal ?>"}

简写语法

了解如何使用 SpEL 简写语法快速引用以下对象：

上下文变量
实体
意向

上下文变量的简写语法

下表显示了可用于在条件表达式中编写上下文变量的简写语法示例。

简写语法
简写语法	使用 SpEL 的完整语法
`$card_type`	`context['card_type']`
`$(card-type)`	`context['card-type']`
`$card_type:VISA`	`context['card_type'] == 'VISA'`
`$card_type:(MASTER CARD)`	`context['card_type'] == 'MASTER CARD'`

可以在上下文变量名称中包含特殊字符，例如连字符或句点。但是，这样做会导致对 SpEL 表达式求值时出现问题。例如，连字符可解释为减号。要避免此类问题，请使用完整的表达式语法或简写语法 $(variable-name) 来引用该变量，并且不要在名称中使用以下特殊字符：

圆括号 ()
多个撇号 ''
引号 "

在文本响应或对话节点条件中引用上下文变量时，可以使用简短语法。

例如，Hello, $name。如果 $name 上下文变量包含 Sam，那么响应将显示为 Hello, Sam。

如果要在文本回复中使用完整语法引用上下文变量，请务必用 <? ?>. 例如，Hello, <? context['name'] ?>。

如果想要引用有多个字段的上下文变量，例如 $context.integrations.chat.browser_info.page_url。要使用完整语法，请指定 <? context['integrations']['chat']['browser_info']['page_url'] ?>。

实体的简写语法

下表列出了在引用实体时可以使用的速记语法示例。

简写语法
简写语法	使用 SpEL 的完整语法
`@year`	`entities['year']?.value`
`@year == 2016`	`entities['year']?.value == 2016`
`@year != 2016`	`entities['year']?.value != 2016`
`@city == 'Boston'`	`entities['city']?.value == 'Boston'`
`@city:Boston`	`entities['city']?.contains('Boston')`
`@city:(New York)`	`entities['city']?.contains('New York')`

在 SpEL, 中，问号 (?) 可防止在实体对象为空时触发空指针异常。

如果要检查的实体值包含 ) 字符，那么不能使用 : 运算符进行比较。例如，如果要检查 city 实体是否为 Dublin (Ohio)，那么必须使用 @city == 'Dublin (Ohio)'，而不能使用 @city:(Dublin (Ohio))。

意向的简写语法

下表列出了在引用意图时可以使用的速记语法示例。

内置全局变量

可以使用表达式语言抽取以下全局变量的属性信息：

全局变量
全局变量	定义
上下文	已处理交谈消息的 JSON 对象部分。
实体[ ]	支持默认访问1st元素的实体列表。
输入	已处理交谈消息的 JSON 对象部分。
意向[ ]	支持默认访问第一个元素的意图列表。
输出	已处理交谈消息的 JSON 对象部分。

访问实体

实体数组包含在用户输入中识别的一个或多个实体。

在测试对话框时，您可以通过在对话框节点响应中指定此表达式来查看用户输入中被识别的实体的详细信息：

<? entities ?>

对于用户输入 today，助手会识别 @sys-date 系统实体，因此响应包含以下实体对象:

 [
   {
     "entity":"sys-date",
     "location":[0,5],
     "value":"2020-12-30",
     "confidence":1.0,
     "metadata":
     {
       "calendar_type":"GREGORIAN",
       "timezone":"America/New_York"
     },
     "interpretation":
     {
       "timezone":"America/New_York",
       "relative_day":0,
       "granularity":"day",
       "calendar_type":"GREGORIAN"
      }
    }
  ]

如果要在响应中包含文本，请使用表达式中的 toJson() 方法将返回的实体列表强制转换为 JSON 对象。例如：

Recognized entities are: <? entities.toJson() ?>

在输入内容中放置实体

在条件中使用速记表达式 @city.contains('Boston') 时，对话框节点返回 true 只有当 Boston 是用户输入中检测到的第一个实体。只有当实体在输入中的位置对您很重要，并且您只想检查第一次提及时，才使用此语法。

如果希望在用户输入中提到该术语时，无论实体被提及的顺序如何，条件都返回 true，请使用完整的 SpEL 表达式。如果在所有 @city 实体中至少找到一个“波士顿”城市实体，则条件 entities['city']?.contains('Boston') 返回 true，无论其位置如何。

例如，用户提交 "I want to go from Toronto to Boston." 检测到 @city:Toronto 和 @city:Boston 实体，并在返回的数组中表示这些实体，如下所示:

entities.city[0].value = 'Toronto'
entities.city[1].value = 'Boston'

返回的数组中实体的顺序与用户输入中提及这些实体的顺序相匹配。

实体属性

每个实体都有一组与之相关的属性。可以通过实体的属性访问有关实体的信息。

实体属性
属性	定义	用法提示
置信度	表示助手对已识别实体的置信度的小数百分比。除非激活实体模糊匹配，否则实体的置信度要么为 0，要么为 1。启用模糊匹配后，缺省置信度级别阈值为 0.3。无论是否启用模糊匹配，系统实体的置信度始终为 1.0。	可以在条件中使用此属性，在置信度级别不高于您指定的百分比时，使其返回 false。
位置	从零开始的字符偏移量，用于指示检测到的实体值在输入文本中的起始和结束位置。	使用 `.literal` 可抽取 location 属性中存储的起始索引值与结束索引值之间的文本范围。
值	在输入中识别到的实体值。	此属性返回在训练数据中定义的实体值，即便已针对其某个关联同义词进行了匹配也不例外。可以使用 `.values` 来捕获可能在用户输入出现多次的实体。

实体属性用法示例

在以下示例中，技能包含 airport 实体，此实体包含值 JFK 和同义词“Kennedy Airport”。用户输入的内容是我要去肯尼迪机场。

如果要在用户输入中识别出 "JFK "实体时返回特定的响应，可以在响应条件中添加此表达式： entities.airport[0].value == 'JFK' 或 @airport = "JFK"
要返回用户在对话框响应中指定的实体名称，请使用 .literal 属性： So you want to go to <?entities.airport[0].literal?>... 或 So you want to go to @airport.literal ...

这两种格式的评估结果都是 So you want to go to Kennedy Airport...。

像 @airport:(JFK) 或 @airport.contains('JFK') 这样的表达式始终引用实体（在此示例中为）的值JFK。
例如，要在启用模糊匹配时对输入中识别为机场的词汇进行更强的限制，可以在节点条件中指定以下表达式：@airport && @airport.confidence > 0.7。只有当您的助手有 70% 的把握认为输入文本包含机场参考信息时，才会执行该节点。

在此示例中，用户输入为 Are there places to exchange currency at JFK, Logan, and O'Hare?

要捕获在用户输入中多次出现的实体类型，请使用如下语法：
```
"context":{
  "airports":"@airport.values"
}
```
要稍后在对话响应中引用捕获的列表，请使用以下语法: You asked about these airports: <? $airports.join(', ') ?>. 现在显示为类似于以下内容： You asked about these airports: JFK, Logan, O'Hare.
要捕获多个实体提及项的字面值，请使用以下语法：
```
entities['myEntityName'].![literal]
```

访问意向

意图数组包含用户输入中识别出的一个或多个意图，按置信度从高到低排序。

每个意向只有一个属性：confidence 属性。 confidence 属性为小数百分比，表示助手对识别到的意向的置信度。

在测试对话框时，您可以通过在对话框节点响应中指定此表达式来查看用户输入中可识别的意图的详细信息：

<? intents ?>

对于用户输入 Hello now，助手找到了与 #greeting 意向的完全匹配。因此，服务首先列出 #greeting 意向对象的详细信息。响应还包含在技能中定义的排名前 10 的其他意向，这些意向与置信度分数无关。（在此示例中，由于第一个意向是完全匹配，因此它在其他意向中的置信度设置为 0。）由于“试用”窗格在其请求中发送了 alternate_intents:true 参数，因此返回了排名前 10 的意向。如果要直接使用 API，并希望查看排名前 10 的结果，请确保在调用中指定此参数。如果 alternate_intents 为 false（默认值），则数组中只会返回置信度大于 0.2 的意图。

[{"intent":"greeting","confidence":1},
{"intent":"yes","confidence":0},
{"intent":"pizza-order","confidence":0}]

如果要在响应中包含文本，请在表达式中使用 toJson() 方法将返回的意向列表强制转换为 JSON 对象。例如：

Recognized intents are: <? intents.toJson() ?>

以下示例显示如何检查意向值：

intents[0] == 'Help'
intent == 'Help'

intent == 'help' 不同于 intents[0] == 'help'，因为如果未检测到意向，intent == 'help' 不会抛出异常。仅当意向置信度超过阈值时，它才会求值为 true。如果需要，可以为条件指定自定义置信度，例如 intents.size() > 0 && intents[0] == 'help' && intents[0].confidence > 0.1。

访问输入

输入 JSON 对象仅包含一个属性：text 属性。 text 属性表示用户输入的文本。

输入属性用法示例

以下示例显示如何访问输入：

要在用户输入为“是”时执行节点，请在节点条件中添加此表达式： input.text == 'Yes'

可以使用任何字符串方法对用户输入的文本进行求值或处理。例如：

要检查用户输入是否包含“Yes”，请使用：input.text.contains( 'Yes' )。
如果用户输入的是数字，那么返回 true：input.text.matches( '[0-9]+' )。
要检查输入字符串是否包含 10 个字符，请使用：input.text.length() == 10。