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

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

  • Статья

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

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

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

Ограничения

Поддержка индексатора Для Azure Cosmos DB для Gremlin и MongoDB Collections сейчас доступна в предварительной версии. В настоящее время для подключения с помощью ключей требуется ограничение предварительной версии. Вы по-прежнему можете настроить управляемое удостоверение и назначение ролей, но поиск ИИ Azure будет использовать только назначение роли для получения ключей для подключения. Это ограничение означает, что вы не можете настроить подход на основе ролей, если индексаторы подключаются к Gremlin или MongoDB.

Создание назначения ролей в Azure Cosmos DB

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

  2. Выберите Управление доступом (IAM).

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

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

  5. Выберите Далее.

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

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

  8. Выберите удостоверение и сохраните назначение роли.

Дополнительные сведения см. в статье Настройка управления доступом на основе ролей с помощью идентификатора Microsoft Entra для учетной записи Azure Cosmos DB.

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

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

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

Совет

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

Управляемое удостоверение, назначаемое системой

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

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

  • Для коллекций SQL строка подключения не требуется ApiKind.
  • Для коллекций SQL добавьте IdentityAuthType=AccessToken, если доступ на основе ролей применяется в качестве единственного метода проверки подлинности. Это не применимо для коллекций MongoDB и Gremlin.
  • Для коллекций MongoDB добавьте ApiKind=MongoDb в строка подключения и используйте REST API предварительной версии.
  • Для графов Gremlin добавьте ApiKind=Gremlin в строка подключения и используйте REST API предварительной версии.

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

POST https://[service name].search.windows.net/datasources?api-version=2024-07-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];ApiKind=SQL;IdentityAuthType=[AccessToken | AccountKey]"
    },
    "container": { "name": "[my-cosmos-collection]", "query": null },
    "dataChangeDetectionPolicy": null

 
}

Управляемое удостоверение, назначаемое пользователем

При подключении к управляемому удостоверению, назначаемого пользователем, существует два изменения определения источника данных:

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

    • Для коллекций SQL строка подключения не требуется ApiKind.
    • Для коллекций SQL добавьте IdentityAuthType=AccessToken, если доступ на основе ролей применяется в качестве единственного метода проверки подлинности. Это не применимо для коллекций MongoDB и Gremlin.
    • Для коллекций MongoDB добавьте "ApiKind=MongoDb" в строка подключения
    • Для графов Gremlin добавьте "ApiKind=Gremlin" в строка подключения.

  • Во-вторых, вы добавляете свойство identity, содержащее коллекцию управляемых удостоверений, назначаемых пользователем. При создании источника данных должно быть предоставлено только одно управляемое удостоверение, назначаемое пользователем. Задайте для него тип userAssignedIdentities.

Ниже приведен пример создания объекта источника данных индексатора с помощью REST API.

POST https://[service name].search.windows.net/datasources?api-version=2024-07-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];ApiKind=SQL;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
}

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

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

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

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

См. также