使用 Azure AI 搜尋服務技能集中的內容和來源屬性參考擴充節點的路徑
在技能集執行期間，引擎會建置記憶體內部擴充樹狀結構，擷取每個擴充，例如已辨識的實體或已翻譯的文字。 在本文中，了解如何參考擴充樹狀結構中的擴充節點，以便您可將輸出傳遞至下游技能，或指定搜尋索引欄位的輸出欄位對應。
本文使用範例來說明各種案例。 如需完整語法，請參閱技能內容和輸入註釋語言。
背景概念
在檢閱語法之前，讓我們先回顧幾個重要的概念，以深入了解本文稍後所提供的範例。
| 詞彙 | 描述 |
|---|---|
| 「擴充的文件」 | 擴充的文件是一種記憶體內部結構，其會在建立時收集技能輸出，並保存與文件相關的所有擴充。 請將擴充的文件設想為樹狀結構。 一般而言，樹狀結構會從根文件層級開始，而每個新的擴充都是從先前的子系建立。 |
| 「節點」 | 在擴充的文件內，節點 (有時稱為「註釋」) 是由 OCR 技能中的 "text" 和 "layoutText" 等技能所建立和填入。 擴充的文件會同時填入擴充和原始來源欄位值，或從來源複製的中繼資料。 |
| 「內容」 | 擴充的範圍，也就是整個文件、文件的一部分，或者如果您使用影像，則為從文件擷取的影像。 依預設，擴充內容位於 "/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 索引子在文件萃取階段的過程中自動產生的「內容」欄位為基礎。 從 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"
}
]
}
註釋路徑疑難排解的提示
如果您在指定技能輸入時遇到問題，這些提示可協助您繼續進行：