通过托管标识设置到 Azure Cosmos DB 的索引器连接

  • 项目

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

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

先决条件

$cosmosdb_acc_name = <cosmos db account name>
$resource_group = <resource group name>
$subsciption = <subscription id>
$system_assigned_principal = <principal id for system assigned identity>
$readOnlyRoleDefinitionId = "00000000-0000-0000-0000-000000000001"
$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

  • 对于 Cosmos DB for NoSQL，可以选择通过将 Cosmos DB 帐户的 disableLocalAuth 设置为 true，强制将基于角色的访问作为数据连接的唯一身份验证方法。

  • 对于 Gremlin 和 MongoDB 集合：索引器支持目前为预览版。 目前，存在预览限制，要求 Azure AI 搜索使用按密钥进行连接。 你仍然可以设置托管标识和角色分配，但 Azure AI 搜索将仅使用角色分配来获取用于连接的密钥。 此限制意味着，如果索引器使用具有托管标识的搜索连接到 Gremlin 或 MongoDB 以连接到 Azure Cosmos DB，则无法配置基于角色的方法。

  • 你应熟悉索引器概念和配置。

创建数据源

创建数据源并在连接字符串中提供系统分配的托管标识或用户分配的托管标识（预览版）。

系统分配的托管标识

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 和托管标识连接字符串创建数据源以索引存储帐户的数据。 对于 REST API、.NET SDK 和 Azure 门户，托管标识连接字符串格式是相同的。

POST https://[service name].search.azure.cn/datasources?api-version=2020-06-30
Content-Type: application/json
api-key: [Search service admin key]

{
    "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 | Gremlin | MongoDB];IdentityAuthType=[AccessToken | AccountKey]"
    },
    "container": { "name": "[my-cosmos-collection]", "query": null },
    "dataChangeDetectionPolicy": null

}

用户分配的托管标识（预览版）

2021-04-30-preview REST API 支持基于用户分配的托管标识的连接。 使用用户分配的托管标识进行连接时，对数据源定义进行了两项更改：

  • 首先，“凭据”属性的格式是数据库名称，以及一个没有帐户密钥或密码的 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=2021-04-30-preview
Content-Type: application/json
api-key: [Search service admin key]

{
    "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 | Gremlin | MongoDB];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
}

创建索引

索引指定文档、属性和其他构造中可以塑造搜索体验的字段。

下面是一个带有可搜索的 booktitle 字段的创建索引 REST API 调用：

POST https://[service name].search.azure.cn/indexes?api-version=2020-06-30
Content-Type: application/json
api-key: [admin key]

{
    "name" : "my-target-index",
    "fields": [
    { "name": "id", "type": "Edm.String", "key": true, "searchable": false },
    { "name": "booktitle", "type": "Edm.String", "searchable": true, "filterable": false, "sortable": false, "facetable": false }
    ]
}

创建索引器

索引器将数据源与目标搜索索引关联，并提供自动执行数据刷新的计划。 创建索引和数据源后，就可以创建和运行索引器。 如果索引器成功，则表明连接语法和角色分配有效。

下面是一个带有 Azure Cosmos DB 索引器定义的创建索引器 REST API 调用。 提交请求时，索引器将开始运行。

    POST https://[service name].search.azure.cn/indexers?api-version=2020-06-30
    Content-Type: application/json
    api-key: [admin key]

    {
      "name" : "cosmos-db-indexer",
      "dataSourceName" : "cosmos-db-datasource",
      "targetIndexName" : "my-target-index"
    }

故障排除

如果最近轮换了 Cosmos DB 帐户密钥，则需要等待 15 分钟，以便托管标识连接字符串正常工作。

查看 Azure Cosmos DB 帐户的访问权限是否只限于选择网络。 你可以通过在未设置限制的情况下尝试连接来排除任何防火墙问题。

另请参阅