Azure AI 検索でクエリを実行するために Azure Cosmos DB for MongoDB からデータのインデックスを付ける

重要

MongoDB API のサポートは、現在、追加の使用条件の下でパブリック プレビュー段階にあります。 現時点では、SDK のサポートはありません。

この記事では、インデクサーを構成する方法について説明します。これにより、Azure Cosmos DB for MongoDB からコンテンツがインポートされて、Azure AI Search で検索できるようになります。

この記事では、Cosmos DB に固有の情報を使用して、インデクサーの作成に関する記事を補足しています。 REST API を使用して、すべてのインデクサーに共通する 3 部構成のワークフロー (データ ソースの作成、インデックスの作成、インデクサーの作成) を示します。 データ抽出は、インデクサーの作成要求を送信したときに発生します。

用語が混乱を招く可能性があるため、Azure Cosmos DB のインデックス作成と Azure AI Search のインデックス作成は異なる操作であることに注意してください。 Azure AI Search のインデックス作成では、検索インデックスが作成され、検索サービスに読み込まれます。

前提条件

• プレビューに登録して、シナリオのフィードバックを提供します。 フォームの送信後、この機能に自動的にアクセスできます。

• Azure Cosmos DB アカウント、データベース、コレクション、およびドキュメント。 待機時間を短縮し、帯域幅の料金を回避するために、Azure AI Search と Azure Cosmos DB の両方に同じリージョンを使用します。

• Consistent に設定されている、Azure Cosmos DB コレクションに対する自動インデックス作成ポリシー。 これは既定の構成です。 Lazy インデックス作成は推奨されません。データが欠落するおそれがあります。

• 読み取りアクセス許可。 "フル アクセス" の接続文字列には、コンテンツへのアクセスを許可するキーが含まれますが、Azure ロールを使用している場合は、検索サービスのマネージド ID に Cosmos DB アカウントの閲覧者ロールのアクセス許可があることを確認してください。

• データ ソース、インデックス、インデクサーを作成するための REST クライアント。

制限事項

この機能の制限は次のとおりです。

• データ セットを指定するためのカスタム クエリはサポートされません。

• 列名 _ts は予約語です。 このフィールドが必要な場合は、別のソリューションでのインデックス作成を検討してください。

• MongoDB 属性 $ref は予約語です。 MongoDB コレクションにこれが必要な場合は、別のソリューションでのインデックス作成を検討してください。

このコネクタの代わりとして、シナリオにこれらの要件がある場合は、Push API/SDK を使用するか、シンクとして Azure AI Search インデックスを使用した Azure Data Factory を検討できます。

データ ソースを定義する

データ ソース定義では、インデックスを付けるデータ、資格情報、データの変更を識別するためのポリシーを指定します。 データ ソースは、複数のインデクサーで使用できるように、独立したリソースとして定義します。

この呼び出しでは、プレビュー REST API バージョン (2020-06-30-Preview または 2021-04-30-Preview) を指定して、MongoDB API を介して接続するデータ ソースを作成します。

1. データ ソースを作成または更新してその定義を設定します。

   POST https://[service name].search.windows.net/datasources?api-version=2021-04-30-Preview
   Content-Type: application/json
   api-key: [Search service admin key]
   {
     "name": "[my-cosmosdb-mongodb-ds]",
     "type": "cosmosdb",
     "credentials": {
       "connectionString": "AccountEndpoint=https://[cosmos-account-name].documents.azure.com;AccountKey=[cosmos-account-key];Database=[cosmos-database-name];ApiKind=MongoDb;"
     },
     "container": {
       "name": "[cosmos-db-collection]",
       "query": null
     },
     "dataChangeDetectionPolicy": {
       "@odata.type": "#Microsoft.Azure.Search.HighWaterMarkChangeDetectionPolicy",
       "highWaterMarkColumnName": "_ts"
     },
     "dataDeletionDetectionPolicy": null,
     "encryptionKey": null,
     "identity": null
   }
   

2. "type" を "cosmosdb" に指定します (必須)。

3. "credentials" を接続文字列に設定します。 続く部分は、サポートされている形式を記述します。

4. "container" をコレクションに設定します。 "name" プロパティは必須です。これによって、インデックスが作成されるデータベース コレクションの ID を指定します。 Azure Cosmos DB for MongoDB の場合、"query" はサポートされていません。

5. データが変化しやすいので、以降の実行で新規および更新された項目だけをインデクサーで取得する場合は、"dataChangeDetectionPolicy" を設定します。

6. ソース項目が削除されたら場合に検索インデックスから検索ドキュメントを削除する場合は、"dataDeletionDetectionPolicy" を設定します。

サポートされている資格情報と接続文字列

