Azure Cognitive Search で BLOB インデクサーを使用して JSON BLOB のインデックスを作成する方法How to index JSON blobs using a Blob indexer in Azure Cognitive Search

この記事では、Azure Blob Storage 内の JSON ドキュメントから構造化コンテンツを抽出するように Azure Cognitive Search BLOB インデクサーを構成し、Azure Cognitive Search で検索できるようにする方法について説明します。This article shows you how to configure an Azure Cognitive Search blob indexer to extract structured content from JSON documents in Azure Blob storage and make it searchable in Azure Cognitive Search. このワークフローでは、Azure Cognitive Search インデックスを作成し、JSON BLOB から抽出された既存のテキストと共に読み込みます。This workflow creates an Azure Cognitive Search index and loads it with existing text extracted from JSON blobs.

ポータルREST API、または .NET SDK を使用して、JSON コンテンツのインデックスを作成できます。You can use the portal, REST APIs, or .NET SDK to index JSON content. すべての方法に共通するのは、JSON ドキュメントが Azure Storage アカウントの BLOB コンテナー内にあるということです。Common to all approaches is that JSON documents are located in a blob container in an Azure Storage account. 他の Azure 以外のプラットフォームから JSON ドキュメントをプッシュする方法については、Azure Cognitive Search でのデータのインポートに関する記事をご覧ください。For guidance on pushing JSON documents from other non-Azure platforms, see Data import in Azure Cognitive Search.

Azure Blob Storage 内の JSON BLOB は、通常は、単一の JSON ドキュメント (解析モードは json) または JSON エンティティのコレクションのいずれかです。JSON blobs in Azure Blob storage are typically either a single JSON document (parsing mode is json) or a collection of JSON entities. コレクションの場合、BLOB には整形式の JSON 要素 (解析モードは jsonArray) の配列が格納されている可能性があります。For collections, the blob could have an array of well-formed JSON elements (parsing mode is jsonArray). BLOB は、改行で区切られた複数の JSON エンティティ (解析モードは jsonLines) で構成されていることもあります。Blobs could also be composed of multiple individual JSON entities separated by a newline (parsing mode is jsonLines). 要求の parsingMode パラメーターによって、出力構造が決定されます。The parsingMode parameter on the request determines the output structures.

注意

1つの BLOB から複数の検索ドキュメントにインデックスを作成する方法の詳細については、一対多のインデックス作成に関する記事を参照してください。For more information about indexing multiple search documents from a single blob, see One-to-many indexing.

ポータルの使用Use the portal

JSON ドキュメントのインデックスを作成する最も簡単な方法は、Azure portal のウィザードを使用することです。The easiest method for indexing JSON documents is to use a wizard in the Azure portal. Azure BLOB コンテナー内のメタデータを解析することにより、データのインポート ウィザードでは、既定のインデックスを作成し、ソース フィールドをターゲット インデックス フィールドにマップし、1 回の操作でインデックスを読み込むことができます。By parsing metadata in the Azure blob container, the Import data wizard can create a default index, map source fields to target index fields, and load the index in a single operation. ソース データのサイズと複雑さによっては、数分で運用可能なフルテキスト検索インデックスを作成できます。Depending on the size and complexity of source data, you could have an operational full text search index in minutes.

Azure Cognitive Search と Azure Cosmos DB の両方で (可能であれば同じリージョン内の) 同じ Azure サブスクリプションを使用することをお勧めします。We recommend using the same Azure subscription for both Azure Cognitive Search and Azure storage, preferably in the same region.

1 - ソース データを準備する1 - Prepare source data

Azure portal にサインインし、データを格納する BLOB コンテナーを作成します。Sign in to the Azure portal and create a Blob container to contain your data. パブリック アクセス レベルは、有効な任意の値に設定できます。The Public Access Level can be set to any of its valid values.

インポート データ ウィザードでデータを取得するには、ストレージ アカウント名、コンテナー名、アクセス キーが必要です。You will need the storage account name, container name, and an access key to retrieve your data in the Import data wizard.

2 - データのインポート ウィザードを開始する2 - Start Import data wizard

検索サービスの [概要] ページでは、コマンド バーからウィザードを開始できます。In the Overview page of your search service, you can start the wizard from the command bar.

ポータルの [データのインポート] コマンドImport data command in portal

3 - データ ソースを設定する3 - Set the data source

