在技能集執行期間，引擎會建置記憶體內的擴充樹狀結構來擷取每個擴充，例如已辨識的實體或已翻譯的文字。 請在本文了解如何參照擴充樹狀結構的擴充節點，以便您將輸出傳遞至下游技能，或指定搜尋索引欄位的輸出欄位對應。
本文使用範例來說明各種情境。 如需完整的語法，請參閱 技能內容和輸入批注語言。
背景概念
在檢查語法之前，我們先回顧幾個重要概念，以便加強了解本文稍後會提供的範例。
| 詞彙 | 描述 |
|---|---|
| 「擴充文件」 | 擴充文件是一種記憶體內結構，會在建立時收集技能輸出，並保留與文件相關的所有擴充。 請將擴充的文件想像為樹狀結構。 一般而言，樹狀結構是從根文件層級開始建立，每個新的擴充都是從之前的節點建立為該節點的子系。 |
| 「節點」 | 在擴充文件內，節點 (有時稱為「註釋」) 是 OCR 技能的「text」或「layoutText」等特定輸出，或產品 ID 欄位內容等原始來源欄位值，或Azure 儲存體的 Blob 的metadata_storage_path 等從來源複製的中繼資料。 |
| 「脈絡」 | 擴充的範圍可能是整個文件、一部分文件 (頁面或句子)，或者從文件中擷取的影像 (如果您使用影像)。 根據預設，擴充脈絡位於 "/document" 層級，範圍限定於資料來源包含的個別文件。 技能執行時，該技能的輸出會成為已定義脈絡的屬性。 |
不同情境的路徑
路徑的指定位置是技能集的「context」和「source」屬性，以及索引子的輸出欄位對應。
螢幕擷取畫面中的範例說明了 Azure Cosmos DB 集合的項目路徑。
context路徑是/document/HotelId，因為集合會依/HotelId欄位分割成不同文件。source路徑是/document/Description，因為此技能是翻譯技能，而您想要翻譯的欄位是每個檔案的Description欄位。
所有路徑的開頭都是 /document。 索引子開啟文件或從資料來源讀取資料列時，索引子執行的「文件破解」階段會建立擴充文件。 一開始，擴充文件的唯一節點是根節點 (/document)，它是所有其他擴充發生的來源節點。
下列清單包含數個常見範例：
-
/document是根節點，且指出 Azure 儲存體的整個 Blob，或 SQL 資料表的資料列。 -
/document/{key}是 Azure Cosmos DB 集合的文件或項目的語法，其中{key}是實際索引鍵，例如上個範例的/document/HotelId。 -
/document/content會指定 JSON Blob 的「content」屬性。 -
/document/{field}是在特定欄位執行的作業語法，例如上個範例所示的轉譯/document/Description欄位。 - 如果您要將大型文件分成較小的區塊以進行處理，
/document/pages/*或/document/sentences/*會成為脈絡。 如果「context」是/document/pages/*，則技能會對文件中的每個頁面都執行一次。 由於可能有多個頁面或句子，您可以附加/*以便將它們全部擷取。 - 如果文件包含影像，文件破解期間會建立
/document/normalized_images/*。 影像的所有路徑都會以 normalized_images 開頭。 由於文件通常會內嵌多個影像，請附加/*。
本文其餘部分的範例會以 Azure Blob 索引子在文件破解階段自動產生的「content」欄位為依據。 參照 Blob 容器的文件時，請使用 "/document/content" 這類格式，其中「content」欄位是「document」的一部分。
範例 1：簡單註釋參照
在 Azure Blob 儲存體，假設有各種檔案包含人員名稱的參照，而您想要使用實體辨識來擷取。 在下列技能定義，"/document/content" 是整份文件的文字表示法，而「people」則擷取自識別為人員的實體完整名稱。
由於預設脈絡為 "/document"，因此人員清單此時可以參照為 "/document/people"。 在這種情況下，"/document/people" 是註釋，此時有可能對應至索引的欄位，或用於相同技能集的其他技能。
{
"@odata.type": "#Microsoft.Skills.Text.V3.EntityRecognitionSkill",
"categories": [ "Person"],
"defaultLanguageCode": "en",
"inputs": [
{
"name": "text",
"source": "/document/content"
}
],
"outputs": [
{
"name": "persons",
"targetName": "people"
}
]
}
範例 2：參照文件內的陣列
此範例以上一個範例為基礎，示範如何對相同的文件叫用擴充步驟多次。 假設上個範例產生的字串陣列包含單一文件的 10 個人員姓名。 合理的後續步驟可能是第二次擴充，從完整姓名擷取姓氏。 由於有 10 筆姓名，您想在此文件呼叫此步驟 10 次，每個人員各一次。
若要重複叫用正確次數，請將脈絡設為 "/document/people/*"，其中星號 ("*") 代表擴充文件的所有節點，這些節點是 "/document/people" 的子系。 雖然這項技能只會在技能陣列定義一次，但會對文件中的每個成員都呼叫，直到所有成員皆處理完成。
{
"@odata.type": "#Microsoft.Skills.Custom.WebApiSkill",
"description": "Fictitious skill that gets the last name from a full name",
"uri": "http://names.azurewebsites.net/api/GetLastName",
"context" : "/document/people/*",
"defaultLanguageCode": "en",
"inputs": [
{
"name": "fullname",
"source": "/document/people/*"
}
],
"outputs": [
{
"name": "lastname",
"targetName": "last"
}
]
}
如果註釋是字串的陣列或集合，您可以將特定的成員設為目標，而不是整個陣列。 上一個範例會在內容所代表的每個節點下產生名為 "last" 的批注。 如果您想要參照此系列的註釋，您可以使用語法 "/document/people/*/last"。 如果您想要參照特定註釋，可以使用明確索引："/document/people/1/last」來參照在文件識別的第一個人員的姓氏。 請注意，在此語法中，陣列為「0 索引」。
範例 3：參照陣列內的成員
有時候，您必須將特定類型的所有註釋分為一組，傳遞至特定技能。 建議建立假設性的自訂技能，以從擷取自範例 2 的所有姓氏識別出最常見的姓氏。 若只要將姓氏提供給自訂技能，請將脈絡指定為 "/document"，並將輸入指定為 "/document/people/*/lastname"。
請注意，"/document/people/*/lastname" 的基數大於文件的基數。 可能有10個姓氏節點，而這份檔只有一個文件節點。 這種情況下，系統會自動建立 "/document/people/*/lastname" 陣列，包含文件中的所有元素。
{
"@odata.type": "#Microsoft.Skills.Custom.WebApiSkill",
"description": "Fictitious skill that gets the most common string from an array of strings",
"uri": "http://names.azurewebsites.net/api/MostCommonString",
"context" : "/document",
"inputs": [
{
"name": "strings",
"source": "/document/people/*/lastname"
}
],
"outputs": [
{
"name": "mostcommon",
"targetName": "common-lastname"
}
]
}
註釋路徑疑難排解的提示
如果您在指定技能輸入時遇到問題，以下提示可協助您繼續進行：