インデクサーは、次の接続を使用してコレクションに接続できます。 MongoDB API を対象とする接続の場合は、必ず接続文字列に "ApiKind" を含めます。

エンドポイント URL にポート番号は含めないでください。 ポート番号を含めると、接続は失敗します。

フル アクセス接続文字列
{ "connectionString" : "AccountEndpoint=https://<Cosmos DB account name>.documents.azure.com;AccountKey=<Cosmos DB auth key>;Database=<Cosmos DB database id>;ApiKind=MongoDb" }
左側のナビゲーション ウィンドウで [接続文字列] を選択すると、Azure portal の Azure Cosmos DB アカウント ページから "Cosmos DB 認証キー" を取得できます。 必ず プライマリ パスワード をコピーし、 Cosmo DB 認証キー の値をそれに置き換えてください。

マネージド ID の接続文字列
{ "connectionString" : "ResourceId=/subscriptions/<your subscription ID>/resourceGroups/<your resource group name>/providers/Microsoft.DocumentDB/databaseAccounts/<your cosmos db account name>/;(ApiKind=[api-kind];)" }
この接続文字列にアカウント キーは必要ありませんが、前もって、マネージド ID を使用して接続するように検索サービスを構成し、Cosmos DB アカウントの閲覧者ロールのアクセス許可を付与するロールの割り当てを作成しておく必要があります。 詳細については、マネージド ID を使用して Azure Cosmos DB データベースへのインデクサー接続を設定する方法に関する記事を参照してください。

インデックスに検索フィールドを追加する

検索インデックスに、ソース JSON ドキュメントまたはカスタム クエリ プロジェクションの出力を受け入れるフィールドを追加します。 検索インデックス スキーマがソース データに対応していることを確認してください。 Azure Cosmos DB 内のコンテンツの場合、検索インデックス スキーマは、データ ソース内の Azure Cosmos DB の項目に対応している必要があります。

1. インデックスを作成または更新して、データを格納する検索フィールドを定義します。

   POST https://[service name].search.windows.net/indexes?api-version=2020-06-30
   Content-Type: application/json
   api-key: [Search service admin key]
   
   {
       "name": "mysearchindex",
       "fields": [{
           "name": "doc_id",
           "type": "Edm.String",
           "key": true,
           "retrievable": true,
           "searchable": false
       }, {
           "name": "description",
           "type": "Edm.String",
           "filterable": false,
           "searchable": true,
           "sortable": false,
           "facetable": false,
           "suggestions": true
       }]
   }
   

2. ドキュメント キー フィールド ("key": true) を作成します。 MongoDB コレクションに基づく検索インデックスでは、"doc_id" や "rid" など、一意の値が格納された文字列フィールドをドキュメント キーとすることができます。 フィールド名とデータ型が両側で同じである限り、フィールド マッピングは必要ありません。

   • "doc_id" は、オブジェクト識別子の "_id" を表します。 インデックスに "doc_id" フィールドを指定した場合、インデクサーによってオブジェクト識別子の値が設定されます。

   • "rid" は Azure Cosmos DB のシステム プロパティです。 インデックスに "rid" のフィールドを指定した場合は、base64 でエンコードされた、"rid" プロパティの値が設定されます。

   • その他のフィールドの場合、検索フィールドの名前はコレクション内で定義されている名前と同じである必要があります。

3. コンテンツをより検索しやすくするために、追加のフィールドを作成します。 詳細については、インデックスの作成に関するページを参照してください。

マッピング データ型

JSON データ型	Azure AI Search のフィールドの型
Bool	Edm.Boolean、Edm.String
整数などの数値	Edm.Int32、Edm.Int64、Edm.String
浮動小数点などの数値	Edm.Double、Edm.String
String	Edm.String
["a", "b", "c"] などのプリミティブ型の配列	Collection(Edm.String)
日付などの文字列	Edm.DateTimeOffset、Edm.String
{ "type": "Point", "coordinates": [long, lat] } などの GeoJSON オブジェクト	Edm.GeographyPoint
その他の JSON オブジェクト	該当なし

Azure Cosmos DB for MongoDB インデクサーを構成して実行する

インデックスとデータ ソースを作成したら、インデクサーを作成できます。 インデクサーの構成では、実行時の動作を制御する入力、パラメーター、プロパティを指定します。

1. 名前を指定し、データ ソースとターゲット インデックスを参照することで、インデクサーを作成または更新します。

   POST https://[service name].search.windows.net/indexers?api-version=2020-06-30
   Content-Type: application/json
   api-key: [search service admin key]
   {
       "name" : "[my-cosmosdb-indexer]",
       "dataSourceName" : "[my-cosmosdb-mongodb-ds]",
       "targetIndexName" : "[my-search-index]",
       "disabled": null,
       "schedule": null,
       "parameters": {
           "batchSize": null,
           "maxFailedItems": 0,
           "maxFailedItemsPerBatch": 0,
           "base64EncodeKeys": false,
           "configuration": {}
           },
       "fieldMappings": [],
       "encryptionKey": null
   }
   