データソースのページでは、ソースが次のように指定された Azure BLOB ストレージになっている必要があります。In the data source page, the source must be Azure Blob Storage, with the following specifications:

  • [抽出されるデータ] は、 [コンテンツとメタデータ] になっている必要があります。Data to extract should be Content and metadata. このオプションを選択すると、ウィザードでインデックス スキーマを推測して、インポート用のフィールドをマップすることができます。Choosing this option allows the wizard to infer an index schema and map the fields for import.

  • [解析モード] を、 [JSON] 、" [JSON 配列] "、または " [JSON 行] " に設定する必要があります。Parsing mode should be set to JSON, JSON array or JSON lines.

    [JSON] は、各 BLOB が 1 つの検索ドキュメントであり、検索結果で独立した項目として表示されることを示します。JSON articulates each blob as a single search document, showing up as an independent item in search results.

    "JSON 配列" は、整形式の JSON データを含む BLOB 用です。この整形式の JSON は、オブジェクトの配列またはオブジェクトの配列であるプロパティに対応し、各要素をスタンドアロンの独立した検索ドキュメントとして使用できます。JSON array is for blobs that contain well-formed JSON data - the well-formed JSON corresponds to an array of objects, or has a property which is an array of objects and you want each element to be articulated as a standalone, independent search document. BLOB が複雑な場合に、 [JSON 配列] を選択しないと、BLOB 全体が 1 つのドキュメントとして取り込まれます。If blobs are complex, and you don't choose JSON array the entire blob is ingested as a single document.

    " [JSON 行] " は、改行で区切られた複数の JSON 要素で構成されている BLOB 用であり、各エンティティをスタンドアロンの独立した検索ドキュメントとして使用できます。JSON lines is for blobs composed of multiple JSON entities separated by a new-line, where you want each entity to be articulated as a standalone independent search document. BLOB が複雑なときに、" [JSON 行] " 解析モードが選択されていない場合は、BLOB 全体が単一のドキュメントとして取り込まれます。If blobs are complex, and you don't choose JSON lines parsing mode, then the entire blob is ingested as a single document.

  • [ストレージ コンテナー] では、使用するストレージ アカウントとコンテナー、またはコンテナーとして解決される接続文字列を指定する必要があります。Storage container must specify your storage account and container, or a connection string that resolves to the container. 接続文字列は、Blob service のポータル ページで取得できます。You can get connection strings on the Blob service portal page.

    BLOB データ ソースの定義

4 - ウィザードの [認知検索を追加します] ページをスキップする4 - Skip the "Add cognitive search" page in the wizard

JSON ドキュメントをインポートするときは、コグニティブ スキルを追加する必要はありません。Adding cognitive skills is not necessary for JSON document import. 特別に AI エンリッチメントを追加する必要がない場合は、この手順を省略してください。Unless you have a specific need to add AI enrichment to your indexing pipeline, you should skip this step.

このステップをスキップするには、先に次のページに移動します。To skip the step, first go to the next page.

コグニティブ検索用の次のページ ボタン

そのページから、インデックスのカスタマイズに進むことができます。From that page you can skip ahead to index customization.

コグニティブ スキル手順のスキップ

5 - インデックスの属性を設定する5 - Set index attributes

[インデックス] ページには、フィールドとデータ型およびインデックスの属性を設定するための一連のチェック ボックスが一覧表示されます。In the Index page, you should see a list of fields with a data type and a series of checkboxes for setting index attributes. このウィザードで、メタデータに基づいてソース データをサンプリングすることで、フィールドの一覧を生成できます。The wizard can generate a fields list based on metadata and by sampling the source data.

属性列の上部にあるチェック ボックスをクリックすることで、属性を一括選択できます。You can bulk-select attributes by clicking the checkbox at the top of an attribute column. クライアント アプリに返してフル検索処理の対象にする必要があるすべてのフィールドで、 [取得可能][検索可能] を選択します。Choose Retrievable and Searchable for every field that should be returned to a client app and subject to full text search processing. 整数はフルテキスト検索もあいまい検索もできないことに注意してください (数値は逐語的に評価され、多くの場合フィルターで役立ちます)。You'll notice that integers are not full text or fuzzy searchable (numbers are evaluated verbatim and are often useful in filters).

詳細については、インデックス属性言語アナライザーの説明を参照してください。Review the description of index attributes and language analyzers for more information.

時間をかけて選択内容を確認します。Take a moment to review your selections. ウィザードを実行すると、物理データ構造が作成されて、すべてのオブジェクトを削除して再作成しない限り、これらのフィールドを編集することはできません。Once you run the wizard, physical data structures are created and you won't be able to edit these fields without dropping and recreating all objects.

