Conectar-se ao Azure Cosmos DB usando uma identidade gerenciada (Azure AI Search)

  • 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 ao sistema ou uma 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 visualização. No momento, uma limitação de visualização 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.

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

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

  2. Selecione Controlo de acesso (IAM) .

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

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

  5. Selecione Seguinte.

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

  7. Filtre por identidades gerenciadas atribuídas pelo sistema ou identidades gerenciadas atribuídas pelo usuário. Deverá ver a identidade gerida que criou anteriormente para o 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, dê-lhe 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 para 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 cadeia de conexão no artigo de identidade gerenciada.

Gorjeta

Você pode criar uma conexão de fonte de dados com o CosmosDB no portal do 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 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". Forneça um nome de banco de dados e um ResourceId que não tenha 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 do Cosmos DB usando a API REST Create Data Source 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=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 gerida atribuída pelo utilizador

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.

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 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 da 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.

Resolução de Problemas

Para o 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.

Para Gremlin ou MongoDB, 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.

Consulte também