マネージド ID を使用して Azure Cosmos DB に接続する (Azure AI Search)

この記事では、接続文字列で資格情報を指定する代わりに、マネージド ID を使用して Azure Cosmos DB データベースへのインデクサー接続を設定する方法を説明します。

システム割り当てマネージド ID またはユーザー割り当てマネージド ID を使用できます。 マネージド ID は Microsoft Entra のログイン ID であり、Azure Cosmos DB のデータにアクセスするには Azure でのロールの割り当てが必要です。 必要に応じて、Azure Cosmos DB for NoSQL アカウントの disableLocalAuth を true に設定することで、データ接続の唯一の認証方法としてロールベースのアクセスを適用することができます。

前提条件

• 検索サービス用のマネージド ID を作成します。

マネージド ID 認証でサポートされているアプローチ

Azure AI 検索は、マネージド ID を使用して Azure Cosmos DB に接続するための 2 つのメカニズムをサポートしています。

• "レガシ" アプローチでは、ターゲットの Azure Cosmos DB アカウントのコントロール プレーンに対する読み取りアクセス許可を持つようにマネージド ID を構成する必要があります。 Azure AI 検索は、その ID を利用してバックグラウンドで Cosmos DB アカウントのアカウント キーをフェッチし、データにアクセスします。 Cosmos DB アカウントに "disableLocalAuth": true がある場合、このアプローチは機能しません。

• "モダン" アプローチでは、ターゲットの Azure Cosmos DB アカウントのコントロール プレーンとデータ プレーンでマネージド ID の適切なロールを構成する必要があります。 次に、Azure AI 検索は、Cosmos DB アカウント内のデータにアクセスするためのアクセス トークンを要求します。 このアプローチは、Cosmos DB アカウントに "disableLocalAuth": true がある場合でも機能します。

Azure Cosmos DB for NoSQL に接続するインデクサーは、"レガシ" と "モダン" 両方のアプローチをサポートしていますが、"モダン" アプローチを強くお勧めします。

制限事項

• Azure Cosmos DB for Gremlin および MongoDB (現在プレビュー段階) に接続するインデクサーは、"レガシ" アプローチのみをサポートしています。

Azure Cosmos DB for NoSQL に接続する

このセクションでは、"モダン" アプローチを使用して Azure Cosmos DB for NoSQL への接続を構成する手順の概要について説明します。

コントロール プレーンのロールの割り当てを構成する

1. Azure portal にサインインし、NoSQL アカウントの Cosmos DB を見つけます。

2. [アクセス制御 (IAM)] を選択します。

3. [追加] を選択し、[ロールの割り当て] を選択します。

4. 職務権限ロールの一覧から、[Cosmos DB アカウント閲覧者] を選択します。

5. [次へ] を選択します。

6. [マネージド ID] を選択し、次に [メンバー] を選択します。

7. システム割り当てのマネージド ID、または、ユーザー割り当てのマネージド ID、でフィルターします。 以前に検索サービス用に作成してあるマネージド ID が表示されます。 これを持っていない場合は、「マネージド ID を使用するように検索を構成する」を参照してください。 既に設定が済んでいてまだ使用できない場合には、数分間待機します。

8. ID を選択し、ロールの割り当てを保存します。

詳細については、「Azure Cosmos DB for NoSQL でコントロール プレーンのロールベースのアクセス制御を使用する」を参照してください。

データ プレーンのロールの割り当てを構成する

マネージド ID には、Cosmos DB アカウントのデータ プレーンから読み取るためのロールを割り当てる必要があります。 検索サービスのシステム/ユーザー割り当て ID のオブジェクト (プリンシパル) ID は、検索サービスの [ID] タブから確認できます。現時点では、この手順は Azure CLI 経由でのみ実行できます。

次の変数を設定します。