BLOB のインデックス定義

6 - インデクサーを作成する6 - Create indexer

完全に指定すると、ウィザードによって検索サービスに 3 つの異なるオブジェクトが作成されます。Fully specified, the wizard creates three distinct objects in your search service. データ ソース オブジェクトとインデックス オブジェクトは、Azure Cognitive Search サービスに名前付きリソースとして保存されます。A data source object and index object are saved as named resources in your Azure Cognitive Search service. 最後のステップでは、インデクサー オブジェクトが作成されます。The last step creates an indexer object. インデクサーに名前を付けると、インデクサーはスタンドアロン リソースとして存在することができ、同じウィザードのシーケンスで作成されるインデックス オブジェクトやデータ ソース オブジェクトとは独立して、スケジュールを設定したり管理したりできます。Naming the indexer allows it to exist as a standalone resource, which you can schedule and manage independently of the index and data source object, created in the same wizard sequence.

インデクサーに慣れていないユーザーのために説明すると、"インデクサー" とは Azure Cognitive Search のリソースであり、外部データ ソースで検索可能なコンテンツのクロールを行います。If you are not familiar with indexers, an indexer is a resource in Azure Cognitive Search that crawls an external data source for searchable content. データのインポート ウィザードで出力されるインデクサーでは、JSON データ ソースがクロールされ、検索可能なコンテンツが抽出されて、Azure Cognitive Search のインデックスにインポートされます。The output of the Import data wizard is an indexer that crawls your JSON data source, extracts searchable content, and imports it into an index on Azure Cognitive Search.

BLOB インデクサーの定義

[OK] をクリックしてウィザードを実行し、すべてのオブジェクトを作成します。Click OK to run the wizard and create all objects. インデックスの作成はすぐに開始されます。Indexing commences immediately.

ポータルのページでデータのインポートを監視することができます。You can monitor data import in the portal pages. 進行状況の通知では、インデックス作成の状態と、アップロードされたドキュメントの数が示されます。Progress notifications indicate indexing status and how many documents are uploaded.

インデックスの作成が完了したら、Search エクスプローラーを使用してインデックスのクエリを実行できます。When indexing is complete, you can use Search explorer to query your index.

注意

期待どおりのデータが表示されない場合は、その他のフィールドにその他の属性を設定する必要があります。If you don't see the data you expect, you might need to set more attributes on more fields. 今作成したインデックスとインデクサーを削除し、もう一度ウィザードの手順に従って、手順 5 でインデックス属性の選択内容を変更してください。Delete the index and indexer you just created, and step through the wizard again, modifying your selections for index attributes in step 5.

REST API の使用Use REST APIs

REST API を使用して、Azure Cognitive Search のすべてのインデクサーに共通する 3 部構成のワークフロー (データ ソースを作成し、インデックスを作成し、インデクサーを作成する) で、JSON BLOB データのインデックスを作成できます。You can use the REST API to index JSON blobs, following a three-part workflow common to all indexers in Azure Cognitive Search: create a data source, create an index, create an indexer. BLOB ストレージからのデータ抽出は、インデクサー作成要求を送信した時点で発生します。Data extraction from blob storage occurs when you submit the Create Indexer request. この要求が完了すると、クエリ可能なインデックスが作成されます。After this request is finished, you will have a queryable index.

このセクションの最後にある REST サンプル コードで、3 つのオブジェクトをすべて作成する方法を確認できます。You can review REST example code at the end of this section that shows how to create all three objects. このセクションには、JSON 解析モード単一 BLOBJSON 配列、および入れ子になった配列の詳細も含まれています。This section also contains details about JSON parsing modes, single blobs, JSON arrays, and nested arrays.

コードベースの JSON インデックスでは、Postman と REST API を使用して、次のオブジェクトが作成されます。For code-based JSON indexing, use Postman and the REST API to create these objects:

オブジェクトを作成して呼び出す操作は、この順序で実行する必要があります。Order of operations requires that you create and call objects in this order. ポータルを使用するワークフローとは異なり、コードを使用する方法では、インデックス作成要求を通して送信された JSON ドキュメントを受け取るために利用できるインデックスが必要です。In contrast with the portal workflow, a code approach requires an available index to accept the JSON documents sent through the Create Indexer request.

