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

Примечание

Поиск с использованием ИИ Azure доступна через портал Azure, REST API и Azure SDKs. Он также лежит в основе Foundry IQ — управляемого слоя знаний, который преобразует корпоративный контент в многократно используемые базы знаний с учетом разрешений доступа для агентов на портале Microsoft Foundry.

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

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

Необходимые условия

Ограничения

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

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

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

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

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

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

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

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

Настройка назначений ролей контрольной плоскости

  1. Войдите на портал Azure и найдите учетную запись Cosmos DB для NoSQL.

  2. Выберите диспетчер доступа (IAM).

  3. Выберите "Добавить " и выберите "Назначение роли".

  4. Из списка ролей функций работы выберите чтец учетной записи Cosmos DB.

  5. Нажмите кнопку "Далее".

  6. Выберите Управляемая идентичность и выберите Участники.

  7. Фильтрация по управляемым удостоверениям, назначенным системой, или управляемым удостоверениям, назначаемым пользователем. Вы увидите управляемое удостоверение, созданное ранее для службы поиска. Если у вас нет одного, ознакомьтесь с "Настройка поиска для использования управляемого удостоверения". Если вы уже настроили его, но он недоступен, подождите несколько минут.

  8. Выберите идентификацию и сохраните назначение роли.

Дополнительные сведения см. в разделе Управление доступом на уровне контрольной плоскости на основе ролей с помощью 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-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, чтобы узнать, как формируется строка подключения.

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

Подключение с использованием идентификации, назначенной системой

При подключении к управляемому удостоверению, назначенному системой, единственное изменение определения источника данных — это формат свойства учетных данных (credentials). Укажите имя базы данных и Идентификатор ресурса, не имеющий ключа учетной записи или пароля. ResourceId должен содержать идентификатор подписки Azure Cosmos DB, группу ресурсов и имя учетной записи 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 по умолчанию используется метод legacy для обеспечения обратной совместимости.

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

Вам нужно добавить свойство "identity" в определение источника данных, где следует указать конкретное удостоверение (из нескольких, назначаемых поисковому сервису), которое будет использоваться для подключения к учетной записи 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]" 
    }
}

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

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

Настройка назначений ролей контрольной плоскости

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

Установите строку подключения

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

Ниже приведен пример подключения к коллекциям MongoDB с помощью назначаемого системой удостоверения с помощью REST API

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]" 
    }
}

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

Сведения о подключении и разрешения удаленной службы проверяются во время выполнения индексатора. Если индексатор успешно выполнен, синтаксис подключения и назначения ролей допустимы. Дополнительные сведения см. в разделе "Запуск или сброс индексаторов", "Навыки" или "Документы".

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

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

  • Для Azure Cosmos DB для NoSQL, если индексатор завершается ошибкой из-за проблем с проверкой подлинности, убедитесь, что назначения ролей были выполнены как на плоскости управления, так и на плоскости данных учетной записи Cosmos DB.

  • Для Gremlin или MongoDB, если вы недавно сменили ключи учетной записи Azure Cosmos DB, необходимо дождаться до 15 минут, чтобы строка подключения управляемого удостоверения начала работать.

См. также

  • Last updated on