$cosmosdb_acc_name = <cosmos db account name>
$resource_group = <resource group name>
$subsciption = <subscription ID>
$system_assigned_principal = <Object (principal) ID for the search service's system/user assigned identity>
$readOnlyRoleDefinitionId = "00000000-0000-0000-0000-00000000000"
$scope=$(az cosmosdb show --name $cosmosdbname --resource-group $resourcegroup --query id --output tsv)

システム割り当て ID 用にロールの割り当てを定義します。

az cosmosdb sql role assignment create --account-name $cosmosdbname --resource-group $resourcegroup --role-definition-id $readOnlyRoleDefinitionId --principal-id $sys_principal --scope $scope

詳細については、「Azure Cosmos DB for NoSQL でデータ プレーンのロールベースのアクセス制御を使用する」を参照してください

データ ソース定義を構成する

Azure Cosmos DB for NoSQL アカウントでコントロール プレーンとデータ プレーンの両方のロールの割り当てを構成したら、そのロールの下で動作する接続を設定できます。

インデクサーは、外部データ ソースへの接続用として、データ ソース オブジェクトを使用します。 このセクションでは、システム割り当てマネージド ID またはユーザー割り当てマネージド ID を、データ ソース接続文字列で指定する方法について説明します。 その他の接続文字列の例については、マネージド ID に関する記事で確認してください。

ヒント

Azure portal でシステムまたはユーザー割り当てマネージド ID のいずれかを指定して Cosmos DB へのデータ ソース接続を作成し、その後 JSON 定義を表示して接続文字列がどのように構成されているかを確認できます。

REST API、Azure portal、.NET SDK は、システム割り当てまたはユーザー割り当てマネージド ID の使用をサポートしています。

システム割り当て ID を使用して接続する

システム割り当てマネージド ID を使用して接続する場合は、データソース定義に対して、"credentials" プロパティの形式を変更するだけで済みます。 アカウント キーまたはパスワードが設定されていない、データベース名と ResourceId を指定します。 ResourceId には、Azure Cosmos DB のサブスクリプション ID、リソースグループ、Azure Cosmos DB のアカウント名を含める必要があります。

ここでは、"モダン" アプローチを実行するデータ ソースの作成 REST API を使用する例を示します。

POST https://[service name].search.windows.net/datasources?api-version=2024-11-01-preview
{
    "name": "my-cosmosdb-ds",
    "type": "cosmosdb",
    "credentials": {
        "connectionString": "ResourceId=/subscriptions/[subscription-id]/resourceGroups/[rg-name]/providers/Microsoft.DocumentDB/databaseAccounts/[cosmos-account-name];Database=[cosmos-database];IdentityAuthType=AccessToken"
    },
    "container": { "name": "[my-cosmos-collection]" }
}

Note

IdentityAuthType プロパティが接続文字列の一部ではない場合、Azure AI 検索は下位互換性を確保するために、既定で "レガシ" アプローチを使用します。

ユーザー割り当て ID を使用して接続する

データ ソース定義に "identity" プロパティを追加する必要があります。ここで、Azure Cosmos DB アカウントへの接続に使用される特定の ID (検索サービスに割り当てることができる複数の ID の中から) を指定します。

ここでは、"モダン" アプローチでユーザー割り当て ID を使用する例を示します。

POST https://[service name].search.windows.net/datasources?api-version=2024-11-01-preview
{
    "name": "[my-cosmosdb-ds]",
    "type": "cosmosdb",
    "credentials": {
        "connectionString": "ResourceId=/subscriptions/[subscription-id]/resourceGroups/[rg-name]/providers/Microsoft.DocumentDB/databaseAccounts/[cosmos-account-name];Database=[cosmos-database];IdentityAuthType=AccessToken"
    },
    "container": { "name": "[my-cosmos-collection]"},
    "identity" : { 
        "@odata.type": "#Microsoft.Azure.Search.DataUserAssignedIdentity",
        "userAssignedIdentity": "/subscriptions/[subscription-id]/resourcegroups/[rg-name]/providers/Microsoft.ManagedIdentity/userAssignedIdentities/[my-user-managed-identity-name]" 
    }
}