Azure Blob Storage 内の JSON BLOB は、通常は、単一の JSON ドキュメントまたは JSON "配列" のいずれかです。JSON blobs in Azure Blob storage are typically either a single JSON document or a JSON "array". Azure Cognitive Search の BLOB インデクサーでは、要求で parsingMode パラメーターを設定する方法に応じて、構成を解析できます。The blob indexer in Azure Cognitive Search can parse either construction, depending on how you set the parsingMode parameter on the request.

JSON ドキュメントJSON document parsingModeparsingMode 説明Description 可用性Availability
BLOB あたり 1 つOne per blob json JSON BLOB を 1 つのテキスト チャンクとして解析します。Parses JSON blobs as a single chunk of text. 各 JSON BLOB は、1 つの Azure Cognitive Search ドキュメントになります。Each JSON blob becomes a single Azure Cognitive Search document. REST API と .NET SDK の両方で一般公開されています。Generally available in both REST API and .NET SDK.
BLOB あたり複数Multiple per blob jsonArray 配列の各要素が別々の Azure Cognitive Search ドキュメントになる、BLOB 内の JSON 配列を解析します。Parses a JSON array in the blob, where each element of the array becomes a separate Azure Cognitive Search document. REST API と .NET SDK の両方で一般公開されています。Generally available in both REST API and .NET SDK.
BLOB あたり複数Multiple per blob jsonLines 改行によって分離された複数の JSON エンティティ ("配列") を含む BLOB を解析します。各エンティティが独立した Azure Cognitive Search ドキュメントになります。Parses a blob which contains multiple JSON entities (an "array") separated by a newline, where each entity becomes a separate Azure Cognitive Search document. REST API と .NET SDK の両方で一般公開されています。Generally available in both REST API and .NET SDK.

1 - 要求に対する入力をアセンブルする1 - Assemble inputs for the request

要求ごとに、Azure Cognitive Search サービス名と管理者キーを (POST ヘッダーに) 指定し、BLOB ストレージのストレージ アカウント名とキーを指定する必要があります。For each request, you must provide the service name and admin key for Azure Cognitive Search (in the POST header), and the storage account name and key for blob storage. Postman を使用して、Azure Cognitive Search に HTTP 要求を送信できます。You can use Postman to send HTTP requests to Azure Cognitive Search.

次の 4 つの値をメモ帳にコピーして、要求に貼り付けることができるようにします。Copy the following four values into Notepad so that you can paste them into a request:

  • Azure Cognitive Search サービス名Azure Cognitive Search service name
  • Azure Cognitive Search の管理者キーAzure Cognitive Search admin key
  • Azure ストレージ アカウント名Azure storage account name
  • Azure ストレージ アカウント キーAzure storage account key

これらの値は、ポータルで調べることができます。You can find these values in the portal:

  1. Azure Cognitive Search のポータル ページで、[概要] ページから Search サービスの URL をコピーします。In the portal pages for Azure Cognitive Search, copy the search service URL from the Overview page.

  2. 左側のナビゲーション ウィンドウで [キー] をクリックし、プライマリまたはセカンダリのいずれかのキー (どちらも働きは同じです) をコピーします。In the left navigation pane, click Keys and then copy either the primary or secondary key (they are equivalent).

  3. ストレージ アカウントのポータル ページに切り替えます。Switch to the portal pages for your storage account. 左側のナビゲーション ウィンドウで、 [設定][アクセス キー] をクリックします。In the left navigation pane, under Settings, click Access Keys. このページには、アカウント名とキーの両方が表示されます。This page provides both the account name and key. ストレージ アカウント名といずれかのキーをメモ帳にコピーします。Copy the storage account name and one of the keys to Notepad.

2 - データ ソースを作成する2 - Create a data source

この手順では、インデクサーで使用されるデータ ソース接続情報を指定します。This step provides data source connection information used by the indexer. データ ソースは、接続情報を保持する Azure Cognitive Search 内の名前付きオブジェクトです。The data source is a named object in Azure Cognitive Search that persists the connection information. azureblob というデータ ソースの種類によって、インデクサーによって呼び出されるデータ抽出動作が決まります。The data source type, azureblob, determines which data extraction behaviors are invoked by the indexer.

サービス名、管理者キー、ストレージ アカウント、およびアカウント キーのプレースホルダーを有効な値を置き換えてください。Substitute valid values for service name, admin key, storage account, and account key placeholders.

POST https://[service name].search.windows.net/datasources?api-version=2019-05-06
Content-Type: application/json
api-key: [admin key for Azure Cognitive Search]

