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

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

注意

Azure AI 搜索可通过Azure门户、REST API 和Azure SDK获取。它也是 Foundry IQ 的基础；Foundry IQ 是一个托管式知识层，可将企业内容转化为供 Microsoft Foundry 门户中的智能体使用的、可复用且具备权限感知能力的知识库。

本文介绍如何使用托管身份设置与 Azure Cosmos DB 数据库的索引器连接，而不是在连接字符串中提供凭据。

可以使用系统分配的托管标识或用户分配的托管标识。托管标识是 Microsoft Entra 登录名，需要 Azure 角色分配才能访问 Azure Cosmos DB 中的数据。可以选择通过将 Azure Cosmos DB for NoSQL 帐户的设置为 disableLocalAuth，true。

先决条件

为搜索服务创建托管标识。

限制

连接到 Azure Cosmos DB for Gremlin 和 MongoDB（目前以预览版提供）的索引器仅支持旧式方法。

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

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，此方法也能正常工作。

连接到 NoSQL Azure Cosmos DB 的索引器支持 legacy 和 modern 方法 - 建议使用 modern 方法。

连接到 Azure Cosmos DB（用于 NoSQL）

本部分概述了通过 modern 方法配置连接到 NoSQL Azure Cosmos DB 的步骤。

配置控制平面角色分配

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

有关详细信息，请参阅在 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-000000000001"
$scope=$(az cosmosdb show --name $cosmosdb_acc_name --resource-group $resource_group --query id --output tsv)

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

az cosmosdb sql role assignment create --account-name $cosmosdb_acc_name --resource-group $resource_group --role-definition-id $readOnlyRoleDefinitionId --principal-id $system_assigned_principal --scope $scope

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

配置数据源定义

在 Azure Cosmos DB for NoSQL 帐户中配置控制平面和数据平面角色分配后，可以设置在该角色下运行的帐户连接。

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

提示

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

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

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

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

这是一个使用创建数据源 REST API来实现现代方法的示例。

POST https://[service name].search.windows.net/datasources?api-version=2026-04-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];IdentityAuthType=AccessToken"
    },
    "container": { "name": "[my-cosmos-collection]" }
}

注意

如果 IdentityAuthType 属性不属于连接字符串，则Azure AI 搜索默认为 legacy 方法以确保向后兼容。

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

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

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

POST https://[service name].search.windows.net/datasources?api-version=2026-04-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];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]" 
    }
}

连接到适用于 Gremlin/MongoDB 的 Azure Cosmos DB（预览版）

本部分概述了通过 legacy 方法配置连接到 Gremlin/Mongo Azure Cosmos DB 的步骤。

配置控制平面角色分配

按照之前的相同步骤，在 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=2026-08-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=2026-08-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]" 
    }
}

运行索引器以验证权限

在索引器执行期间，会在运行时对远程服务的连接信息和权限进行验证。如果索引器成功，则连接语法和角色分配有效。有关详细信息，请参阅 “运行或重置索引器”、“技能”或“文档”。

排查连接问题

对于适用于 NoSQL 的 Azure Cosmos DB，请检查该帐户是否限制访问到特定网络。你可以尝试不受限制地进行连接，以排除任何防火墙问题。有关详细信息，请参阅在索引器中访问受 Azure 网络安全性保护的内容
对于适用于 NoSQL 的 Azure Cosmos DB，如果索引器由于身份验证问题而失败，请确保角色分配已在 Cosmos DB 帐户的控制平面和数据平面上都完成。
对于 Gremlin 或 MongoDB，如果您最近轮换了 Azure Cosmos DB 帐户密钥，则需要等待最多 15 分钟才能使托管标识的连接字符串生效。

另请参阅

反馈

此页面是否有帮助？

Last updated on 2026-07-03

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

先决条件

限制

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

连接到 Azure Cosmos DB（用于 NoSQL）

配置控制平面角色分配

配置数据平面角色分配

配置数据源定义

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

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

连接到适用于 Gremlin/MongoDB 的 Azure Cosmos DB（预览版）

配置控制平面角色分配

设置连接字符串

运行索引器以验证权限

排查连接问题

另请参阅

反馈

其他资源