Подключение к базе данных Azure Cosmos с использованием управляемой идентичности (Поиск в Azure AI)

2025-01-14

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

Вы можете использовать управляемое удостоверение, назначаемое системой, или управляемое удостоверение, назначаемое пользователем. Управляемые удостоверения представляют собой учетные записи Microsoft Entra и требуют присвоения ролей Azure для получения доступа к данным в Azure Cosmos DB. При необходимости можно принудительно применить доступ на основе ролей в качестве единственного метода проверки подлинности для подключений к данным, установив disableLocalAuthtrue для учетной записи 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. Идентификатор объекта (principal 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 для 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 с использованием управляемой идентичности (Поиск в Azure AI)

Предварительные условия

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

Ограничения

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

Конфигурация назначений ролей плоскости управления

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

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

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

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

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

Конфигурация назначений ролей плоскости управления

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

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

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

См. также

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

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