インデクサーを使用した Cosmos DB と Azure Search の接続Connecting Cosmos DB with Azure Search using indexers

この記事では、次のことについて説明します:In this article, learn how to:

  • Azure Cosmos DB コレクションをデータ ソースとして使用する Azure Search インデクサーを構成します。Configure Azure Search indexer that uses an Azure Cosmos DB collection as a data source.
  • JSON と互換性のあるデータ型を持つ検索インデックスを作成します。Create a search index with JSON-compatible data types.
  • インデクサーでオンデマンドおよび定期的なインデックス作成を構成します。Configure an indexer for on-demand and recurring indexing.
  • 基になるデータの変更に基づいてインデックスを増分更新します。Incrementally refresh the index based on changes in the underlying data.

注意

Azure Cosmos DB とは、次世代の DocumentDB です。Azure Cosmos DB is the next generation of DocumentDB. 製品名が変更されていますが、下位互換性のために Azure Search インデクサーの documentdb 公文は Azure Search API とポータル ページの両方に依然として存在します。Although the product name is changed, the documentdb syntax in Azure Search indexers still exists for backwards compatibility in both the Azure Search APIs and portal pages. インデクサーを構成するときには、この記事の説明に従って必ず documentdb 構文を指定します。When configuring indexers, be sure to specify the documentdb syntax as instructed in this article.

次のビデオでは、Azure Cosmos DB のプログラム マネージャーである Andrew Liu が、Azure Search インデックスを Azure Cosmos DB コンテナーに追加する方法を紹介しています。In the following video, Azure Cosmos DB Program Manager Andrew Liu demonstrates how to add an Azure Search index to an Azure Cosmos DB container.

サポートされる API の種類Supported API types

Azure Cosmos DB ではさまざまなデータ モデルと API がサポートされていますが、Azure Search インデクサーの運用サポートは SQL API のみに拡張されます。Although Azure Cosmos DB supports a variety of data models and APIs, Azure Search indexer production support extends to the SQL API only. 現在、MongoDB API のサポートはパブリック プレビュー段階にあります。Support for MongoDB API is currently in public preview.

他の API のサポートは近日公開予定です。Support for additional APIs is forthcoming. どれを最初にサポートするかは、ユーザーの声 Web サイトでの投票によって決まります。是非ご協力ください。To help us prioritize which ones to support first, please cast your vote on the User Voice web site:

前提条件Prerequisites

Cosmos DB アカウントのほかに、Azure Search サービスが必要です。In addition to a Cosmos DB account, you need to have a Azure Search service.

Azure Search インデクサーの概念Azure Search indexer concepts

データ ソースは、インデックスを作成するデータ、資格情報、およびデータの変更を識別するためのポリシー (コレクション内の変更または削除されたドキュメントなど) を指定します。A data source specifies the data to index, credentials, and policies for identifying changes in the data (such as modified or deleted documents inside your collection). データ ソースは、複数のインデクサーから使用できるように、独立したリソースとして定義します。The data source is defined as an independent resource so that it can be used by multiple indexers.

インデクサー は、データ ソースからターゲットの検索インデックスにデータが流れるしくみを説明します。An indexer describes how the data flows from your data source into a target search index. インデクサーは次の目的で使用します。An indexer can be used to:

  • 1 回限りのデータのコピーを実行して、インデックスを作成する。Perform a one-time copy of the data to populate an index.
  • スケジュールに従ってデータ ソースの変更とインデックスを同期する。Sync an index with changes in the data source on a schedule.
  • 必要に応じてインデックスのオンデマンド更新を呼び出す。Invoke on-demand updates to an index as needed.

Azure Cosmos DB のインデクサーをセットアップするには、インデックス、データソースを作成したうえで、最後にインデクサーを作成する必要があります。To set up an Azure Cosmos DB indexer, you need to create an index, datasource, and finally the indexer. これらのオブジェクトは、ポータル.NET SDK、または REST API を使用して作成できます。You can create these objects using the portal, .NET SDK, or REST API.

この記事では、REST API を使用する方法について説明します。This article shows how to use the REST API. ポータルを選択した場合は、データのインポート ウィザードに従って、インデックスを含むこれらすべてのリソースを作成します。If you opt for the portal, the Import data wizard guides you through the creation of all these resources, including the index.

ヒント

