Настройка подключения индексатора к 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 для NoSQL можно принудительно применить доступ на основе ролей в качестве единственного метода проверки подлинности для подключений к данным, установив disableLocalAuthtrue для учетной записи Cosmos DB доступ.

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

  • Вы должны ознакомиться с понятиями индексатора и конфигурацией.

Создание источника данных

Создайте источник данных и укажите управляемое удостоверение, назначаемое системой, или назначаемое пользователем управляемое удостоверение (предварительная версия) в строка подключения.

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

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 предварительной версии.

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

POST https://[service name].search.windows.net/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

 
}

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

REST API 2021-04-30-preview поддерживает подключения на основе управляемого удостоверения, назначаемого пользователем. При подключении к управляемому удостоверению, назначаемого пользователем, существует два изменения определения источника данных:

  • Во-первых, формат свойства "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=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
}

Создание индекса

Индекс задает поля в документе, атрибуты, и другие компоненты, которые определяют процедуру поиска.

Ниже приведен вызов REST API для создания индекса с полем для booktitle поиска:

POST https://[service name].search.windows.net/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 }
    ]
}

Создание индексатора

Индексатор соединяет источник данных с целевым индексом поиска и предоставляет расписание для автоматизации обновления данных. После создания индекса и источника данных можно создать и запустить индексатор. Если индексатор успешно выполнен, синтаксис подключения и назначения ролей допустимы.

Ниже приведен вызов REST API индексатора с определением индексатора Azure Cosmos DB для NoSQL. Индексатор запускается при отправке запроса.

    POST https://[service name].search.windows.net/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"
    }

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

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

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

См. также