使用托管标识连接到 Azure Cosmos DB（Azure AI 搜索）

项目
08/26/2024

本文说明了如何使用托管标识设置到 Azure Cosmos DB 数据库的索引器连接，而不是在连接字符串中提供凭据。

可以使用系统分配的托管标识或用户分配的托管标识。托管标识是 Microsoft Entra 登录名，需要 Azure 角色分配才能访问 Azure Cosmos DB 中的数据。

先决条件

为搜索服务创建托管标识。
Azure Cosmos DB for NoSQL。可以选择通过将 Cosmos DB 帐户的 disableLocalAuth 设置为 true，强制将基于角色的访问作为数据连接的唯一身份验证方法。

限制

Azure Cosmos DB for Gremlin 和 MongoDB Collections 的索引器支持目前处于预览阶段。目前，预览限制要求 Azure AI 搜索使用密钥连接。你仍然可以设置托管标识和角色分配，但 Azure AI 搜索将仅使用角色分配来获取用于连接的密钥。此限制意味着，如果索引器连接到 Gremlin 或 MongoDB，则无法配置基于角色的方法。

登录到 Azure 门户并查找 Cosmos DB for NoSQL 帐户。
选择“访问控制(IAM)”。
选择“添加”，然后选择“角色分配”。
从工作职能角色列表中，选择“Cosmos DB 帐户读取者”。
选择下一步。
选择“托管标识”，然后选择“成员”。
按系统分配的托管标识或用户分配的托管标识进行筛选。你应会看到之前为搜索服务创建的托管标识。如果没有托管标识，请参阅配置搜索以使用托管标识。如果已设置托管标识但它不可用，请等待几分钟。
选择标识并保存角色分配。

有关详细信息，请参阅使用 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)

为系统分配的标识定义角色分配：

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 门户中创建数据源与 CosmosDB 的连接，指定系统或用户分配的托管标识，然后查看 JSON 定义以了解连接字符串的构建方式。

系统分配的托管标识

REST API、Azure 门户和 .NET SDK 支持使用系统分配的托管标识。

使用系统分配的托管标识进行连接时，对数据源定义的唯一更改是“凭据”属性的格式。提供数据库名称，以及一个没有帐户密钥或密码的 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。

下面的示例演示如何使用创建数据源 REST API 和托管标识连接字符串创建数据源以索引 Cosmos DB 帐户的数据。对于 REST API、.NET SDK 和 Azure 门户，托管标识连接字符串格式是相同的。

POST https://[service name].search.azure.cn/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

}

用户分配的托管标识

使用用户分配的托管标识进行连接时，对数据源定义进行了两项更改：

首先，“凭据”属性的格式是数据库名称，以及一个没有帐户密钥或密码的 ResourceId。 ResourceId 必须包含 Azure Cosmos DB 的订阅 ID、资源组和 Azure Cosmos DB 帐户名称。
- 对于 SQL 集合，连接字符串不需要“ApiKind”。
- 对于 SQL 集合，如果强制将基于角色的访问作为唯一的身份验证方法，请添加“IdentityAuthType=AccessToken”。它不适用于 MongoDB 和 Gremlin 集合。
- 对于 MongoDB 集合，请将“ApiKind=MongoDb”添加到连接字符串
- 对于 Gremlin 图形，请将“ApiKind=Gremlin”添加到连接字符串。
其次，添加一个包含用户分配的托管标识的“标识”属性。创建数据源时，只应提供一个用户分配的托管标识。将其设置为类型“userAssignedIdentities”。

下面是如何使用 REST API 创建索引器数据源对象的示例。

POST https://[service name].search.azure.cn/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，如果最近轮换了 Cosmos DB 帐户密钥，则需要等待 15 分钟，以便托管标识连接字符串正常工作。

通过