データのインポート ウィザードを Azure Cosmos DB ダッシュボードから起動して、そのデータ ソースのインデックス作成を簡略化できます。You can launch the Import data wizard from the Azure Cosmos DB dashboard to simplify indexing for that data source. 左側のナビゲーションで、[コレクション] > [Add Azure Search (Azure Search の追加)] に移動します。In left-navigation, go to Collections > Add Azure Search to get started.

注意

現時点では、Azure Portal または .NET SDK を使用して、MongoDB データ ソースを作成または編集することはできません。For now, you cannot create or edit MongoDB data sources using Azure Portal or the .NET SDK. ただし、ポータルでは MongoDB のインデクサーの実行履歴を監視できますHowever, you can monitor execution history of MongoDB indexers in the portal.

手順 1: データ ソースを作成するStep 1: Create a data source

データ ソースを作成するには、POST 要求を発行します。To create a data source, do a POST:

POST https://[service name].search.windows.net/datasources?api-version=2017-11-11
Content-Type: application/json
api-key: [Search service admin key]

{
    "name": "mydocdbdatasource",
    "type": "documentdb",
    "credentials": {
        "connectionString": "AccountEndpoint=https://myCosmosDbEndpoint.documents.azure.com;AccountKey=myCosmosDbAuthKey;Database=myCosmosDbDatabaseId"
    },
    "container": { "name": "myCollection", "query": null },
    "dataChangeDetectionPolicy": {
        "@odata.type": "#Microsoft.Azure.Search.HighWaterMarkChangeDetectionPolicy",
        "highWaterMarkColumnName": "_ts"
    }
}

要求の本文には、次のフィールドを含むデータ ソースの定義が含まれている必要があります。The body of the request contains the data source definition, which should include the following fields:

  • name: データベースを表す名前を選択します。name: Choose any name to represent your database.
  • type: は documentdb である必要があります。type: Must be documentdb.
  • credentials:credentials:

    • connectionString: 必須。connectionString: Required. 次の形式で接続情報をご自身の Azure Cosmos DB データベースに指定します: AccountEndpoint=<Cosmos DB endpoint url>;AccountKey=<Cosmos DB auth key>;Database=<Cosmos DB database id>。MongoDB コレクションについては、次のように ApiKind=MongoDb を接続文字列に追加します: AccountEndpoint=<Cosmos DB endpoint url>;AccountKey=<Cosmos DB auth key>;Database=<Cosmos DB database id>;ApiKind=MongoDbSpecify the connection info to your Azure Cosmos DB database in the following format: AccountEndpoint=<Cosmos DB endpoint url>;AccountKey=<Cosmos DB auth key>;Database=<Cosmos DB database id> For MongoDB collections, add ApiKind=MongoDb to the connection string: AccountEndpoint=<Cosmos DB endpoint url>;AccountKey=<Cosmos DB auth key>;Database=<Cosmos DB database id>;ApiKind=MongoDb
  • container:container:

    • name: 必須。name: Required. インデックスを作成するデータベース コレクションの ID を指定します。Specify the id of the database collection to be indexed.
    • query: 省略可能。query: Optional. 任意の JSON ドキュメントを、Azure Search がインデックスを作成できるフラット スキーマにフラット化するクエリを指定できます。You can specify a query to flatten an arbitrary JSON document into a flat schema that Azure Search can index. MongoDB コレクションの場合、クエリはサポートされません。For MongoDB collections, queries are not supported.
  • dataChangeDetectionPolicy: 推奨。dataChangeDetectionPolicy: Recommended. 変更されたドキュメントのインデックス作成」セクションを参照してください。See Indexing Changed Documents section.
  • dataDeletionDetectionPolicy: 省略可能。dataDeletionDetectionPolicy: Optional. 削除されたドキュメントのインデックス作成」セクションを参照してください。See Indexing Deleted Documents section.

インデックス作成するデータの処理にクエリを活用するUsing queries to shape indexed data

SQL クエリを指定すると、ネストされたプロパティや配列のフラット化、JSON プロパティのプロジェクション、インデックスを作成するデータのフィルター処理を行うことができます。You can specify a SQL query to flatten nested properties or arrays, project JSON properties, and filter the data to be indexed.

警告

MongoDB コレクションではカスタム クエリはサポートされていません。container.query パラメーターは null に設定するか、省略する必要があります。Custom queries are not supported for MongoDB collections: container.query parameter must be set to null or omitted. カスタム クエリを使用する必要がある場合は、ユーザーの声 Web サイトでお知らせください。If you need to use a custom query, please let us know on User Voice.

