Azure AI Search で JSON BLOB とファイルのインデックスを作成する
適用対象: BLOB インデクサー、ファイル インデクサー
Azure AI 検索での BLOB インデックス作成のために、この記事では、JSON ドキュメントで構成される BLOB またはファイルのプロパティを設定する方法について説明します。 Azure Blob Storage または Azure Files の JSON ファイルでは、一般に次のような形式が想定されています。
- 1 つの JSON ドキュメント
- 整形式の JSON 要素の配列を含む JSON ドキュメント
- 改行で区切られた複数のエンティティを含む JSON ドキュメント
BLOB インデクサーには、JSON 構造に基づいて検索ドキュメントの出力を最適化する parsingMode パラメータが用意されています。 解析モードは次のオプションで構成されます。
| parsingMode | JSON ドキュメント | 説明 |
|---|---|---|
json |
BLOB あたり 1 つ | (既定) JSON BLOB を 1 つのテキスト チャンクとして解析します。 各 JSON BLOB が、1 つの検索ドキュメントになります。 |
jsonArray |
BLOB あたり複数 | 配列の各要素が別々の検索ドキュメントになる、BLOB 内の JSON 配列を解析します。 |
jsonLines |
BLOB あたり複数 | 個々の要素が改行で区切られた複数の JSON エンティティ (配列) を含む BLOB を解析します。 インデクサーにより、改行ごとに新しい検索ドキュメントが開始されます。 |
jsonArray と jsonLines の両方について、1 つの BLOB にインデックスを付けて多数の検索ドキュメントを生成する方法に関するページを確認し、同じ BLOB から生成された複数の検索ドキュメントのドキュメント キーのあいまいさ排除が BLOB インデクサーによってどのように処理されるかを理解する必要があります。
インデクサーの定義では、必要に応じて、フィールド マッピングを設定して、ターゲットの検索インデックスの設定に使用されるソース JSON ドキュメントのプロパティを選択できます。 たとえば、jsonArray 解析モードを使用しているときに、配列が下位レベルのプロパティとして存在する場合は、BLOB 内での配列の配置場所を示す "documentRoot" プロパティを設定できます。
Note
JSON 解析モードを使用する場合、Azure AI 検索では、すべての BLOB が同じパーサー (json、jsonArray、または jsonLines) を使用すると想定されます。 同じデータ ソースに異なるファイルの種類が混在している場合は、ファイル拡張子フィルターを使用して、インポートするファイルを制御することを検討してください。
以下のセクションで、各モードについて詳しく説明します。 インデクサーのクライアントと概念の詳細については、検索インデクサーの作成に関するページを参照してください。 また、基本的な 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=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" } }
}
Note
すべてのインデクサーと同様に、フィールドが明確に一致しない場合は、基本的な BLOB インデクサーの構成に関するページで説明されているように、BLOB のコンテンツとメタデータに使用できる暗黙のフィールド マッピングを使用しない限り、個々のフィールド マッピングを明示的に指定する必要があります。
json の例 (1 つの hotel JSON ファイル)
GitHub の hotel JSON ドキュメント データ セットは、各 BLOB が構造化 JSON ファイルを表す JSON 解析のテストに役立ちます。 データ ファイルを BLOB ストレージにアップロードし、[データのインポート] ウィザードを使用して、このコンテンツが個々の検索ドキュメントにどのように解析されるかをすばやく評価できます。
データ セットは 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=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 ストレージにアップロードし、[データのインポート] ウィザードを使用して、このコンテンツが個々の検索ドキュメントにどのように解析されるかをすばやく評価できます。
データ セットは 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=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 ポインターの表記を使用して指定されています。 スラッシュから始めて、JSON ドキュメントのルートを参照し、その後、スラッシュ区切りのパスを使用して、目的のプロパティ (任意の入れ子レベル) まで指定します。
0 から始まるインデックスを使用して個々の配列要素を参照することもできます。 たとえば、上の例から "tags" 配列の最初の要素を選択するには、次のようなフィールド マッピングを使用します。
{ "sourceFieldName" : "/article/tags/0", "targetFieldName" : "firstTag" }
Note
"sourceFieldName" が JSON BLOB に存在しないプロパティを参照している場合、そのマッピングはエラーなしでスキップされます。 この動作により、スキーマが異なる JSON BLOB に対してインデックス作成を続行できます (一般的なユース ケース)。 検証チェックが行われないので、不当な理由でドキュメントが失われないように、マッピングに入力ミスがないかよくご確認ください。