Conectar-se ao Azure Cosmos DB usando uma identidade gerenciada (Pesquisa de IA do Azure)

  • 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 colocar as credenciais na cadeia de conexão.

Você pode usar a identidade gerenciada atribuída pelo sistema ou a identidade gerenciada atribuída pelo usuário. 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

Limitações

O suporte do indexador para o Azure Cosmos DB para Coleções Gremlin e MongoDB está atualmente em versão prévia. No momento, uma limitação de visualização exige que a Pesquisa de IA do Azure 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.

Criar uma atribuição de função no Azure Cosmos DB

  1. Entre no portal do Microsoft Azure e encontre sua conta do Cosmos DB for NoSQL.

  2. Selecione IAM (Controle de acesso) .

  3. Selecione Adicionar e, em seguida, Atribuição de função.

  4. Na lista de funções de trabalho, selecione Leitor de Conta do Cosmos DB.

  5. Selecione Avançar.

  6. Selecione Identidade gerenciada e, em seguida, Membros.

  7. Filtrar por identidades gerenciadas atribuídas pelo sistema ou identidades gerenciadas atribuídas pelo usuário. Você deve ver a identidade gerenciada que você criou anteriormente para seu serviço de pesquisa. Se você não tiver uma, consulte Configurar a busca para usar uma identidade gerenciada. Se você já configurou uma, mas ela não está disponível, aguarde alguns minutos.

  8. Selecione a identidade e salve a atribuição de função.

Para obter mais informações, consulte Configurar o controle de acesso baseado em função com a ID do Microsoft Entra para sua conta do Azure Cosmos DB.

Especificar uma identidade gerenciada em uma cadeia de conexão

Depois de ter uma atribuição de função, você pode configurar uma conexão com o Azure Cosmos DB for NoSQL que opera sob essa função.

Os indexadores usam um objeto de fonte de dados para conexões com uma fonte de dados externa. Esta seção explica como especificar uma identidade gerenciada atribuída pelo sistema ou uma identidade gerenciada atribuída pelo usuário em uma cadeia de conexão de fonte de dados. Você pode encontrar mais exemplos de cadeias de conexão no artigo sobre identidade gerenciada.

Dica

Você pode criar uma conexão de fonte de dados com o CosmosDB no portal do Microsoft Azure, especificando uma identidade gerenciada atribuída pelo sistema ou pelo usuário e, em seguida, exibir a definição JSON para ver como a cadeia de conexão é formulada.

Identidade gerenciada atribuída pelo sistema

A API REST, o portal do Azure e o SDK do .NET dão suporte ao uso de uma identidade gerenciada atribuída pelo sistema.

Quando você está se conectando com uma identidade gerenciada atribuída pelo sistema, a única alteração na definição da fonte de dados é o formato da propriedade "credentials". Forneça um nome de banco de dados e uma ResourceId que não tenha nenhuma chave de conta ou senha. A ResourceId precisa incluir a ID da 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 um “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 é aplicável às coleções MongoDB e Gremlin.
  • Para coleções do MongoDB, adicione “ApiKind=MongoDb” à cadeia de conexão e usa uma API REST de visualização.
  • Para grafos do Gremlin, adicione "ApiKind = Gremlin" à cadeia de conexão e use uma API REST de visualização.

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

 
}

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 uma ResourceId que não tenha uma chave de conta ou senha. A ResourceId precisa incluir a ID da 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 um “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 é aplicável às coleções MongoDB e Gremlin.
    • Para coleções do MongoDB, adicione “ApiKind=MongoDb” à cadeia de conexão
    • Para grafos do Gremlin, adicione "ApiKind = Gremlin" à cadeia de conexão.

  • Em segundo lugar, você adiciona uma propriedade “identity” que contenha a coleção de identidades gerenciadas atribuídas pelo usuário. Somente uma identidade gerenciada atribuída pelo usuário deve ser fornecida ao criar a fonte de dados. Defina-a com o tipo "userAssignedIdentities".

Aqui está um exemplo de como criar um objeto de fonte de dados de indexador usando a API REST.

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
}

As informações da conexão e as permissões no serviço remoto são validadas no tempo de execução durante a execução do indexador. Se o indexador for bem-sucedido, a sintaxe de conexão e as atribuições de função serão válidas. Para obter mais informações, consulte Executar ou redefinir indexadores, habilidades ou documentos.

Solução de problemas

Para o Azure Cosmos DB for NoSQL, verifique se a conta tem seu acesso restrito a redes selecionadas. Você pode eliminar qualquer problema de firewall experimentando a conexão sem restrições em vigor.

Para Gremlin ou MongoDB, se você rotacionou recentemente as chaves da sua conta do Azure Cosmos DB, será necessário aguardar até 15 minutos para que a cadeia de conexão de identidade gerenciada funcione.

Confira também