ドキュメントのサンプル:Example document:

{
    "userId": 10001,
    "contact": {
        "firstName": "andy",
        "lastName": "hoh"
    },
    "company": "microsoft",
    "tags": ["azure", "documentdb", "search"]
}

フィルター処理クエリ:Filter query:

SELECT * FROM c WHERE c.company = "microsoft" and c._ts >= @HighWaterMark ORDER BY c._ts

平坦化クエリ:Flattening query:

SELECT c.id, c.userId, c.contact.firstName, c.contact.lastName, c.company, c._ts FROM c WHERE c._ts >= @HighWaterMark ORDER BY c._ts

プロジェクション クエリ:Projection query:

SELECT VALUE { "id":c.id, "Name":c.contact.firstName, "Company":c.company, "_ts":c._ts } FROM c WHERE c._ts >= @HighWaterMark ORDER BY c._ts

配列を平坦化するクエリ:Array flattening query:

SELECT c.id, c.userId, tag, c._ts FROM c JOIN tag IN c.tags WHERE c._ts >= @HighWaterMark ORDER BY c._ts

手順 2: インデックスを作成するStep 2: Create an index

ターゲットの Azure Search インデックスがまだない場合は、インデックスを作成します。Create a target Azure Search index if you don’t have one already. インデックスを作成するには、Azure Portal UICreate Index REST API または Index クラスを使用します。You can create an index using the Azure portal UI, the Create Index REST API or Index class.

次の例では、ID と説明のフィールドを持つインデックスを作成します。The following example creates an index with an id and description field:

POST https://[service name].search.windows.net/indexes?api-version=2017-11-11
Content-Type: application/json
api-key: [Search service admin key]

{
   "name": "mysearchindex",
   "fields": [{
     "name": "id",
     "type": "Edm.String",
     "key": true,
     "searchable": false
   }, {
     "name": "description",
     "type": "Edm.String",
     "filterable": false,
     "sortable": false,
     "facetable": false,
     "suggestions": true
   }]
 }

ターゲット インデックスのスキーマがソース JSON ドキュメントのスキーマまたはカスタムのクエリ プロジェクションの出力と互換性があることを確認します。Ensure that the schema of your target index is compatible with the schema of the source JSON documents or the output of your custom query projection.

注意

パーティション分割されたコレクションの場合、既定のドキュメント キーは Azure Cosmos DB の _rid プロパティですが、フィールド名の先頭にはアンダースコア文字を使用できないため、この名前は Azure Search によって rid に自動的に変更されます。For partitioned collections, the default document key is Azure Cosmos DB's _rid property, which Azure Search automatically renames to rid because field names cannot start with an undescore character. また、Azure Cosmos DB の _rid 値には、Azure Search キーでは無効な文字が含まれています。Also, Azure Cosmos DB _rid values contain characters that are invalid in Azure Search keys. そのため、_rid 値は Base64 でエンコードされます。For this reason, the _rid values are Base64 encoded.

MongoDB コレクションの場合、_id プロパティ名は、Azure Search によって doc_id に自動的に変更されます。For MongoDB collections, Azure Search automatically renames the _id property to doc_id.

JSON データ型と Azure Search データ型間のマッピングMapping between JSON Data Types and Azure Search Data Types

JSON データ型JSON data type 互換性のあるターゲット インデックス フィールドの型Compatible target index field types
ブール値Bool Edm.Boolean、Edm.StringEdm.Boolean, Edm.String
整数などの数値Numbers that look like integers Edm.Int32、Edm.Int64、Edm.StringEdm.Int32, Edm.Int64, Edm.String
浮動小数点などの数値Numbers that look like floating-points Edm.Double、Edm.StringEdm.Double, Edm.String
StringString Edm.StringEdm.String
プリミティブ型の配列。例: ["a"、"b"、"c"]Arrays of primitive types, for example ["a", "b", "c"] Collection(Edm.String)Collection(Edm.String)
日付などの文字列Strings that look like dates Edm.DateTimeOffset、Edm.StringEdm.DateTimeOffset, Edm.String
GeoJSON オブジェクト。例: { "type": "Point", "coordinates": [ long, lat ] }GeoJSON objects, for example { "type": "Point", "coordinates": [long, lat] } Edm.GeographyPointEdm.GeographyPoint
その他の JSON オブジェクトOther JSON objects 該当なしN/A

手順 3: インデクサーを作成するStep 3: Create an indexer

