通过

你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

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

  • 项目

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

可以使用系统分配的托管标识或用户分配的托管标识。 托管标识是 Microsoft Entra 登录名，需要 Azure 角色分配才能访问 Azure Cosmos DB 中的数据。 可以选择通过将 Azure Cosmos DB for NoSQL 帐户的 disableLocalAuth 设置为 true，强制将基于角色的访问作为数据连接的唯一身份验证方法。

先决条件

支持的托管标识身份验证方法

Azure AI 搜索支持通过两种机制使用托管标识连接到 Azure Cosmos DB。

  • 旧式方法要求配置托管标识，以便在目标 Azure Cosmos DB 帐户的控制平面上拥有读取者权限。 Azure AI 搜索利用该标识在后台提取 Cosmos DB 帐户的帐户密钥来访问数据。 如果 Cosmos DB 帐户设置为 "disableLocalAuth": true，则此方法不起作用。

  • 新式方法要求在目标 Azure Cosmos DB 帐户的控制和数据平面上配置相应的托管标识角色。 然后，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 门户并查找 Cosmos DB for NoSQL 帐户。

  2. 选择“访问控制(IAM)”。

  3. 选择“添加”，然后选择“角色分配”。

  4. 从工作职能角色列表中，选择“Cosmos DB 帐户读取者”。

  5. 选择下一步。

  6. 选择“托管标识”，然后选择“成员”。

  7. 按系统分配的托管标识或用户分配的托管标识进行筛选。 你应会看到之前为搜索服务创建的托管标识。 如果没有托管标识，请参阅配置搜索以使用托管标识。 如果已设置托管标识但它不可用，请等待几分钟。

  8. 选择标识并保存角色分配。

有关详细信息，请参阅将控制平面基于角色的访问控制与 Azure Cosmos DB for NoSQL 配合使用。

配置数据平面角色分配

需要为托管标识分配一个角色，以从 Cosmos DB 帐户的数据平面读取数据。 可以在搜索服务的“标识”选项卡中找到搜索服务的系统/用户分配标识的对象（主体）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)

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

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 帐户中配置控制平面和数据平面角色分配后，可以设置在该角色下运行的帐户连接。

索引器使用数据源对象连接到外部数据源。 本部分介绍如何在数据源连接字符串上指定系统分配的托管标识或用户分配的托管标识。 可以在有关托管标识的文章中找到更多连接字符串示例。

提示

可以在 Azure 门户中创建数据源与 Cosmos DB 的连接，指定系统或用户分配的托管标识，然后查看 JSON 定义以了解连接字符串的构建方式。

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

通过系统分配的标识进行连接

使用系统分配的托管标识进行连接时，对数据源定义的唯一更改是“凭据”属性的格式。 提供数据库名称，以及一个没有帐户密钥或密码的 ResourceId。 ResourceId 必须包含 Azure Cosmos DB 的订阅 ID、资源组和 Azure Cosmos DB 帐户名称。

以下示例使用创建数据源 REST API，该 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]" }
}

注意

如果 IdentityAuthType 属性不是连接字符串的一部分，则 Azure AI 搜索默认将采用旧式方法，以确保后向兼容性。

通过用户分配的标识进行连接

需要在数据源定义中添加一个“identity”属性，并在其中指定用于连接到 Azure Cosmos DB 帐户的特定标识（可以分配给搜索服务的多个标识中的一个）。

以下示例通过新式方法使用用户分配的标识。

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 的控制平面上为 Gremlin/MongoDB 分配相应的角色。

设置连接字符串

  • 对于 MongoDB 集合，请将“ApiKind=MongoDb”添加到连接字符串，并使用预览版 REST API。
  • 对于 Gremlin 图形，请将“ApiKind=Gremlin”添加到连接字符串，并使用预览版 REST API。
  • 对于任一类型，都仅支持旧式方法 - 也就是说，IdentityAuthType=AccountKey 是唯一有效的连接字符串，也可以完全将其省略。

以下示例通过 REST API 使用系统分配的标识连接到 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
}

以下示例使用用户分配的标识连接到 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，如果最近轮换了 Cosmos DB 帐户密钥，则需要等待 15 分钟，以便托管标识连接字符串正常工作。

另请参阅