Подключение к Azure Cosmos DB с помощью управляемого удостоверения (поиск в Azure AI)

Статья
01/14/2025

В этой статье объясняется, как настроить подключение индексатора к базе данных Azure Cosmos DB с помощью управляемого удостоверения вместо предоставления учетных данных в строка подключения.

Вы можете использовать управляемое удостоверение, назначаемое системой, или управляемое удостоверение, назначаемое пользователем. Управляемые удостоверения — это имена входа Microsoft Entra и требуют назначения ролей Azure для доступа к данным в Azure Cosmos DB. При необходимости можно принудительно применить доступ на основе ролей в качестве единственного метода проверки подлинности для подключений к данным, установив disableLocalAuth true для учетной записи Azure Cosmos DB для NoSQL.

Необходимые компоненты

Создайте управляемое удостоверение для службы поиска.

Поддерживаемые подходы для проверки подлинности управляемых удостоверений

Поиск ИИ Azure поддерживает два механизма подключения к Azure Cosmos DB с помощью управляемого удостоверения.

Устаревший подход требует настройки управляемого удостоверения, чтобы иметь разрешения на читатель в плоскости управления целевой учетной записи Azure Cosmos DB. Поиск azure AI использует это удостоверение для получения ключей учетной записи Cosmos DB в фоновом режиме для доступа к данным. Этот подход не будет работать, если у учетной записи Cosmos DB есть "disableLocalAuth": true.
Современный подход требует настройки соответствующих ролей управляемого удостоверения на уровне управления и плоскости данных целевой учетной записи Azure Cosmos DB. Затем служба "Поиск ИИ Azure" запрашивает маркер доступа для доступа к данным в учетной записи Cosmos DB. Этот подход работает даже в том случае, если у учетной записи Cosmos DB."disableLocalAuth": true

Индексаторы, подключающиеся к Azure Cosmos DB для NoSQL, поддерживают как устаревший, так и современный подход. Современный подход настоятельно рекомендуется.

Ограничения

Индексаторы, подключающиеся к Azure Cosmos DB для Gremlin и MongoDB (в настоящее время в предварительной версии), поддерживают только устаревший подход.

Подключение к Azure Cosmos DB для NoSQL

В этом разделе описаны шаги по настройке подключения к Azure Cosmos DB для NoSQL с помощью современного подхода.

Настройка назначений ролей уровня управления

Войдите в портал Azure и найдите учетную запись Cosmos DB для NoSQL.
Выберите Управление доступом (IAM).
Выберите " Добавить " и выберите "Назначение роли".
В списке ролей функции задания выберите средство чтения учетной записи Cosmos DB.
Выберите Далее.
Выберите управляемое удостоверение и выберите "Участники".
Фильтрация по управляемым удостоверениям, назначенным системой, или управляемым удостоверениям, назначаемым пользователем. Вы увидите управляемое удостоверение, созданное ранее для службы поиска. Если у вас нет его, см. статью "Настройка поиска для использования управляемого удостоверения". Если вы уже настроили его, но он недоступен, дайте ему несколько минут.
Выберите удостоверение и сохраните назначение роли.

Дополнительные сведения см. в статье Об управлении доступом на основе ролей на основе ролей в Azure Cosmos DB для NoSQL.

Настройка назначений ролей плоскости данных

Управляемое удостоверение должно назначить роль для чтения из плоскости данных учетной записи Cosmos DB. Идентификатор объекта (субъекта) для назначенного системой или пользователем удостоверения службы поиска можно найти на вкладке "Удостоверение" службы поиска. Этот шаг можно выполнить только с помощью 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 для NoSQL

Настройка определения источника данных

После настройки назначений ролей уровня управления и плоскости данных в учетной записи Azure Cosmos DB для NoSQL можно настроить подключение к нему, которое работает под этой ролью.

Индексаторы используют объект источника данных для подключений к внешнему источнику данных. В этом разделе объясняется, как указать управляемое удостоверение, назначаемое системой, или управляемое удостоверение, назначаемое пользователем, в строка подключения источника данных. Дополнительные строка подключения примеры см. в статье об управляемом удостоверении.

Совет

Вы можете создать подключение к источнику данных к Cosmos DB в портал Azure, указав управляемое удостоверение, назначаемое системой или пользователем, а затем просмотреть определение JSON, чтобы узнать, как создается строка подключения.

REST API, портал Azure и пакет SDK для .NET поддерживаются с помощью управляемого удостоверения, назначаемого системой или назначаемого пользователем.

Подключение через назначаемое системой удостоверение

При подключении к управляемому удостоверению, назначаемого системой, единственное изменение определения источника данных — это формат свойства credentials. Укажите имя базы данных и Идентификатор ресурса, не имеющий ключа учетной записи или пароля. ResourceId должен содержать идентификатор подписки Azure Cosmos DB, группу ресурсов и имя учетной записи Azure Cosmos DB.

Ниже приведен пример использования REST 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 для Gremlin/MongoDB (предварительная версия)

В этом разделе описаны шаги по настройке подключения к Azure Cosmos DB для Gremlin/Mongo с помощью устаревшего подхода.

Настройка назначений ролей уровня управления

Выполните те же действия, что и ранее, чтобы назначить соответствующие роли на уровне управления Azure Cosmos DB для Gremlin/MongoDB.

Задание строки подключения

Для коллекций MongoDB добавьте ApiKind=MongoDb в строка подключения и используйте REST API предварительной версии.
Для графов Gremlin добавьте ApiKind=Gremlin в строка подключения и используйте REST API предварительной версии.
Для любого типа поддерживается только устаревший подход, тIdentityAuthType=AccountKey. е. опущение полностью является единственным допустимым строка подключения.

Ниже приведен пример подключения к коллекциям MongoDB с помощью назначаемого системой удостоверения с помощью REST 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];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 для NoSQL проверьте, ограничена ли учетная запись доступом для выбора сетей. Вы можете исключить любые проблемы брандмауэра, пытаясь подключиться без ограничений. Дополнительные сведения см. в статье " Индексатор доступа к содержимому, защищенному сетевой безопасностью Azure"
Если индексатор Azure Cosmos DB для NoSQL завершается ошибкой из-за проблем с проверкой подлинности, убедитесь, что назначения ролей были выполнены как на уровне управления, так и в плоскости данных учетной записи Cosmos DB.
Для Gremlin или MongoDB, если вы недавно повернете ключи учетной записи Azure Cosmos DB, необходимо дождаться до 15 минут, пока управляемое удостоверение строка подключения работать.

Поделиться через

Подключение к Azure Cosmos DB с помощью управляемого удостоверения (поиск в Azure AI)

Необходимые компоненты

Поддерживаемые подходы для проверки подлинности управляемых удостоверений

Ограничения

Подключение к Azure Cosmos DB для NoSQL

Настройка назначений ролей уровня управления

Настройка назначений ролей плоскости данных

Настройка определения источника данных

Подключение через назначаемое системой удостоверение

Подключение через назначаемое пользователем удостоверение

Подключение к Azure Cosmos DB для Gremlin/MongoDB (предварительная версия)

Настройка назначений ролей уровня управления

Задание строки подключения

Запустите индексатор для проверки разрешений

Устранение неполадок подключений

См. также

Обратная связь

Дополнительные ресурсы