インデックスとデータ ソースを作成したら、インデクサーを作成できます。Once the index and data source have been created, you're ready to create the indexer:

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

{
  "name" : "mydocdbindexer",
  "dataSourceName" : "mydocdbdatasource",
  "targetIndexName" : "mysearchindex",
  "schedule" : { "interval" : "PT2H" }
}

このインデクサーは 2 時間ごとに実行されます (スケジュールの間隔が "PT2H" に設定されています)。This indexer runs every two hours (schedule interval is set to "PT2H"). インデクサーを 30 分ごとに実行するには、間隔を "PT30M" に設定します。To run an indexer every 30 minutes, set the interval to "PT30M". サポートされている最短の間隔は 5 分です。The shortest supported interval is 5 minutes. スケジュールは省略可能です。省略した場合、インデクサーは作成時に一度だけ実行されます。The schedule is optional - if omitted, an indexer runs only once when it's created. ただし、いつでもオンデマンドでインデクサーを実行できます。However, you can run an indexer on-demand at any time.

インデクサー作成 API の詳細については、「 インデクサーの作成」をご覧ください。For more details on the Create Indexer API, check out Create Indexer.

オンデマンドでインデクサーを実行するRunning indexer on-demand

スケジュールに従って定期的に実行されるだけでなく、オンデマンドでインデクサーを呼び出すこともできます。In addition to running periodically on a schedule, an indexer can also be invoked on demand:

POST https://[service name].search.windows.net/indexers/[indexer name]/run?api-version=2017-11-11
api-key: [Search service admin key]

注意

API の実行で正しい応答があった場合、インデクサーの呼び出しはスケジュール済みですが、実際の処理は非同期的に実行されます。When Run API returns successfully, the indexer invocation has been scheduled, but the actual processing happens asynchronously.

ポータル、または次に説明する Get Indexer Status API を使用すると、インデクサーの状態を監視できます。You can monitor the indexer status in the portal or using the Get Indexer Status API, which we describe next.

インデクサーの状態を取得するGetting indexer status

インデクサーの現在の状態と実行履歴を取得できます。You can retrieve the status and execution history of an indexer:

GET https://[service name].search.windows.net/indexers/[indexer name]/status?api-version=2017-11-11
api-key: [Search service admin key]

応答には、全体的なインデクサーの状態、最後の (または実行中の) インデクサー呼び出し、およびインデクサー呼び出しの最近の履歴が含まれています。The response contains overall indexer status, the last (or in-progress) indexer invocation, and the history of recent indexer invocations.

{
    "status":"running",
    "lastResult": {
        "status":"success",
        "errorMessage":null,
        "startTime":"2014-11-26T03:37:18.853Z",
        "endTime":"2014-11-26T03:37:19.012Z",
        "errors":[],
        "itemsProcessed":11,
        "itemsFailed":0,
        "initialTrackingState":null,
        "finalTrackingState":null
     },
    "executionHistory":[ {
        "status":"success",
         "errorMessage":null,
        "startTime":"2014-11-26T03:37:18.853Z",
        "endTime":"2014-11-26T03:37:19.012Z",
        "errors":[],
        "itemsProcessed":11,
        "itemsFailed":0,
        "initialTrackingState":null,
        "finalTrackingState":null
    }]
}

実行履歴には、最近完了した 50 件の実行内容が含まれ、時系列の逆の順に並べられます (そのため、最近の実行内容が応答の最初に表示されます)。Execution history contains up to the 50 most recent completed executions, which are sorted in reverse chronological order (so the latest execution comes first in the response).

変更されたドキュメントのインデックス作成Indexing changed documents

データ変更の検出ポリシーの目的は、変更されたデータ項目を効率的に識別することです。The purpose of a data change detection policy is to efficiently identify changed data items. 現在、唯一サポートされているポリシーは、次に示すように、Azure Cosmos DB によって指定される _ts (タイムスタンプ) プロパティを使用した High Water Mark ポリシーです。Currently, the only supported policy is the High Water Mark policy using the _ts (timestamp) property provided by Azure Cosmos DB, which is specified as follows:

{
    "@odata.type" : "#Microsoft.Azure.Search.HighWaterMarkChangeDetectionPolicy",
    "highWaterMarkColumnName" : "_ts"
}

インデクサーの優れたパフォーマンスを確保するのには、このポリシーを使用することが推奨されます。Using this policy is highly recommended to ensure good indexer performance.