2. フィールドの名前または種類に違いがある、または検索インデックスで複数のソース フィールドのバージョンが必要な場合、フィールド マッピングを定義します。

3. その他のプロパティについては、「インデクサーの作成方法」を参照してください。

インデクサーは、作成されると自動的に実行されます。 これを防ぐには、"disabled" を true に設定します。 インデクサーの実行を制御するには、インデクサーをオンデマンドで実行するか、スケジュールを設定します。

インデクサーの状態を確認する

インデクサーの状態と実行履歴を監視するには、インデクサーの状態の取得要求を送信します。

GET https://myservice.search.windows.net/indexers/myindexer/status?api-version=2020-06-30
  Content-Type: application/json  
  api-key: [admin key]

応答には、状態と処理された項目の数が含まれます。 次の例のように表示されます。

    {
        "status":"running",
        "lastResult": {
            "status":"success",
            "errorMessage":null,
            "startTime":"2022-02-21T00:23:24.957Z",
            "endTime":"2022-02-21T00:36:47.752Z",
            "errors":[],
            "itemsProcessed":1599501,
            "itemsFailed":0,
            "initialTrackingState":null,
            "finalTrackingState":null
        },
        "executionHistory":
        [
            {
                "status":"success",
                "errorMessage":null,
                "startTime":"2022-02-21T00:23:24.957Z",
                "endTime":"2022-02-21T00:36:47.752Z",
                "errors":[],
                "itemsProcessed":1599501,
                "itemsFailed":0,
                "initialTrackingState":null,
                "finalTrackingState":null
            },
            ... earlier history items
        ]
    }

実行履歴には、最近完了した実行 50 件が含まれます。時系列の逆の順に並べられるため、最後の実行が最初に表示されます。

新規および変更されたドキュメントのインデックス作成

インデクサーで検索インデックスが完全に設定されたら、以降のインデクサーで、データベース内の新規および変更されたドキュメントだけのインデックスを増分的に作成することができます。

増分インデックス作成を有効にするには、データ ソース定義で "dataChangeDetectionPolicy" プロパティを設定します。 このプロパティで、データに対して使用する変更追跡メカニズムをインデクサーに指示します。

Azure Cosmos DB インデクサーの場合、唯一サポートされているポリシーは、Azure Cosmos DB によって指定される _ts (timestamp) プロパティを使用する HighWaterMarkChangeDetectionPolicy です。

次の例は、変更検出ポリシーを含むデータ ソース定義を示しています。

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

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

コレクションから行が削除されると、通常、検索インデックスからも同様に行を削除する必要があります。 データ削除の検出ポリシーの目的は、削除されたデータ項目を効率的に識別することです。 現在、唯一サポートされているポリシーは、Soft Delete ポリシー (削除されると何らかのフラグでマークされる) です。これは、データ ソース定義で次のように指定します。

"dataDeletionDetectionPolicy"": {
    "@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 で参照されるプロパティがクエリによってプロジェクションされていることを確認してください。

次の例では、ソフト削除ポリシーとともにデータ ソースを作成します。

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

{
    "name": ["my-cosmosdb-mongodb-ds]",
    "type": "cosmosdb",
    "credentials": {
        "connectionString": "AccountEndpoint=https://[cosmos-account-name].documents.azure.com;AccountKey=[cosmos-account-key];Database=[cosmos-database-name];ApiKind=MongoDB"
    },
    "container": { "name": "[my-cosmos-collection]" },
    "dataChangeDetectionPolicy": {
        "@odata.type": "#Microsoft.Azure.Search.HighWaterMarkChangeDetectionPolicy",
        "highWaterMarkColumnName": "_ts"
    },
    "dataDeletionDetectionPolicy": {
        "@odata.type": "#Microsoft.Azure.Search.SoftDeleteColumnDeletionDetectionPolicy",
        "softDeleteColumnName": "isDeleted",
        "softDeleteMarkerValue": "true"
    }
}

次のステップ

これで、インデクサーの実行、状態の監視、インデクサーの実行のスケジュール設定をどのように行うか制御できるようになりました。 次の記事は、Azure Cosmos DB からコンテンツをプルするインデクサーに適用されます。

• マネージド ID を使用して Azure Cosmos DB データベースへのインデクサー接続を設定する
• 大規模なデータ セットにインデックスを作成する
• Azure ネットワーク セキュリティ機能を使用したデータ ソースへのインデクサーのアクセス