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

2025-05-29

重要

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 以降を使用すると、MongoDB API を介して接続するデータソースを作成できます。最新のプレビュー REST API をお勧めします。

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

POST https://[service name].search.windows.net/datasources?api-version=2024-05-01-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
}

"type" を "cosmosdb" に指定します (必須)。
"credentials" を接続文字列に設定します。続く部分は、サポートされている形式を記述します。
"container" をコレクションに設定します。 "name" プロパティは必須です。これによって、インデックスが作成されるデータベースコレクションの ID を指定します。 Azure Cosmos DB for MongoDB の場合、"query" はサポートされていません。
データが変化しやすいので、以降の実行で新規および更新された項目だけをインデクサーで取得する場合は、"dataChangeDetectionPolicy" を設定します。
ソース項目が削除されたら場合に検索インデックスから検索ドキュメントを削除する場合は、"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 の接続文字列

マネージド 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 データベースへのインデクサー接続を設定する方法に関する記事を参照してください。

{ "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 の項目に対応している必要があります。

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

POST https://[service name].search.windows.net/indexes?api-version=2024-05-01-preview
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
    }]
}

ドキュメントキーフィールド ("key": true) を作成します。 MongoDB コレクションに基づく検索インデックスでは、"doc_id" や "rid" など、一意の値が格納された文字列フィールドをドキュメントキーとすることができます。フィールド名とデータ型が両側で同じである限り、フィールドマッピングは必要ありません。
- "doc_id" は、オブジェクト識別子の "_id" を表します。インデックスに "doc_id" フィールドを指定した場合、インデクサーによってオブジェクト識別子の値が設定されます。
- "rid" は Azure Cosmos DB のシステムプロパティです。インデックスに "rid" のフィールドを指定した場合は、base64 でエンコードされた、"rid" プロパティの値が設定されます。
- その他のフィールドの場合、検索フィールドの名前はコレクション内で定義されている名前と同じである必要があります。
コンテンツをより検索しやすくするために、追加のフィールドを作成します。詳細については、インデックスの作成に関するページを参照してください。

マッピングデータ型

JSON データ型	Azure AI Search のフィールドの型
ブール	Edm.Boolean、Edm.String
整数などの数値	Edm.Int32、Edm.Int64、Edm.String
浮動小数点などの数値	Edm.Double、Edm.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 インデクサーを構成して実行する

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

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

POST https://[service name].search.windows.net/indexers?api-version=2024-05-01-preview
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
}

フィールドの名前または種類に違いがある、または検索インデックスで複数のソースフィールドのバージョンが必要な場合、フィールドマッピングを定義します。
その他のプロパティについては、「インデクサーの作成方法」を参照してください。

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

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

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

GET https://myservice.search.windows.net/indexers/myindexer/status?api-version=2024-05-01-preview
  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 によって指定される HighWaterMarkChangeDetectionPolicy (timestamp) プロパティを使用する _ts です。

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

"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=2024-05-01-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": "[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 からコンテンツをプルするインデクサーに適用されます。