カスタム クエリを使用している場合、_ts プロパティはクエリによって投影されていることを確認します。If you are using a custom query, make sure that the _ts property is projected by the query.

増分の進行状況とカスタム クエリIncremental progress and custom queries

インデックスの作成中に増分の進行状況を利用すると、一時的な障害や実行の制限時間によってインデクサーの実行が中断された場合、次の実行時に、最初からコレクション全体のインデックスを再作成するのではなく、中断したところからインデックスを作成することができます。Incremental progress during indexing ensures that if indexer execution is interrupted by transient failures or execution time limit, the indexer can pick up where it left off next time it runs, instead of having to reindex the entire collection from scratch. 大規模なコレクションのインデックスを作成する場合、この機能は特に重要です。This is especially important when indexing large collections.

カスタム クエリを使用するときに増分の進行状況を有効にするには、クエリを使用して _ts 列で結果を並べ替えておきます。To enable incremental progress when using a custom query, ensure that your query orders the results by the _ts column. こうすることで Azure Search が使用する定期的なチェックポイントが作成され、エラーが発生した場合に増分の進行状況を利用できます。This enables periodic check-pointing that Azure Search uses to provide incremental progress in the presence of failures.

ただし状況によっては、クエリに ORDER BY [collection alias]._ts 句が含まれる場合でも、クエリ結果が _ts で並べ替えられることを Azure Search で推論されない可能性があります。In some cases, even if your query contains an ORDER BY [collection alias]._ts clause, Azure Search may not infer that the query is ordered by the _ts. assumeOrderByHighWaterMarkColumn 構成プロパティを使用して結果が並べ替えられるように Azure Search に指示することもできます。You can tell Azure Search that results are ordered by using the assumeOrderByHighWaterMarkColumn configuration property. このヒントを指定するには、次のようにインデクサーを作成または更新します。To specify this hint, create or update your indexer as follows:

{
 ... other indexer definition properties
 "parameters" : {
        "configuration" : { "assumeOrderByHighWaterMarkColumn" : true } }
} 

削除されたドキュメントのインデックス作成Indexing deleted documents

コレクションから行が削除されると、通常、検索インデックスからも同様に行を削除する必要があります。When rows are deleted from the collection, you normally want to delete those rows from the search index as well. データ削除の検出ポリシーの目的は、削除されたデータ項目を効率的に識別することです。The purpose of a data deletion detection policy is to efficiently identify deleted data items. 現在、唯一サポートされているポリシーは、Soft Delete ポリシー (削除されると何らかのフラグでマークされる) のみです。このポリシーは、次のように指定します。Currently, the only supported policy is the Soft Delete policy (deletion is marked with a flag of some sort), which is specified as follows:

{
    "@odata.type" : "#Microsoft.Azure.Search.SoftDeleteColumnDeletionDetectionPolicy",
    "softDeleteColumnName" : "the property that specifies whether a document was deleted",
    "softDeleteMarkerValue" : "the value that identifies a document as deleted"
}

カスタム クエリを使用している場合、softDeleteColumnName から参照されているプロパティはクエリによって投影されていることを確認します。If you are using a custom query, make sure that the property referenced by softDeleteColumnName is projected by the query.

次の例では、ソフト削除ポリシーとともにデータ ソースを作成します。The following example creates a data source with a soft-deletion policy:

POST https://[service name].search.windows.net/datasources?api-version=2017-11-11
Content-Type: application/json
api-key: [Search service admin key]

{
    "name": "mydocdbdatasource",
    "type": "documentdb",
    "credentials": {
        "connectionString": "AccountEndpoint=https://myDocDbEndpoint.documents.azure.com;AccountKey=myDocDbAuthKey;Database=myDocDbDatabaseId"
    },
    "container": { "name": "myDocDbCollectionId" },
    "dataChangeDetectionPolicy": {
        "@odata.type": "#Microsoft.Azure.Search.HighWaterMarkChangeDetectionPolicy",
        "highWaterMarkColumnName": "_ts"
    },
    "dataDeletionDetectionPolicy": {
        "@odata.type": "#Microsoft.Azure.Search.SoftDeleteColumnDeletionDetectionPolicy",
        "softDeleteColumnName": "isDeleted",
        "softDeleteMarkerValue": "true"
    }
}

次のステップNext steps

お疲れさまでした。Congratulations! インデクサーを使用して、Azure Cosmos DB を Azure Search と統合する方法についての説明は以上で終了です。You have learned how to integrate Azure Cosmos DB with Azure Search using an indexer.