{
    "name" : "my-blob-datasource",
    "type" : "azureblob",
    "credentials" : { "connectionString" : "DefaultEndpointsProtocol=https;AccountName=<account name>;AccountKey=<account key>;" },
    "container" : { "name" : "my-container", "query" : "optional, my-folder" }
}   

3 - ターゲット検索インデックスを作成する3 - Create a target search index

インデクサーは、インデックス スキーマとペアになります。Indexers are paired with an index schema. (ポータルではなく) API を使用する場合は、インデクサー操作で指定できるようにインデックスを事前に準備します。If you are using the API (rather than the portal), prepare an index in advance so that you can specify it on the indexer operation.

インデックスには、Azure Cognitive Search の検索可能なコンテンツが格納されます。The index stores searchable content in Azure Cognitive Search. インデックスを作成するには、検索エクスペリエンスを構成するドキュメント内のフィールド、属性、およびその他の構造が指定されているスキーマを提供します。To create an index, provide a schema that specifies the fields in a document, attributes, and other constructs that shape the search experience. ソースと同じフィールド名とデータ型を持つインデックスを作成すると、インデクサーによってソースのフィールドとインデックスのフィールドが照合されるので、フィールドを明示的にマップする作業をしなくて済みます。If you create an index that has the same field names and data types as the source, the indexer will match the source and destination fields, saving you the work of having to explicitly map the fields.

インデックス作成要求の例を次に示します。The following example shows a Create Index request. インデックスには、BLOB から抽出されたテキストを格納するための、検索可能な content フィールドが含まれます。The index will have a searchable content field to store the text extracted from blobs:

POST https://[service name].search.windows.net/indexes?api-version=2019-05-06
Content-Type: application/json
api-key: [admin key for Azure Cognitive Search]

{
      "name" : "my-target-index",
      "fields": [
        { "name": "id", "type": "Edm.String", "key": true, "searchable": false },
        { "name": "content", "type": "Edm.String", "searchable": true, "filterable": false, "sortable": false, "facetable": false }
      ]
}

4 - インデクサーを構成して実行する4 - Configure and run the indexer

インデックスおよびデータ ソースと同様に、インデクサーも Azure Cognitive Search サービス上に作成して再利用する名前付きオブジェクトです。As with an index and a data source, and indexer is also a named object that you create and reuse on an Azure Cognitive Search service. インデクサーを作成するための完全に指定された要求は次のようになります。A fully specified request to create an indexer might look as follows:

POST https://[service name].search.windows.net/indexers?api-version=2019-05-06
Content-Type: application/json
api-key: [admin key for Azure Cognitive Search]

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

インデクサーの構成は、要求の本文内にあります。Indexer configuration is in the body of the request. データ ソースと、Azure Cognitive Search に既に存在する空のターゲット インデックスが必要です。It requires a data source and an empty target index that already exists in Azure Cognitive Search.

スケジュールとパラメーターは省略可能です。Schedule and parameters are optional. これらを省略した場合、インデクサーは、解析モードとして json を使用してすぐに実行されます。If you omit them, the indexer runs immediately, using json as the parsing mode.

この特定のインデクサーには、フィールド マッピングは含まれていません。This particular indexer does not include field mappings. インデクサーの定義では、ソース JSON ドキュメントのプロパティとターゲット検索インデックスのフィールドが一致する場合は、フィールド マッピングを省略できます。Within the indexer definition, you can leave out field mappings if the properties of the source JSON document match the fields of your target search index.

REST の例REST Example

このセクションは、オブジェクトを作成するために使用されるすべての要求の要約です。This section is a recap of all the requests used for creating objects. コンポーネント パーツの詳細については、この記事の前のセクションを参照してください。For a discussion of component parts, see the previous sections in this article.

データ ソース要求Data source request

すべてのインデクサーには、既存のデータへの接続情報を提供するデータ ソース オブジェクトが必要です。All indexers require a data source object that provides connection information to existing data.

POST https://[service name].search.windows.net/datasources?api-version=2019-05-06
Content-Type: application/json
api-key: [admin key for Azure Cognitive Search]

{
    "name" : "my-blob-datasource",
    "type" : "azureblob",
    "credentials" : { "connectionString" : "DefaultEndpointsProtocol=https;AccountName=<account name>;AccountKey=<account key>;" },
    "container" : { "name" : "my-container", "query" : "optional, my-folder" }
}  

インデックス要求Index request

