在 Azure AI 搜尋服務中編製 JSON Blob 和檔案的索引

發行項
10/16/2024

針對 Azure AI 搜尋服務中的 Blob 索引編製，本文說明如何為包含 JSON 文件的 Blob 或檔案設定屬性。 Azure Blob 儲存體或 Azure 檔案儲存體中的 JSON 檔案通常會採用下列任一形式：

單一 JSON 文件
包含語式正確 JSON 元素陣列的 JSON 文件
包含多個實體的 JSON 文件，以新行字元分隔

Blob 索引子會提供 parsingMode 參數，根據 JSON 結構將搜尋文件的輸出最佳化。剖析模式包含下列選項：

parsingMode	JSON 文件	描述
`json`	一個 blob 一個	(預設) 將 JSON blob 剖析為單一文字區塊。每一個 JSON blob 會變成單一搜尋文件。
`jsonArray`	一個 blob 多個	剖析 blob 中的 JSON 陣列，陣列的每個元素會變成不同的搜尋文件。
`jsonLines`	一個 blob 多個	剖析包含多個 JSON 實體 (及陣列) 的 blob，並以新行分隔個別元素。索引子會在每個新行之後開始新的搜尋文件。

針對 jsonArray 和 jsonLines，您應查看編製一個 blob 的索引以產生許多搜尋文件，了解 blob 索引子如何去除混淆從相同 blob 產生之多個搜尋文件的文件索引鍵。

在索引子定義中，您可以選擇性設定欄位對應，選擇用來填入目標搜尋索引的來源 JSON 文件屬性。例如，使用 jsonArray 剖析模式時，如果陣列為較低層級屬性，您可以設定 "documentRoot" 屬性，指出陣列放在 blob 中的位置。

注意

使用 JSON 剖析模式時，Azure AI 搜尋會假設所有 Blob 都使用相同的剖析器 (針對 json、jsonArray 或 jsonLines)。如果您在相同資料來源中混合了不同的檔案類型，請考慮使用副檔名篩選條件，來控制匯入哪些檔案。

下列各節會更詳細說明每一種模式。如果您不熟悉索引子用戶端和概念，請參閱建立搜尋索引子 (機器翻譯)。您也應熟悉基本 blob 索引子設定的詳細資料，本文不再重複。

編製單一 JSON 文件的索引 (每個 blob一個)

Blob 索引子預設會將 JSON blob 剖析為單一文字區塊，容器中每個 blob 一份搜尋文件。如果 JSON 已結構化，搜尋文件可以反映該結構，個別元素以個別欄位表示。例如，假設您在 Azure Blob 儲存體中有下列 JSON 文件：

{
    "article" : {
        "text" : "A hopefully useful article explaining how to parse JSON blobs",
        "datePublished" : "2020-04-13",
        "tags" : [ "search", "storage", "howto" ]    
    }
}

Blob 索引子會將 JSON 文件剖析成單一搜尋文件，藉由比對來源的 "text"、"datePublished" 和 "tags" 及名稱和類型相同的目標索引欄位，載入索引。指定索引的 "text"、"datePublished"、"tags" 欄位，blob 索引子可以推斷正確的對應，故要求中不需要欄位對應。

雖然預設行為是每個 JSON blob 一份搜尋文件，但設定 json 剖析模式會變更內容的內部欄位對應，讓 content 內的欄位升階成搜尋索引中的真正欄位。 json 剖析模式的範例索引子定義可能如下所示：

POST https://[service name].search.windows.net/indexers?api-version=2024-07-01
Content-Type: application/json
api-key: [admin key]

{
    "name" : "my-json-indexer",
    "dataSourceName" : "my-blob-datasource",
    "targetIndexName" : "my-target-index",
    "parameters" : { "configuration" : { "parsingMode" : "json" } }
}

注意

如同所有索引子，如果欄位未明確相符，除非您使用 blob 內容和中繼資料可用的隱含欄位對應，否則您應預期明確指定個別欄位對應，如基本 blob 索引子設定中所述。

json 範例 (單一旅館 JSON 檔案)

GitHub 上的旅館 JSON 文件資料集有助於測試 JSON 剖析，其中每個 Blob 都代表結構化 JSON 檔案。您可以將資料檔案上傳至 Blob 儲存體，並使用 [匯入資料] 精靈，快速評估將此內容剖析成個別搜尋文件的方式。

資料集包含五個 blob，每個都包含具有地址集合和房間集合的旅館文件。 Blob 索引子會偵測這兩個集合，並反映索引結構描述中輸入文件的結構。

剖析 JSON 陣列

或者，您可以使用 JSON 陣列選項。當 blob 包含語式正確 JSON 物件的陣列，且您希望陣列的每個元素成為個別的搜尋文件，這個選項特別實用。使用 jsonArrays，以下 JSON blob 會產生三份不同文件，每個都有 "id" 和 "text" 欄位。

