在 Foundry IQ(Azure AI 搜尋服務)中索引 JSON blob 與檔案

備註

Foundry IQ(Azure AI 搜尋服務)提供直接的索引與查詢 API,並搭配高階知識來源與知識庫 API 用於受控檢索。 使用 Azure 入口網站、REST API 或 Azure SDK 來設定這些功能,或將代理連線到 Microsoft Foundry 入口網站 中的知識庫。

適用於: Blob 索引器、 檔案索引器(預覽版)

針對 Foundry IQ(Azure AI 搜尋服務)中的 blob 索引,本文將示範如何為 blob 或由 JSON 文件組成的檔案設定屬性。 Azure Blob 儲存體或 Azure 檔案儲存體中的 JSON 檔案通常會採用下列任一形式:

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

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

剖析模式 JSON 文件 Description
json 每個 Blob 一個 將 JSON 物件解析成單一搜尋文件的欄位。 請明確設定此模式,使用結構化 JSON 欄位而非預設的文字擷取。
jsonArray 每個 Blob 多個 剖析 blob 中的 JSON 陣列,陣列的每個元素會變成不同的搜尋文件。
jsonLines 每個 Blob 多個 剖析包含多個 JSON 實體 (及陣列) 的 blob,並以新行分隔個別元素。 索引子會在每個新行之後開始新的搜尋文件。

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

在索引來自獨立受信任寫入者的 JSON 前,請先檢視內容控制的金鑰。 解析過的屬性與對應可以對最終文件的身份有所貢獻;重複的商業 ID 不一定代表獨立的索引記錄。 名為 source 或 permission metadata 的屬性並不會證明其值已授權。 請依照每個解析器與對應路徑的 Blob 身份與權限設定檢視 。 不要假設預設的鍵對應或標準欄位名稱就能確立所有權。

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

備註

當使用 JSON 解析模式時,Foundry IQ 假設所有 blob 使用相同的解析器(無論是對 json、 jsonArray 或 jsonLines)。 如果您在相同資料來源中混合了不同的檔案類型,請考慮使用副檔名篩選條件,來控制匯入哪些檔案。

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

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

在預設解析下,blob 索引器會將 JSON blob 擷取為文字,每個 blob 在容器中都需為一份搜尋文件。 設定 parsingMode 為 以 json 以個別欄位表示結構化的 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=2026-10-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 內容和中繼資料可用的隱含欄位對應,否則您應預期明確指定個別欄位對應 (部分內容可能是機器或 AI 翻譯),如基本 Blob 索引子設定中所述。 若要覆寫現有的索引值,來源 JSON 必須提供非 Null 值。 如果來源文件中的欄位為 Null,索引子將保留現有的值。 若要明確清除欄位,請改為傳遞空字串 (“”)。 這可防止從索引中意外刪除。

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=2026-10-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=2026-10-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" ]    
    }
}

假設搜尋索引有下列欄位︰text 類型的 Edm.String、date 類型的 Edm.DateTimeOffset、tags 類型的 Collection(Edm.String)。 請注意來源中的 "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 繼續 (這是常見的使用案例)。 因為沒有驗證檢查,所以請仔細檢查對應是否有錯字,以免因錯誤原因而遺失文件。

後續步驟