すべてのインデクサーには、データを受信するターゲット インデックスが必要です。All indexers require a target index that receives the data. 要求の本文には、検索可能なインデックスで目的の動作をサポートする属性が設定されたフィールドで構成されるインデックス スキーマを定義します。The body of the request defines the index schema, consisting of fields, attributed to support the desired behaviors in a searchable index. インデクサーが実行される時点で、このインデックスは空である必要があります。This index should be empty when you run the indexer.

POST https://[service name].search.windows.net/indexes?api-version=2019-05-06
Content-Type: application/json
api-key: [admin key for Azure Cognitive Search]

{
      "name" : "my-target-index",
      "fields": [
        { "name": "id", "type": "Edm.String", "key": true, "searchable": false },
        { "name": "content", "type": "Edm.String", "searchable": true, "filterable": false, "sortable": false, "facetable": false }
      ]
}

インデクサー要求Indexer request

次の要求は、完全に指定されたインデクサーを示しています。This request shows a fully-specified indexer. これには、前の例では省略されていたフィールド マッピングが含まれています。It includes field mappings, which were omitted in previous examples. 使用可能な既定値がある限り、"schedule"、"parameters"、および "fieldMappings" は省略できます。Recall that "schedule", "parameters", and "fieldMappings" are optional as long as there is an available default. "schedule" を省略すると、インデクサーはすぐに実行されます。Omitting "schedule" causes the indexer to run immediately. "parsingMode" を省略すると、インデックスでは 既定の "json" が使用されます。Omitting "parsingMode" causes the index to use the "json" default.

Azure Cognitive Search 上にインデクサーを作成すると、データのインポートがトリガーされます。Creating the indexer on Azure Cognitive Search triggers data import. それはすぐに実行されます。スケジュールが指定されている場合は、スケジュールに従って実行されます。It runs immediately, and thereafter on a schedule if you've provided one.

POST https://[service name].search.windows.net/indexers?api-version=2019-05-06
Content-Type: application/json
api-key: [admin key for Azure Cognitive Search]

{
  "name" : "my-json-indexer",
  "dataSourceName" : "my-blob-datasource",
  "targetIndexName" : "my-target-index",
  "schedule" : { "interval" : "PT2H" },
  "parameters" : { "configuration" : { "parsingMode" : "json" } },
  "fieldMappings" : [
    { "sourceFieldName" : "/article/text", "targetFieldName" : "text" },
    { "sourceFieldName" : "/article/datePublished", "targetFieldName" : "date" },
    { "sourceFieldName" : "/article/tags", "targetFieldName" : "tags" }
    ]
}

.NET SDK の使用Use .NET SDK

.NET SDK は REST API と完全に同等です。The .NET SDK has full parity with the REST API. 前の REST API セクションを確認し、概念、ワークフロー、要件を理解することをお勧めします。We recommend that you review the previous REST API section to learn concepts, workflow, and requirements. その後は、次の .NET API リファレンス ドキュメントを参照して、マネージド コードで JSON インデクサーを実装できます。You can then refer to following .NET API reference documentation to implement a JSON indexer in managed code.

解析モードParsing modes

JSON BLOB では、複数の形式を想定できます。JSON blobs can assume multiple forms. JSON インデクサーの parsingMode パラメーターによって、JSON BLOB のコンテンツをどのように解析し、Azure Cognitive Search インデックスをどのように構成するかが決まります。The parsingMode parameter on the JSON indexer determines how JSON blob content is parsed and structured in an Azure Cognitive Search index:

parsingModeparsingMode 説明Description
json 各 BLOB を単一のドキュメントとしてインデックス化します。Index each blob as a single document. 既定のプランです。This is the default.
jsonArray BLOB が JSON 配列で構成され、配列の各要素を Azure Cognitive Search で独立したドキュメントにする必要がある場合は、このモードを選択します。Choose this mode if your blobs consist of JSON arrays, and you need each element of the array to become a separate document in Azure Cognitive Search.
jsonLines BLOB が、改行で分離されている複数の JSON エンティティで構成され、各エンティティを Azure Cognitive Search で独立したドキュメントにする必要がある場合は、このモードを選択します。Choose this mode if your blobs consist of multiple JSON entities, that are separated by a new line, and you need each entity to become a separate document in Azure Cognitive Search.

ドキュメントは、検索結果の 1 つの項目として考えることができます。You can think of a document as a single item in search results. 配列の各要素を、検索結果に独立した項目として表示する場合は、jsonArray または jsonLines オプションを使用します。If you want each element in the array to show up in search results as an independent item, then use the jsonArray or jsonLines option as appropriate.

