Share via

Configurar uma conexão de indexador com o Azure Cosmos DB por meio de uma identidade gerenciada

  • Artigo

Este artigo explica como configurar uma conexão de indexador com um banco de dados do Azure Cosmos DB usando uma identidade gerenciada em vez de fornecer credenciais na cadeia de conexão.'

Você pode usar uma identidade gerenciada atribuída pelo sistema ou uma identidade gerenciada atribuída pelo usuário (visualização). As identidades gerenciadas são logons do Microsoft Entra e exigem atribuições de função do Azure para acessar dados no Azure Cosmos DB.

Pré-requisitos

  • Crie uma identidade gerenciada para seu serviço de pesquisa.

  • Atribua a função Leitor de Conta do Cosmos DB à identidade gerenciada do serviço de pesquisa. Essa função concede a capacidade de ler dados de conta do Azure Cosmos DB. Para obter mais informações sobre atribuições de função no Cosmos DB, consulte Configurar o controle de acesso baseado em função aos dados.

  • Atribuição de Função do Plano de Dados: Siga a Atribuição de Função do Plano de Dados para saber mais.

  • Exemplo de uma atribuição de função de plano de dados somente leitura:

$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)

Atribuição de função para identidade atribuída pelo sistema:

az cosmosdb sql role assignment create --account-name $cosmosdbname --resource-group $resourcegroup --role-definition-id $readOnlyRoleDefinitionId --principal-id $sys_principal --scope $scope

  • Para o Cosmos DB para NoSQL, você pode, opcionalmente , impor o acesso baseado em função como o único método de autenticação para conexões de dados definindo disableLocalAuth como true para sua conta do Cosmos DB.

  • Para coleções Gremlin e MongoDB: o suporte ao indexador está atualmente em visualização. No momento, existe uma limitação de visualização que exige que o Azure AI Search se conecte usando chaves. Você ainda pode configurar uma identidade gerenciada e uma atribuição de função, mas o Azure AI Search usará apenas a atribuição de função para obter chaves para a conexão. Essa limitação significa que você não pode configurar uma abordagem baseada em função se seus indexadores estiverem se conectando ao Gremlin ou ao MongoDB usando a Pesquisa com identidades gerenciadas para se conectar ao Azure Cosmos DB.

  • Você deve estar familiarizado com os conceitos e a configuração do indexador.

Criar a origem de dados

Crie a fonte de dados e forneça uma identidade gerenciada atribuída pelo sistema ou uma identidade gerenciada atribuída pelo usuário (visualização) na cadeia de conexão.

Identidade gerida atribuída pelo sistema

A API REST, o portal do Azure e o SDK do .NET suportam usando uma identidade gerenciada atribuída ao sistema.

Quando você está se conectando com uma identidade gerenciada atribuída ao sistema, a única alteração na definição da fonte de dados é o formato da propriedade "credenciais". Você fornecerá o nome do banco de dados e um ResourceId que não tem chave de conta ou senha. O ResourceId deve incluir a ID de assinatura do Azure Cosmos DB, o grupo de recursos e o nome da conta do Azure Cosmos DB.

  • Para coleções SQL, a cadeia de conexão não requer "ApiKind".
  • Para coleções SQL, adicione "IdentityAuthType=AccessToken" se o acesso baseado em função for imposto como o único método de autenticação. Não se aplica às coleções MongoDB e Gremlin.
  • Para coleções MongoDB, adicione "ApiKind=MongoDb" à cadeia de conexão e use uma API REST de visualização.
  • Para gráficos Gremlin, adicione "ApiKind=Gremlin" à cadeia de conexão e use uma API REST de visualização.

Veja um exemplo de como criar uma fonte de dados para indexar dados de uma conta de armazenamento usando a API REST Criar Fonte de Dados e uma cadeia de conexão de identidade gerenciada. O formato de cadeia de conexão de identidade gerenciada é o mesmo para a API REST, SDK .NET e o portal do 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

 
}

Identidade gerenciada atribuída pelo usuário (visualização)

A API REST 2021-04-30-preview suporta conexões baseadas em uma identidade gerenciada atribuída pelo usuário. Quando você está se conectando com uma identidade gerenciada atribuída pelo usuário, há duas alterações na definição da fonte de dados:

  • Primeiro, o formato da propriedade "credentials" é o nome do banco de dados e um ResourceId que não tem chave de conta ou senha. O ResourceId deve incluir a ID de assinatura do Azure Cosmos DB, o grupo de recursos e o nome da conta do Azure Cosmos DB.

    • Para coleções SQL, a cadeia de conexão não requer "ApiKind".
    • Para coleções SQL, adicione "IdentityAuthType=AccessToken" se o acesso baseado em função for imposto como o único método de autenticação. Não se aplica às coleções MongoDB e Gremlin.
    • Para coleções MongoDB, adicione "ApiKind=MongoDb" à cadeia de conexão
    • Para gráficos Gremlin, adicione "ApiKind=Gremlin" à cadeia de conexão.

  • Em segundo lugar, você adiciona uma propriedade "identity" que contém a coleção de identidades gerenciadas atribuídas pelo usuário. Apenas uma identidade gerenciada atribuída pelo usuário deve ser fornecida ao criar a fonte de dados. Defina-o para digitar "userAssignedIdentities".

Veja um exemplo de como criar um objeto de fonte de dados indexador usando a API REST de visualização Criar ou Atualizar Fonte de Dados:

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
}

Criar o índice

O índice especifica os campos em um documento, atributos e outras construções que moldam a experiência de pesquisa.

Aqui está uma chamada da API REST Create Index com um campo pesquisável 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 }
    ]
}

Criar o indexador

Um indexador conecta uma fonte de dados a um índice de pesquisa de destino e fornece uma programação para automatizar a atualização de dados. Depois que o índice e a fonte de dados forem criados, você estará pronto para criar e executar o indexador. Se o indexador for bem-sucedido, a sintaxe da conexão e as atribuições de função serão válidas.

Aqui está uma chamada de API REST do Indexador Criar com uma definição de indexador do Azure Cosmos DB para NoSQL. O indexador é executado quando você envia a solicitação.

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

Resolução de Problemas

Se você girou recentemente suas chaves de conta do Azure Cosmos DB, precisará aguardar até 15 minutos para que a cadeia de conexão de identidade gerenciada funcione.

Verifique se a conta do Azure Cosmos DB tem seu acesso restrito a redes selecionadas. Você pode descartar quaisquer problemas de firewall tentando a conexão sem restrições em vigor.

Consulte também