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

[アーティクル]
09/03/2024

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

システム割り当てマネージド ID またはユーザー割り当てマネージド ID を使用できます。マネージド ID は Microsoft Entra のログイン ID であり、Azure Cosmos DB のデータにアクセスするには Azure でのロールの割り当てが必要です。

前提条件

検索サービス用のマネージド ID を作成します。
Azure Cosmos DB for NoSQL。オプションで、Cosmos DB アカウントの disableLocalAuth を true に設定することで、データ接続の唯一の認証方法として、ロールベースのアクセスを適用することができます。

制限事項

Gremlin および MongoDB のコレクションに対する Azure Cosmos DB のインデクサーサポートは、現在プレビュー段階です。現時点では、プレビューでの制限により、Azure AI 検索の接続にはキーの使用が必要となります。それでもマネージド ID とロールの割り当てを設定できますが、Azure AI Search ではロールの割り当てのみを使用して接続のキーを取得します。これは、インデクサーが Gremlin または MongoDB に接続している場合には、ロールベースのアプローチを構成できない制限があることを意味します。

Azure portal にサインインし、NoSQL アカウントの Cosmos DB を見つけます。
[アクセス制御 (IAM)] を選択します。
[追加] を選択し、[ロールの割り当て] を選択します。
職務権限ロールの一覧から、[Cosmos DB アカウント閲覧者] を選択します。
[次へ] を選択します。
[マネージド ID] を選択し、次に [メンバー] を選択します。
システム割り当てのマネージド ID、または、ユーザー割り当てのマネージド ID、でフィルターします。以前に検索サービス用に作成してあるマネージド ID が表示されます。これを持っていない場合は、「マネージド ID を使用するように検索を構成する」を参照してください。既に設定が済んでいてまだ使用できない場合には、数分間待機します。
ID を選択し、ロールの割り当てを保存します。

詳細については、「Microsoft Entra ID を使用して Azure Cosmos DB アカウントのロールベースのアクセス制御を構成する」をご覧ください。

次の変数を設定します。

$cosmosdb_acc_name = <cosmos db account name>
$resource_group = <resource group name>
$subsciption = <subscription ID>
$system_assigned_principal = <principal ID for the search service's system 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

接続文字列でマネージド ID を指定する

ロールの割り当てを完了したら、そのロールの下で動作する Azure Cosmos DB for NoSQL への接続を設定できます。

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

ヒント

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

システム割り当てマネージド ID

REST API、Azure portal、および .NET SDK では、システム割り当てマネージド ID の使用がサポートされています。

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

SQL コレクションの場合は、接続文字列に "ApiKind" は必要ありません。
SQL コレクションについては、ロールベースのアクセスが唯一の認証方法として適用されている場合、"IdentityAuthType=AccessToken" を追加します。 MongoDB および Gremlin コレクションには適用されません。
MongoDB コレクションの場合は、"ApiKind=MongoDb" を接続文字列に追加し、プレビュー REST API を使用します。
Gremlin グラフの場合は、"ApiKind=Gremlin" を接続文字列に追加し、プレビュー REST API を使用します。

以下に、Create Data Source REST API とマネージド ID 接続文字列を使用し、Cosmos DB アカウントからのデータにインデックスを付けるために、データソースを作成する方法の例を示します。マネージド ID 接続文字列の形式は、REST API、.NET SDK、および Azure portal において同じです。

POST https://[service name].search.windows.net/datasources?api-version=2024-07-01
{
    "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=SQL;IdentityAuthType=[AccessToken | AccountKey]"
    },
    "container": { "name": "[my-cosmos-collection]", "query": null },
    "dataChangeDetectionPolicy": null

 
}

ユーザー割り当てマネージド ID

ユーザー割り当てマネージド ID を使用して接続する場合、データソースの定義に対する変更は次の 2 つとなります。

まず、"credentials" プロパティの形式は、データベース名とアカウントキーまたはパスワードを持たない ResourceId です。 ResourceId には、Azure Cosmos DB のサブスクリプション ID、リソースグループ、Azure Cosmos DB のアカウント名を含める必要があります。
- SQL コレクションの場合は、接続文字列に "ApiKind" は必要ありません。
- SQL コレクションについては、ロールベースのアクセスが唯一の認証方法として適用されている場合、"IdentityAuthType=AccessToken" を追加します。 MongoDB および Gremlin コレクションには適用されません。
- MongoDB コレクションの場合は、"ApiKind=MongoDb" を接続文字列に追加します
- Gremlin グラフの場合は、"ApiKind=Gremlin" を接続文字列に追加します。
次に、ユーザー割り当てマネージド ID のコレクションを含む「identity」プロパティを追加します。データソースを作成するとき、ユーザー割り当てマネージド ID を 1 つだけ指定する必要があります。それを、"userAssignedIdentities" という型に設定します。

REST API を使用して、インデクサーデータソースオブジェクトを作成する方法の例を次に示します。

POST https://[service name].search.windows.net/datasources?api-version=2024-07-01

{
    "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=SQL;IdentityAuthType=[AccessToken | AccountKey]"
    },
    "container": { 
        "name": "[my-cosmos-collection]", "query": null 
    },
    "identity" : { 
        "@odata.type": "#Microsoft.Azure.Search.DataUserAssignedIdentity",
        "userAssignedIdentity": "/subscriptions/[subscription-id]/resourcegroups/[rg-name]/providers/Microsoft.ManagedIdentity/userAssignedIdentities/[my-user-managed-identity-name]" 
    },
    "dataChangeDetectionPolicy": null
}

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

トラブルシューティング

Azure Cosmos DB for NoSQL の場合は、アカウントのアクセス権限が、特定のネットワークに制限されているかどうかを確認します。制限を設定せずに接続を試すことにより、ファイアウォールの問題を除外できます。

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

次の方法で共有