インデクサーの定義では、必要に応じて、フィールド マッピングを使用して、ターゲットの検索インデックスの設定に使用されるソース JSON ドキュメントのプロパティを選択できます。Within the indexer definition, you can optionally use field mappings to choose which properties of the source JSON document are used to populate your target search index. jsonArray 解析モードでは、配列が下位レベルのプロパティとして存在する場合は、BLOB 内での配列の配置場所を示すドキュメント ルートを設定できます。For jsonArray parsing mode, if the array exists as a lower-level property, you can set a document root indicating where the array is placed within the blob.

重要

jsonjsonArray、または jsonLines 解析モードを使用した場合、Azure Cognitive Search では、データ ソース内のすべての BLOB に JSON が含まれていると想定されます。When you use json, jsonArray or jsonLines parsing mode, Azure Cognitive Search assumes that all blobs in your data source contain JSON. JSON BLOB と JSON 以外の BLOB が混在するデータ ソースをサポートする必要がある場合は、UserVoice サイト でお知らせください。If you need to support a mix of JSON and non-JSON blobs in the same data source, let us know on our UserVoice site.

単一の JSON BLOB を解析するParse single JSON blobs

Azure Cognitive Search BLOB インデクサー は、既定では JSON BLOB を 1 つのテキスト チャンクとして解析します。By default, Azure Cognitive Search blob indexer parses JSON blobs as a single chunk of text. 多くの場合、JSON ドキュメントの構造はそのままに維持する必要があります。Often, you want to preserve the structure of your JSON documents. たとえば、Azure Blob Storage に次の JSON ドキュメントがあると仮定します。For example, assume you have the following JSON document in Azure Blob storage:

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

BLOB インデクサーでは、JSON ドキュメントが 1 つの Azure Cognitive Search ドキュメントとして解析されます。The blob indexer parses the JSON document into a single Azure Cognitive Search document. インデクサーでは、ソースの "text"、"datePublished"、"tags" が、同じ名前と型のターゲット インデックス フィールドと照合されて、インデックスが読み込まれます。The indexer loads an index by matching "text", "datePublished", and "tags" from the source against identically named and typed target index fields.

前述のように、フィールド マッピングは必要ありません。As noted, field mappings are not required. "text"、"datePublished、"tags" のフィールドでインデックスを指定すると、BLOB インデクサーは、要求にフィールド マッピングがない場合でも正しいマッピングを推測することができます。Given an index with "text", "datePublished, and "tags" fields, the blob indexer can infer the correct mapping without a field mapping present in the request.

JSON 配列を解析するParse JSON arrays

別の方法として、[JSON 配列] オプションを使用できます。Alternatively, you can use the JSON array option. このオプションは、BLOB に "JSON オブジェクトの配列" が含まれ、各要素を個別の Azure Cognitive Search ドキュメントにする場合に役立ちます。This option is useful when blobs contain an array of well-formed JSON objects, and you want each element to become a separate Azure Cognitive Search document. たとえば、次の JSON BLOB では、それぞれ "id" および "text" フィールドを持つ 3 つの独立したドキュメントで Azure Cognitive Search インデックスを作成できます。For example, given the following JSON blob, you can populate your Azure Cognitive Search index with three separate documents, each with "id" and "text" fields.

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

JSON 配列の場合、インデクサーの定義は次の例のようになります。For a JSON array, the indexer definition should look similar to the following example. parsingMode パラメーターで jsonArray パーサーが指定されていることに注意してください。Notice that the parsingMode parameter specifies the jsonArray parser. JSON BLOB のインデックスを作成するための配列に固有の要件は、適切なパーサーを指定することと、適切なデータを入力することの 2 つだけです。Specifying the right parser and having the right data input are the only two array-specific requirements for indexing JSON blobs.

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

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

この場合も、フィールドのマッピングを省略できることに注意してください。Again, notice that field mappings can be omitted. インデックスに同じ名前のフィールド "id" と "text" があるものとすると、フィールド マッピング リストを明示的に指定しなくても、BLOB インデクサーで正しいマッピングを推測できます。Assuming an index with identically named "id" and "text" fields, the blob indexer can infer the correct mapping without an explicit field mapping list.

入れ子になった配列を解析するParse nested arrays

入れ子になった要素を持つ JSON 配列では、documentRoot を指定して、複数レベルの構造であることを指示することができます。For JSON arrays having nested elements, you can specify a documentRoot to indicate a multi-level structure. たとえば、次のような BLOB があるとします。For example, if your blobs look like this:

