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

この記事では、接続文字列で資格情報を指定する代わりに、マネージド 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 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)

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 に関する記事で確認してください。

システム割り当てマネージド 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=2023-11-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=2023-11-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 分間待つ必要があります。

関連項目

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