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

Nota

Pesquisa de IA do Azure  está disponível por meio do portal Azure, APIs REST e SDKs do Azure. Ele também sustenta o IQ do Foundry, a camada de conhecimento gerenciado que transforma o conteúdo da empresa em bases de conhecimento reutilizáveis e com reconhecimento de permissão para agentes no portal do Microsoft Foundry.

Este artigo explica como configurar uma conexão de indexador para um banco de dados Azure Cosmos DB usando uma identidade gerenciada em vez de fornecer credenciais no cadeia de conexão."

Você pode usar uma identidade gerenciada atribuída pelo sistema ou uma identidade gerenciada atribuída pelo usuário. As identidades gerenciadas da Microsoft Entra são logins que exigem atribuições de função no Azure para acessar dados no Azure Cosmos DB. Opcionalmente, você pode 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 a conta do Azure Cosmos DB para NoSQL.

Pré-requisitos

Limitações

  • Os indexadores que se conectam a Azure Cosmos DB para Gremlin e MongoDB (atualmente em versão prévia) só dão suporte à abordagem legacy.

Abordagens com suporte para autenticação de identidade gerenciada

Pesquisa de IA do Azure  dá suporte a dois mecanismos para se conectar a Azure Cosmos DB usando identidade gerenciada.

  • A abordagem ultrapassada requer a configuração da identidade gerenciada para ter permissões de leitura no plano de controle da conta de destino do Azure Cosmos DB. Pesquisa de IA do Azure  utiliza essa identidade para buscar as chaves da conta do Cosmos DB em segundo plano para acessar os dados. Essa abordagem não funcionará se a conta do Cosmos DB tiver "disableLocalAuth": true.

  • A abordagem moderna requer a configuração das funções apropriadas de identidade gerenciada no plano de controle e de dados da conta de destino do Azure Cosmos DB. Pesquisa de IA do Azure  solicitará um token de acesso para acessar os dados na conta do Cosmos DB. Essa abordagem funciona mesmo se a conta do Cosmos DB tiver "disableLocalAuth": true.

Os indexadores que se conectam a Azure Cosmos DB para NoSQL dão suporte à abordagem legacy e à abordagem modern - a abordagem modern é recomendada.

Conectar-se ao Azure Cosmos DB para NoSQL

Esta seção descreve as etapas para configurar a conexão com Azure Cosmos DB para NoSQL por meio da abordagem modern.

Configurar atribuições de função do painel de controle

  1. Entre no portal Azure e localize sua conta do Cosmos DB para NoSQL.

  2. Selecione controle de acesso (IAM).

  3. Selecione Adicionar e selecione 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 selecione 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 pesquisa para usar uma identidade gerenciada. Se você já configurou um, mas ele não está disponível, espere alguns minutos.

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

Para mais informações, confira Usar o controle de acesso baseado em função do painel de controle com o Azure Cosmos DB for NoSQL.

Configurar atribuições de função do plano de dados

A identidade gerenciada precisa ter uma função atribuída para ler os dados do plano da conta do Cosmos DB. O ID do Objeto (principal) da identidade atribuída pelo sistema/usuário do serviço de pesquisa pode ser encontrado na guia "Identidade" do serviço de pesquisa. Esta etapa só pode ser executada por meio da CLI do Azure no momento.

Definir variáveis:

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

Defina uma atribuição de função para a identidade atribuída pelo sistema:

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

Para mais informações, confira Usar o controle de acesso baseado em função do plano de dados com o Azure Cosmos DB for NoSQL

Configurar a definição da fonte de dados

Depois de configurar ambas as atribuições de função do painel de controle e do plano de dados na conta do Azure Cosmos DB for NoSQL, você pode configurar uma conexão com ela 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 string de conexão de fonte de dados. Você pode encontrar mais exemplos de cadeia de conexão no artigo de identidade gerenciada.

Dica

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

A API REST, o portal do Azure e o .NET SDK suportam o uso de uma identidade gerenciada atribuída pelo sistema ou atribuída pelo usuário.

Conectar-se por meio da identidade atribuída pelo sistema

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

Aqui está um exemplo usando a API REST criar fonte de dados que exerce a abordagem moderna .

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

Nota

Se a propriedade IdentityAuthType não fizer parte da cadeia de conexão, então o Pesquisa de IA do Azure  adota a abordagem antiga para garantir a compatibilidade com versões anteriores.

Conectar-se por meio da identidade atribuída pelo usuário

Você precisa adicionar uma propriedade de "identidade" à definição da fonte de dados, em que você especifica a identidade específica (de várias que podem ser atribuídas ao serviço de pesquisa), que será usada para se conectar à conta Azure Cosmos DB.

Veja um exemplo usando a identidade atribuída pelo usuário por meio da abordagem moderna .

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

Conectar-se ao Azure Cosmos DB para Gremlin/MongoDB (versão prévia)

Esta seção descreve as etapas para configurar a conexão ao Azure Cosmos DB para Gremlin/Mongo por meio da abordagem legacy.

Configurar atribuições de função do painel de controle

Siga as mesmas etapas de antes para atribuir as funções apropriadas no plano de controle do Azure Cosmos DB para Gremlin/MongoDB.

Definir a string de conexão

  • Para coleções do MongoDB, adicione "ApiKind=MongoDb" ao cadeia de conexão e use uma API REST de visualização.
  • Para grafos do Gremlin, adicione "ApiKind=Gremlin" ao cadeia de conexão e use uma API REST de visualização.
  • Para qualquer um dos tipos, há suporte apenas para a abordagem herdada, ou seja, IdentityAuthType=AccountKey ou omiti-la inteiramente é a única cadeia de conexão válida.

Veja um exemplo para se conectar às coleções do MongoDB usando a identidade atribuída pelo sistema por meio da API REST

POST https://[service name].search.windows.net/datasources?api-version=2026-05-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
}

Veja um exemplo para se conectar aos grafos do Gremlin usando a identidade atribuída pelo usuário.

POST https://[service name].search.windows.net/datasources?api-version=2026-05-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]" 
    }
}

Executar o indexador para verificar permissões

As informações de conexão e as permissões no serviço remoto são validadas em 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.

Solucionar problemas de conexões

  • Para Azure Cosmos DB para NoSQL, verifique se a conta tem seu acesso restrito a redes selecionadas. Você pode descartar quaisquer problemas de firewall tentando a conexão sem restrições em vigor. Consulte acesso do Indexer ao conteúdo protegido pela segurança de rede do Azure para obter mais informações

  • Para Azure Cosmos DB para NoSQL, se o indexador falhar devido a problemas de autenticação, verifique se as atribuições de função foram feitas both no plano de controle e no plano de dados da conta do Cosmos DB.

  • Para o Gremlin ou MongoDB, se você rotacionou recentemente suas chaves de conta do Azure Cosmos DB, precisará aguardar por até 15 minutos para que a string de conexão de identidade gerenciada funcione.

Consulte também

  • Last updated on