{
    "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 プロパティに格納されている配列にインデックスを付けます。Use this configuration to index the array contained in the level2 property:

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

改行で区切られた BLOB を解析するParse blobs separated by newlines

BLOB に改行で分離された複数の JSON エンティティが含まれ、各要素を独立した Azure Cognitive Search ドキュメントにする場合は、[JSON 行] オプションを選択できます。If your blob contains multiple JSON entities separated by a newline, and you want each element to become a separate Azure Cognitive Search document, you can opt for the JSON lines option. たとえば、次の BLOB (3 つの異なる JSON があります) では、それぞれが "id" フィールドと "text" フィールドを持つ 3 つの独立したドキュメントを含む Azure Cognitive Search インデックスを作成できます。For example, given the following blob (where there are three different JSON entities), you can populate your Azure Cognitive Search index with three separate documents, each with "id" and "text" fields.

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

JSON 行では、インデクサーの定義は次の例のようになります。For JSON lines, the indexer definition should look similar to the following example. parsingMode パラメーターで jsonLines パーサーが指定されていることに注意してください。Notice that the parsingMode parameter specifies the jsonLines parser.

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

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

ここでも、jsonArray 解析モードのように、フィールド マッピングを省略できることに注意してください。Again, notice that field mappings can be omitted, similar to the jsonArray parsing mode.

フィールド マッピングを追加するAdd field mappings

ソースとターゲットのフィールドが完全には一致していない場合、要求本文のフィールド マッピング セクションでフィールド間の明示的なアソシエーションを定義できます。When source and target fields are not perfectly aligned, you can define a field mapping section in the request body for explicit field-to-field associations.

現在、Azure Cognitive Search では、プリミティブ データ型、文字列配列、および GeoJSON ポイントのみをサポートしているため、任意の JSON ドキュメントに対して直接インデックス作成を行うことはできません。Currently, Azure Cognitive Search cannot index arbitrary JSON documents directly because it supports only primitive data types, string arrays, and GeoJSON points. ただし、 フィールド マッピング を使用すると、JSON ドキュメントの一部を選択して、それを検索ドキュメントの最上位レベルのフィールドに "引き上げる" ことができます。However, you can use field mappings to pick parts of your JSON document and "lift" them into top-level fields of the search document. フィールド マッピングの基礎については、Azure Cognitive Search インデクサーのフィールド マッピングに関する記事をご覧ください。To learn about field mappings basics, see Field mappings in Azure Cognitive Search indexers.

JSON ドキュメントの例に戻りましょう。Revisiting our example JSON document:

{
    "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 フィールドを持つ検索インデックスがあるとします。Assume a search index with the following fields: text of type Edm.String, date of type Edm.DateTimeOffset, and tags of type Collection(Edm.String). ソースの "datePublished" とインデックスの date フィールド間の違いに注目してください。Notice the discrepancy between "datePublished" in the source and date field in the index. JSON を必要な形式にマッピングするには、次のフィールド マッピングを使用します。To map your JSON into the desired shape, use the following field mappings:

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

マッピング内のソース フィールド名は、 JSON ポインター の表記を使用して指定されています。The source field names in the mappings are specified using the JSON Pointer notation. スラッシュから始めて、JSON ドキュメントのルートを参照し、その後、スラッシュ区切りのパスを使用して、目的のプロパティ (任意の入れ子レベル) まで指定します。You start with a forward slash to refer to the root of your JSON document, then pick the desired property (at arbitrary level of nesting) by using forward slash-separated path.

0 から始まるインデックスを使用して個々の配列要素を参照することもできます。You can also refer to individual array elements by using a zero-based index. たとえば、上の例から "tags" 配列の最初の要素を選択するには、次のようなフィールド マッピングを使用します。For example, to pick the first element of the "tags" array from the above example, use a field mapping like this:

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

注意

フィールド マッピングのパス内のソース フィールド名が、JSON に存在しないプロパティを参照している場合、そのマッピングはエラーなしでスキップされます。If a source field name in a field mapping path refers to a property that doesn't exist in JSON, that mapping is skipped without an error. これは、異なるスキーマを使用したドキュメントをサポートできるようにするためです (一般的なユース ケースです)。This is done so that we can support documents with a different schema (which is a common use case). 検証機能がないため、フィールド マッピングの仕様を入力するときは、入力ミスをしないように注意する必要があります。Because there is no validation, you need to take care to avoid typos in your field mapping specification.

関連項目See also