技能上下文和输入注释语言
本文是有关技能上下文和输入语法的参考文档。 这是对表达式语言的完整描述，该语言用于构建扩充文档中节点的路径。
Azure AI 搜索技能可以使用和扩充来自数据源和其他技能输出的数据。 表示当前文档的索引器工作当前状态的数据工作集从来自数据源的原始数据开始，并随着每个技能迭代的输出数据逐渐扩充。 该数据在内部组织成树状结构，可以对其进行查询以用作技能输入或添加到索引。 树中的节点可以是简单值，如字符串、数字、数组或复杂对象，甚至是二进制文件。 甚至可以通过附加的结构化信息来扩充简单值。 例如，可以使用扩充树中其下存储的其他信息对字符串进行批注。 用于查询该内部结构的表达式使用本文详细介绍的复杂语法。 可以从调试会话中检查扩充的数据结构。 查询结构的表达式也可以从调试会话中进行测试。
在本文中，我们将使用以下已扩充的数据作为示例。 这些数据是典型的结构，当你使用一个包含OCR、关键短语提取、文本翻译、语言检测、实体识别技能以及自定义 tokenizer 技能的技能组来扩充文档时，你就会得到这种结构。
| 路径 | 值 |
|---|---|
document |
|
merged_content |
“BMN 110 在儿科患者中的研究”... |
keyphrases |
|
[0] |
“BMN 研究” |
[1] |
“综合征” |
[2] |
“儿科患者” |
| ... | |
locations |
|
[0] |
“IVA” |
translated_text |
“BMN 110 在儿科患者中的研究”... |
entities |
|
[0] |
|
category |
“组织” |
subcategory |
null |
confidenceScore |
0.72 |
length |
3 |
offset |
9 |
text |
“BMN” |
| ... | |
organizations |
|
[0] |
“BMN” |
language |
“en” |
normalized_images |
|
[0] |
|
layoutText |
... |
text |
|
words |
|
[0] |
“BMN” |
[1] |
的 |
[2] |
“研究” |
[3] |
“110” |
| ... | |
[1] |
|
layoutText |
... |
text |
|
words |
|
[0] |
"it" |
[1] |
是 |
[2] |
“肯定的” |
| ... | |
| ... | |
| ... |
文档根
所有数据都在一个根元素下，路径为 "/document"。 根元素是技能的默认上下文。
简单路径
使用由斜杠分隔的简单标记，可将内部扩充文档的简单路径表示出来。 此语法类似于 JSON 指针规范。
对象属性
表示对象的节点的属性将它们的值添加到属性名称下的树中。 可以通过将属性名称追加为由斜杠分隔的标记来获得这些值：
| 表达式 | 值 |
|---|---|
/document/merged_content/language |
"en" |
属性名称标记区分大小写。
数组项索引
可以使用其数字索引（如属性名称）引用数组中的特定元素：
| 表达式 | 值 |
|---|---|
/document/merged_content/keyphrases/1 |
"Syndrome" |
/document/merged_content/entities/0/text |
"BMN" |
转义序列
以下这两个字符具有特殊含义，如果它们出现在表达式中，则需要对其进行转义，并且必须按原样解释，而不是按其特殊含义解释：'/' 和 '~'。
这些字符必须分别转义为 '~0' 和 '~1'。
数组枚举
可以使用 '*' 标记获取值的数组：
| 表达式 | 值 |
|---|---|
/document/normalized_images/0/text/words/* |
["Study", "of", "BMN", "110" ...] |
该 '*' 令牌不一定在路径的末尾。 可以枚举与路径匹配的所有节点，中间有一颗星或多颗星：
| 表达式 | 值 |
|---|---|
/document/normalized_images/*/text/words/* |
["Study", "of", "BMN", "110" ... "it", "is", "certainly" ...] |
此示例返回所有匹配节点的简单列表。
使用 '#' 标记（而不是第二个 '*' 标记）可以维护更多的结构，并为每个页面的单词获取一个单独的数组：
| 表达式 | 值 |
|---|---|
/document/normalized_images/*/text/words/# |
[["Study", "of", "BMN", "110" ...], ["it", "is", "certainly" ...] ...] |
此 '#' 标记表示应将数组视为单个值而不是枚举。
枚举上下文中的数组
单独处理数组的每个元素并为每个元素设置一组不同的技能输入和输出通常很有用。
这可以通过将技能的上下文设置为枚举而不是默认的 "/document" 来完成。
在以下示例中，我们使用之前使用的输入表达式之一，但使用不同的上下文来更改所得值。
| 上下文 | 表达式 | 值 |
|---|---|---|
/document/normalized_images/* |
/document/normalized_images/*/text/words/* |
["Study", "of", "BMN", "110" ...]["it", "is", "certainly" ...]... |
对于这种上下文和输入的组合，会为每个规范化的图像执行一次此技能：一次用于"/document/normalized_images/0"，一次用于"/document/normalized_images/1"。 每个技能执行对应的两个输入值将在值列中详细说明。
在上下文中枚举数组时，技能产生的任何输出也将作为上下文的扩充添加到文档中。
在上面的示例中，名为"out"的输出将其每次执行的值分别添加到"/document/normalized_images/0/out"和"/document/normalized_images/1/out"下的文档中。
文本值
技能输入可以采用文本值作为输入，而不是从现有文档中查询动态值。 这可以通过在值前加上等于号来实现。 值可以是数字、字符串或布尔值。
字符串值可以用单引号 ' 或双引号 " 括起来。
| 表达式 | 值 |
|---|---|
=42 |
42 |
=2.45E-4 |
0.000245 |
="some string" |
"some string" |
='some other string' |
"some other string" |
="unicod\u0065" |
"unicode" |
=false |
false |
内联数组
如果某个技能输入需要数据数组，但数据当前表示为单个值，或者需要将多个不同的单个值合并到数组字段中，则可以将逗号分隔的表达式列表括在括号（[和]）中，从而以内联形式创建数组值作为技能输入表达式的一部分。 数组值可以是表达式路径或文本值的组合（根据需要）。 还可以以这种方式在数组中创建嵌套数组。
| Expression | 值 |
|---|---|
=['item'] |
["item"] |
=[$(/document/merged_content/entities/0/text), 'item'] |
["BMN", "item"] |
=[1, 3, 5] |
[1, 3, 5] |
=[true, true, false] |
[true, true, false] |
=[[$(/document/merged_content/entities/0/text), 'item'],['item2', $(/document/merged_content/keyphrases/1)]] |
[["BMN", "item"], ["item2", "Syndrome"]] |
如果技能具有解释按数组输入运行技能的上下文（也就是说，"context": "/document/pages/*"意味着技能在pages的每个“页面”中运行一次），则将该值作为表达式作为输入传递给内联数组会一次使用其中一个值。
对于示例扩充数据的示例，如果技能的的context为/document/merged_content/keyphrases/*，然后在该技能的输入上创建以下=['key phrase', $(/document/merged_content/keyphrases/*)]的内联数组，则技能执行三次，一次值为 [“关键短语”，“BMN 研究”]，另一次值为 [“关键短语”，“综合症”]，最后一次值为 [“关键短语”，“儿科患者”]。 文本“关键短语”值每次都保持不变，但表达式路径的值随每个技能执行而更改。
复合表达式
可以使用一元、二元和三元运算符将值组合在一起。
运算符可以组合文字值和路径计算得出的值。
在表达式中使用时，应将路径用 "$(" 和 ")" 括起来。
布尔值非 '!'
| 表达式 | 值 |
|---|---|
=!false |
true |
负 '-'
| 表达式 | 值 |
|---|---|
=-42 |
-42 |
=-$(/document/merged_content/entities/0/offset) |
-9 |
加 '+'
| 表达式 | 值 |
|---|---|
=2+2 |
4 |
=2+$(/document/merged_content/entities/0/offset) |
11 |
减 '-'
| 表达式 | 值 |
|---|---|
=2-1 |
1 |
=$(/document/merged_content/entities/0/offset)-2 |
7 |
乘 '*'
| 表达式 | 值 |
|---|---|
=2*3 |
6 |
=$(/document/merged_content/entities/0/offset)*2 |
18 |
除 '/'
| 表达式 | 值 |
|---|---|
=3/2 |
1.5 |
=$(/document/merged_content/entities/0/offset)/3 |
3 |
取模 '%'
| 表达式 | 值 |
|---|---|
=15%4 |
3 |
=$(/document/merged_content/entities/0/offset)%2 |
1 |
小于、小于或等于、大于、大于或等于 '<' '<=' '>' '>='
| 表达式 | 值 |
|---|---|
=15<4 |
false |
=4<=4 |
true |
=15>4 |
true |
=1>=2 |
false |
相等、不相等 '==' '!='
| Expression | 值 |
|---|---|
=15==4 |
false |
=4==4 |
true |
=15!=4 |
true |
=1!=1 |
false |
逻辑操作 and、or、独占 or '&&' '||' '^'
| 表达式 | 值 |
|---|---|
=true&&true |
true |
=true&&false |
false |
=true||true |
true |
=true||false |
true |
=false||false |
false |
=true^false |
true |
=true^true |
false |
三元运算符 '?:'
可以基于使用三元运算符的布尔表达式计算为输入提供不同的值。
| Expression | 值 |
|---|---|
=true?"true":"false" |
"true" |
=$(/document/merged_content/entities/0/offset)==9?"nine":"not nine" |
"nine" |
括号和运算符优先级
以与常用约定匹配的优先级对运算符进行计算，依次为：一元运算符，乘、除和取模，加和减，比较，相等，逻辑运算符。 通常的关联性规则也适用。
括号可用于改变求值顺序或消除歧义。
| 表达式 | 值 |
|---|---|
=3*2+5 |
11 |
=3*(2+5) |
21 |