技能內容和輸入註釋語言
本文是技能內容和輸入語法的參考文件。 本文會完整描述用於建構擴充文件中節點路徑的運算式語言。
Azure AI 搜尋技能可以使用和擴充來自資料來源的資料，以及來自其他技能的輸出資料。 代表目前文件索引子工作目前狀態的資料工作集，會從來自資料來源的原始資料開始，並且會隨著每個技能反覆項目的輸出資料逐漸擴充。 該資料會在內部組織在樹狀結構中，可查詢以用於技能輸入或新增至索引。 樹狀結構中的節點可以是簡單的值，例如字串和數字、陣列或複雜物件，甚至是二進位檔案。 即使是簡單的值，也可以使用其他結構化資訊來擴充。 例如，字串可以使用儲存在擴充樹狀結構底下的其他資訊來標註。 用來查詢內部結構的運算式會使用本文詳述豐富的語法。 您可以從偵錯工作階段檢查擴充的資料結構。 查詢結構的運算式也可以從偵錯工作階段進行測試。
我們會在本文中使用下列擴充資料作為範例。 此資料通常是您在使用具有 OCR、關鍵片語擷取、文字翻譯、語言偵測、實體辨識技能以及自訂權杖化工具技能的技能集來擴充文件時所得到的結構類型。
| 路徑 | 值 |
|---|---|
document |
|
merged_content |
"Study of BMN 110 in Pediatric Patients"... |
keyphrases |
|
[0] |
"Study of BMN" |
[1] |
"Syndrome" |
[2] |
"Pediatric Patients" |
| ... | |
locations |
|
[0] |
"IVA" |
translated_text |
"Étude de BMN 110 chez les patients pédiatriques"... |
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] |
"Study" |
[1] |
"of" |
[2] |
"BMN" |
[3] |
"110" |
| ... | |
[1] |
|
layoutText |
... |
text |
|
words |
|
[0] |
"it" |
[1] |
"is" |
[2] |
"certainly" |
| ... | |
| ... | |
| ... |
文件根目錄
所有資料都位於單一根項目下，路徑為 "/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 |
在行陣列中
如果特定技能輸入需要資料陣列，但資料目前會以單一值表示，或者您需要將多個不同的單一值結合到陣列欄位中，則您可以藉由將逗號分隔的表達式清單包裝在括弧 ([ 和 ]) 中，以內嵌方式建立陣列值，作為技能輸入表達式的一部分。 陣列值可以是表達式路徑或常值的組合，視需要而定。 您也可以透過此方式在陣列內建立巢狀陣列。
| 運算式 | 值 |
|---|---|
=['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 的研究"]、另一個值為 ["關鍵詞組"、"綜合症"]，最後再以 ["關鍵詞組"的值執行，"兒科患者"]。 常值「關鍵片語」值每次都會維持不變，但表達式路徑的值會隨著每個技能執行而變更。
複合運算式
您可以使用一元、二元和三元運算子，將值合併在一起。
運算子可以合併路徑評估所產生的常值和值。
在運算式內使用時，應該用 "$(" 和 ")" 括住路徑。
布林值 not '!'
| 運算式 | 值 |
|---|---|
=!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 |
相等和不相等 '==''!='
| 運算式 | 值 |
|---|---|
=15==4 |
false |
=4==4 |
true |
=15!=4 |
true |
=1!=1 |
false |
邏輯運算「和」、「或」以及「互斥或」'&&''||''^'
| 運算式 | 值 |
|---|---|
=true&&true |
true |
=true&&false |
false |
=true||true |
true |
=true||false |
true |
=false||false |
false |
=true^false |
true |
=true^true |
false |
三元運算子 '?:'
您可以使用三元運算子，根據布林運算式的評估，為輸入提供不同的值。
| 運算式 | 值 |
|---|---|
=true?"true":"false" |
"true" |
=$(/document/merged_content/entities/0/offset)==9?"nine":"not nine" |
"nine" |
括號和運算子優先順序
運算子會以符合一般慣例的優先順序進行評估：一元運算子、乘法、除法和模數、加法和減法、比較、相等和邏輯運算子。 通常也會套用關聯性規則。
括號可用來變更或釐清評估順序。
| 運算式 | 值 |
|---|---|
=3*2+5 |
11 |
=3*(2+5) |
21 |