Azure Cosmos DB for Gremlin/MongoDB (プレビュー) に接続する

このセクションでは、"レガシ" アプローチを使用して Azure Cosmos DB for Gremlin/Mongo への接続を構成する手順の概要について説明します。

コントロール プレーンのロールの割り当てを構成する

前と同じ手順に従って、Azure Cosmos DB for Gremlin/MongoDB のコントロール プレーンに適切なロールを割り当てます。

接続文字列の設定

• MongoDB コレクションの場合は、"ApiKind=MongoDb" を接続文字列に追加し、プレビュー REST API を使用します。
• Gremlin グラフの場合は、"ApiKind=Gremlin" を接続文字列に追加し、プレビュー REST API を使用します。
• どちらの種類でも、"レガシ" アプローチのみがサポートされています。つまり、IdentityAuthType=AccountKey またはこれを完全に省略することが唯一の有効な接続文字列です。

REST API 経由でシステム割り当て ID を使用して MongoDB コレクションに接続する例を次に示します

POST https://[service name].search.windows.net/datasources?api-version=2024-11-01-preview
{
    "name": "my-cosmosdb-ds",
    "type": "cosmosdb",
    "credentials": {
        "connectionString": "ResourceId=/subscriptions/[subscription-id]/resourceGroups/[rg-name]/providers/Microsoft.DocumentDB/databaseAccounts/[cosmos-account-name];Database=[cosmos-database];ApiKind=MongoDb"
    },
    "container": { "name": "[my-cosmos-collection]", "query": null },
    "dataChangeDetectionPolicy": null
}

ユーザー割り当て ID を使用して Gremlin グラフに接続する例を次に示します。

POST https://[service name].search.windows.net/datasources?api-version=2024-11-01-preview
{
    "name": "[my-cosmosdb-ds]",
    "type": "cosmosdb",
    "credentials": {
        "connectionString": "ResourceId=/subscriptions/[subscription-id]/resourceGroups/[rg-name]/providers/Microsoft.DocumentDB/databaseAccounts/[cosmos-account-name];Database=[cosmos-database];ApiKind=Gremlin"
    },
    "container": { "name": "[my-cosmos-collection]"},
    "identity" : { 
        "@odata.type": "#Microsoft.Azure.Search.DataUserAssignedIdentity",
        "userAssignedIdentity": "/subscriptions/[subscription-id]/resourcegroups/[rg-name]/providers/Microsoft.ManagedIdentity/userAssignedIdentities/[my-user-managed-identity-name]" 
    }
}

インデクサーを実行してアクセス許可を確認する

リモート サービスの接続情報とアクセス許可は、インデクサー処理の実行時に検証されます。 インデクサーが成功した場合、接続構文とロールの割り当ては有効です。 詳細については、「インデクサー、スキル、ドキュメントの実行またはリセット」を参照してください。

接続のトラブルシューティング

• Azure Cosmos DB for NoSQL の場合は、アカウントのアクセス権限が、特定のネットワークに制限されているかどうかを確認します。 制限を設定せずに接続を試すことにより、ファイアウォールの問題を除外できます。 詳細については、「Azure ネットワーク セキュリティで保護されたコンテンツへのインデクサー アクセス」を参照してください

• Azure Cosmos DB for NoSQL の場合、認証の問題によってインデクサーが失敗した場合は、Cosmos DB アカウントのコントロール プレーンとデータ プレーンの両方でロールの割り当てが実行されていることを確認します。

• Gremlin あるいは MongoDB で Azure Cosmos DB アカウント キーを最近ローテーションした場合は、マネージド ID 接続文字列が機能するまでに最大で 15 分間待つ必要があります。

関連項目

• Azure Cosmos DB for NoSQL を使用したインデックス作成
• Azure Cosmos DB for MongoDB を使用したインデックス作成
• Azure Cosmos DB for Apache Gremlin を使用したインデックス作成