[
    { "id" : "1", "text" : "example 1" },
    { "id" : "2", "text" : "example 2" },
    { "id" : "3", "text" : "example 3" }
]

索引子上的 parameters 屬性包含剖析模式值。若為 JSON 陣列，索引子定義看起來應該像下列範例。

POST https://[service name].search.windows.net/indexers?api-version=2024-07-01
Content-Type: application/json
api-key: [admin key]

{
    "name" : "my-json-indexer",
    "dataSourceName" : "my-blob-datasource",
    "targetIndexName" : "my-target-index",
    "parameters" : { "configuration" : { "parsingMode" : "jsonArray" } }
}

jsonArrays 範例

GitHub 上的紐約愛樂 JSON 資料集有助於測試 JSON 陣列剖析。您可以將資料檔案上傳至 Blob 儲存體，並使用 [匯入資料] 精靈，快速評估將此內容剖析成個別搜尋文件的方式。

資料集包含八個 blob，每個都包含實體的 JSON 陣列，總共 100 個實體。實體隨著填入欄位而有所不同，但最終結果是所有 blob 的所有陣列中，每個實體一個搜尋文件。

剖析巢狀 JSON 陣列

對於具有巢狀元素的 JSON 陣列，您可以指定 documentRoot 來表示多層級結構。例如，如果您的 Blob 看起來像這樣︰

{
    "level1" : {
        "level2" : [
            { "id" : "1", "text" : "Use the documentRoot property" },
            { "id" : "2", "text" : "to pluck the array you want to index" },
            { "id" : "3", "text" : "even if it's nested inside the document" }  
        ]
    }
}

使用這個設定來索引 level2 屬性中包含的陣列：

{
    "name" : "my-json-array-indexer",
    ... other indexer properties
    "parameters" : { "configuration" : { "parsingMode" : "jsonArray", "documentRoot" : "/level1/level2" } }
}

剖析以新行分隔的 JSON 實體

如果您的 blob 包含多個以新行分隔的 JSON 實體，且您希望每個元素變成個別搜尋文件，請使用 jsonLines。

{ "id" : "1", "text" : "example 1" }
{ "id" : "2", "text" : "example 2" }
{ "id" : "3", "text" : "example 3" }

若為 JSON 行，索引子定義應如以下範例所示。

POST https://[service name].search.windows.net/indexers?api-version=2024-07-01
Content-Type: application/json
api-key: [admin key]

{
    "name" : "my-json-indexer",
    "dataSourceName" : "my-blob-datasource",
    "targetIndexName" : "my-target-index",
    "parameters" : { "configuration" : { "parsingMode" : "jsonLines" } }
}

將 JSON 欄位對應至搜尋欄位

欄位對應會在欄位名稱與類型不相同的情況下，將來源欄位與目的地欄位建立關聯。但是，欄位對應也可以用來比對 JSON 文件的部分，並將它們「提升」到搜尋文件的最上層欄位。

下列範例會說明此情節。如需一般欄位對應的詳細資訊，請參閱欄位對應 (機器翻譯)。

{
    "article" : {
        "text" : "A hopefully useful article explaining how to parse JSON blobs",
        "datePublished" : "2016-04-13"
        "tags" : [ "search", "storage", "howto" ]    
    }
}

假設搜尋索引有下列欄位︰Edm.String 類型的 text、Edm.DateTimeOffset 類型的 date、Collection(Edm.String) 類型的 tags。請注意來源中的 "datePublished" 與索引中的 date 欄位之間的差異。若要將 JSON 對應到所需形狀，請使用下列欄位對應︰

"fieldMappings" : [
    { "sourceFieldName" : "/article/text", "targetFieldName" : "text" },
    { "sourceFieldName" : "/article/datePublished", "targetFieldName" : "date" },
    { "sourceFieldName" : "/article/tags", "targetFieldName" : "tags" }
    ]

來源欄位是使用 JSON Pointer 標記法指定。以正斜線開始參考 JSON 文件的根目錄，然後使用正斜線分隔的路徑挑選所需的屬性 (使用任意層級的巢狀結構)。

您也可以使用以零為起始的索引來參考個別陣列元素。比方說，若要從上述範例挑選 "tags" 陣列的第一個元素，請如下所示使用欄位對應︰

{ "sourceFieldName" : "/article/tags/0", "targetFieldName" : "firstTag" }

注意

如果 "sourceFieldName" 參考 JSON blob 中不存在的屬性，則會略過該對應且不會產生錯誤。此行為允許編製索引，針對具有不同結構描述的 JSON Blob 繼續 (這是常見的使用案例)。因為沒有驗證檢查，所以請仔細檢查對應是否有錯字，以免因錯誤原因而遺失文件。

共用方式為