Azure AI 検索 で JSON BLOB とファイルのインデックスを作成する

適用対象: BLOB インデクサー、 ファイル インデクサー (プレビュー)

Azure AI 検索での BLOB インデックス作成のために、この記事では、JSON ドキュメントで構成される BLOB またはファイルのプロパティを設定する方法について説明します。 Azure Blob Storage または Azure Files の JSON ファイルでは、一般に次のような形式が想定されています。

• 1 つの JSON ドキュメント
• 整形式の JSON 要素の配列を含む JSON ドキュメント
• 改行で区切られた複数のエンティティを含む JSON ドキュメント

BLOB インデクサーには、JSON 構造に基づいて検索ドキュメントの出力を最適化する parsingMode パラメータが用意されています。 解析モードは次のオプションで構成されます。

jsonArray と jsonLines の両方について、1 つの BLOB にインデックスを付けて多数の検索ドキュメントを生成する方法に関するページを確認し、同じ BLOB から生成された複数の検索ドキュメントのドキュメント キーのあいまいさ排除が BLOB インデクサーによってどのように処理されるかを理解する必要があります。

インデクサーの定義では、必要に応じて、フィールド マッピングを設定して、ターゲットの検索インデックスの設定に使用されるソース JSON ドキュメントのプロパティを選択できます。 たとえば、jsonArray 解析モードを使用しているときに、配列が下位レベルのプロパティとして存在する場合は、BLOB 内での配列の配置場所を示す "documentRoot" プロパティを設定できます。

以下のセクションで、各モードについて詳しく説明します。 インデクサーのクライアントと概念の詳細については、検索インデクサーの作成に関するページを参照してください。 また、基本的な BLOB インデクサーの構成の詳細についても理解しておく必要があります。これについては、ここでは説明しません。

1 つの JSON ドキュメントにインデックスを付ける (BLOB ごとに 1 つ)

既定では、BLOB インデクサーによって JSON BLOB が 1 つのテキスト チャンクとして、コンテナー内の BLOB ごとに 1 つの検索ドキュメントに解析されます。 JSON が構造化されている場合、検索ドキュメントはその構造を反映でき、個々の要素が個々のフィールドとして表されます。 たとえば、Azure Blob Storage に次の JSON ドキュメントがあると仮定します。

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

BLOB インデクサーにより、JSON ドキュメントが 1 つの検索ドキュメントに解析され、ソースの "text"、"datePublished"、"tags" が、同じ名前と型のターゲット インデックス フィールドと照合されて、インデックスが読み込まれます。 "text"、"datePublished、"tags" のフィールドでインデックスを指定すると、BLOB インデクサーは、要求にフィールド マッピングがない場合でも正しいマッピングを推測することができます。

既定の動作は JSON BLOB ごとに 1 つの検索ドキュメントですが、json 解析モードを設定すると、コンテンツの内部フィールド マッピングが変更され、content 内のフィールドが検索インデックスの実際のフィールドに昇格します。 json 解析モードのインデクサー定義の例は次のようになります。

POST https://[service name].search.windows.net/indexers?api-version=2026-04-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" } }
}

json の例 (1 つの hotel JSON ファイル)

GitHub の hotel JSON ドキュメント データ セットは、各 BLOB が構造化 JSON ファイルを表す JSON 解析のテストに役立ちます。 データ ファイルを Blob Storage にアップロードし、 インポート ウィザード を使用して、このコンテンツを個々の検索ドキュメントに解析する方法をすばやく評価できます。

データ セットは 5 つの BLOB で構成され、それぞれに address コレクションと rooms コレクションを含む hotel ドキュメントが含まれています。 BLOB インデクサーによって両方のコレクションが検出され、インデックス スキーマ内の入力ドキュメントの構造が反映されます。

JSON 配列を解析する

別の方法として、[JSON 配列] オプションを使用できます。 このオプションは、BLOB に整形式の JSON オブジェクトの配列が含まれ、各要素を個別の検索ドキュメントにする場合に役立ちます。 次の JSON BLOB では、jsonArrays を使用して、それぞれ "id" フィールドと "text" フィールドを持つ 3 つの別個のドキュメントが生成されます。

[
    { "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-04-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 Storage にアップロードし、 インポート ウィザード を使用して、このコンテンツを個々の検索ドキュメントに解析する方法をすばやく評価できます。

データ セットは 8 つの BLOB で構成され、それぞれにエンティティの JSON 配列が含まれており、エンティティは合計 100 個になります。 エンティティは、どのフィールドに値が入力されるかによって異なりますが、最終的な結果は、すべての BLOB のすべての配列で、エンティティごとに 1 つの検索ドキュメントが生成されます。

入れ子になった 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-04-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 ポインターの表記を使用して指定されています。 スラッシュから始めて、JSON ドキュメントのルートを参照し、その後、スラッシュ区切りのパスを使用して、目的のプロパティ (任意の入れ子レベル) まで指定します。

0 から始まるインデックスを使用して個々の配列要素を参照することもできます。 たとえば、上の例から "tags" 配列の最初の要素を選択するには、次のようなフィールド マッピングを使用します。

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

次のステップ

• BLOB インデクサーの構成
• フィールド マッピングを定義する
• インデクサーの概要
• BLOB インデクサーを使用して CSV BLOB にインデックスを付ける方法
• チュートリアル: Azure Blob Storage で半構造化データを検索する