Ligue-se ao Azure Cosmos DB usando uma identidade gerida (Pesquisa de IA do Azure)

Este artigo explica como configurar uma ligação indexadora a uma base de dados Azure Cosmos DB usando uma identidade gerida em vez de fornecer credenciais na cadeia de ligação.'

Pode usar uma identidade gerida atribuída pelo sistema ou uma identidade gerida atribuída pelo utilizador. As identidades geridas são logins Microsoft Entra e requerem atribuições de funções no Azure para aceder a dados no Azure Cosmos DB. Podes opcionalmente impor acesso baseado em funções como único método de autenticação para ligações de dados, definindo disableLocalAuth para true para a tua Azure Cosmos DB para NoSQL conta.

Pré-requisitos

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

Limitações

• Indexadores que conectam-se a Azure Cosmos DB para Gremlin e MongoDB (atualmente em pré-visualização) suportam apenas a abordagem legacy.

Abordagens suportadas para autenticação de identidade gerida

O Pesquisa de IA do Azure suporta dois mecanismos para se ligar ao Azure Cosmos DB usando a identidade gerida.

• A abordagem legacy requer configurar a identidade gerida para ter permissões de leitura no plano de controlo da conta de Azure Cosmos DB alvo. O Pesquisa de IA do Azure utiliza essa identidade para obter as chaves da conta do Cosmos DB em segundo plano para aceder aos dados. Esta abordagem não funcionará se a conta de base de dados do Cosmos tiver "disableLocalAuth": true.

• A abordagem moderna requer a configuração das funções apropriadas à identidade gerida no plano de controlo e no plano de dados da conta alvo do Azure Cosmos DB. O Pesquisa de IA do Azure irá então solicitar um token de acesso para aceder aos dados na conta do Cosmos DB. Esta abordagem funciona mesmo que a conta do Cosmos DB tenha "disableLocalAuth": true.

Indexadores que se ligam a Azure Cosmos DB para NoSQL suportam tanto a abordagem legacy como a abordagem modern – recomenda-se a abordagem moderna.

Liga-te ao Azure Cosmos DB para NoSQL

Esta secção descreve os passos para configurar a ligação ao Azure Cosmos DB para NoSQL através da abordagem moderna.

Configurar atribuições de funções no plano de controlo

1. Inicie sessão no portal do Azure e encontre a sua conta Cosmos DB para NoSQL.

2. Selecionar controlo de acesso (IAM).

3. Selecione Adicionar e depois selecione Atribuição de Funções.

4. Da lista de funções, selecione Cosmos DB Account Reader.

5. Selecionar Próximo.

6. Selecione Identidade gerida e depois selecione Membros.

7. Filtre por identidades geridas atribuídas pelo sistema ou por identidades geridas atribuídas pelo utilizador. Deve ver a identidade gerida que criou anteriormente para o seu serviço de pesquisa. Se não tiveres uma, vê Configurar pesquisa para usar uma identidade gerida. Se já configuraste um mas não está disponível, espera alguns minutos.

8. Selecione a identidade e guarde a atribuição de funções.

Para mais informações, veja Use o plano de controlo de acesso baseado em funções com Azure Cosmos DB para NoSQL.

Configurar atribuições de papéis no plano de dados

A identidade gerida deve ter uma função atribuída para leitura no plano de dados da conta Cosmos DB. O ID do Objeto (principal) para a identidade atribuída ao sistema/utilizador do serviço de pesquisa pode ser encontrado no separador "Identidade" do serviço de pesquisa. Este passo só pode ser realizado através do CLI do Azure neste momento.

Variáveis de conjunto:

$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 papel 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, consulte Utilizar o controlo de acesso baseado em funções no plano de dados com o Azure Cosmos DB para NoSQL

Configurar a definição da fonte de dados

Depois de configurares as atribuições de funções em ambos os planos de controlo e de dados na conta do Azure Cosmos DB para NoSQL, podes estabelecer uma ligação que opere sob essas funções atribuídas.

Os indexadores utilizam um objeto fonte de dados para ligações a uma fonte de dados externa. Esta secção explica como especificar uma identidade gerida atribuída pelo sistema ou uma identidade gerida atribuída pelo utilizador numa cadeia de ligação de fonte de dados. Pode encontrar mais exemplos cadeia de ligação no artigo sobre identidade gerida.

A API REST, o portal Azure e o SDK .NET suportam uma identidade gerida atribuída pelo sistema ou pelo utilizador.

Liga-te através da identidade atribuída ao sistema

Quando se conecta a uma identidade gerida 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 base de dados e um ResourceID que não tenha chave de conta nem palavra-passe. O ResourceId deve incluir o ID de subscrição do Azure Cosmos DB, o grupo de recursos e o nome da conta do Azure Cosmos DB.

Aqui está um exemplo usando a API Create Data Source REST que adota 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]" }
}

Liga-te através da identidade atribuída pelo utilizador

Precisa de adicionar uma propriedade de "identidade" à definição da fonte de dados, onde especifica a identidade específica (entre várias que podem ser atribuídas ao serviço de pesquisa), que será usada para se ligar à conta do Azure Cosmos DB.

Aqui está um exemplo usando identidade atribuída pelo utilizador através 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 ao Azure Cosmos DB para Gremlin/MongoDB (versão preliminar)

Esta secção descreve os passos para configurar a ligação a Azure Cosmos DB para Gremlin/Mongo através da abordagem legacy.

Configurar atribuições de funções no plano de controlo

Siga os mesmos passos de antes para atribuir os papéis apropriados no plano de controlo do Azure Cosmos DB para Gremlin/MongoDB.

Definir a "cadeia de ligação"

• Para coleções MongoDB, adicione "ApiKind=MongoDb" à cadeia de ligação e use uma API REST de pré-visualização.
• Para grafos Gremlin, adicione "ApiKind=Gremlin" à cadeia de ligação e use uma API REST de pré-visualização.
• Para qualquer dos tipos, apenas a abordagem legacy é suportada – ou seja, IdentityAuthType=AccountKey ou omiti-la completamente, é a única cadeia de conexão válida.

Aqui está um exemplo para ligar a coleções MongoDB usando identidade atribuída ao sistema através da API REST

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

Aqui está um exemplo para ligar grafos Gremlin usando identidade atribuída pelo utilizador.

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

Execute o indexador para verificar permissões

A informação de ligaçã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 ligação e as atribuições de papéis são válidas. Para mais informações, consulte Executar ou redefinir indexadores, competências ou documentos.

Resolução de problemas de conexão

• Para Azure Cosmos DB para NoSQL, verifique se a conta tem acesso restrito a redes selecionadas. Podes descartar qualquer problema de firewall tentando a ligação sem restrições. Consulte o acesso do Indexador a conteúdos protegidos por segurança de rede Azure para mais informações

• Para Azure Cosmos DB para NoSQL, se o indexador falhar devido a problemas de autenticação, certifique-se de que as atribuições de papéis foram feitas ambos no plano de controlo e no plano de dados da conta Cosmos DB.

• Para o Gremlin ou MongoDB, se recentemente alterou as chaves da sua conta do Azure Cosmos DB, deverá aguardar até 15 minutos para que a cadeia de conexão de identidade gerida funcione.

Ver também

• Indexação via o Azure Cosmos DB para NoSQL
• Indexação através de um Azure Cosmos DB for MongoDB (pré-visualização)
• Indexação através do Azure Cosmos DB for Apache Gremlin (pré-visualização)