Partilhar via


Integrar o Azure Cosmos DB para MongoDB com o Service Connector

Esta página mostra os métodos de autenticação e os clientes suportados e mostra o código de exemplo que pode utilizar para ligar o Azure Cosmos DB para MongoDB a outros serviços na nuvem utilizando o Service Connector. Talvez você ainda consiga se conectar ao Azure Cosmos DB para MongoDB em outras linguagens de programação sem usar o Service Connector. Esta página também mostra nomes e valores de variáveis de ambiente padrão (ou configuração do Spring Boot) que você obtém quando cria a conexão de serviço.

Serviços de computação suportados

O Service Connector pode ser usado para conectar os seguintes serviços de computação ao Azure Cosmos DB para MongoDB:

  • Serviço de Aplicações do Azure
  • Azure Container Apps
  • Funções do Azure
  • Azure Kubernetes Service (AKS)
  • Azure Spring Apps

Tipos de autenticação e tipos de cliente suportados

A tabela abaixo mostra quais combinações de tipos de cliente e métodos de autenticação são suportadas para conectar seu serviço de computação ao Azure Cosmos DB para MongoDB usando o Service Connector. Um "Sim" indica que a combinação é suportada, enquanto um "Não" indica que ela não é suportada.

Tipo de cliente Identidade gerida atribuída pelo sistema Identidade gerida atribuída pelo utilizador Segredo / cadeia de conexão Principal de serviço
.NET Sim Sim Sim Sim
Java Sim Sim Sim Sim
Java - Spring Boot Não Não Sim Não
Node.js Sim Sim Sim Sim
Python Sim Sim Sim Sim
Vai Sim Sim Sim Sim
Nenhuma Sim Sim Sim Sim

Esta tabela indica que todas as combinações de tipos de cliente e métodos de autenticação na tabela são suportadas, exceto para o tipo de cliente Java - Spring Boot, que suporta apenas o método Secret / connection string. Todos os outros tipos de cliente podem usar qualquer um dos métodos de autenticação para se conectar ao Azure Cosmos DB para MongoDB usando o Service Connector.

Observação

O Cosmos DB não suporta nativamente a autenticação por meio de identidade gerenciada. Portanto, o Service Connector usa a identidade gerenciada para recuperar a cadeia de conexão, e a conexão é subsequentemente estabelecida usando essa cadeia de conexão.

Nomes de variáveis de ambiente padrão ou propriedades de aplicativo e código de exemplo

Use os detalhes de conexão abaixo para conectar serviços de computação ao Azure Cosmos DB. Esta página também mostra nomes e valores de variáveis de ambiente padrão (ou configuração do Spring Boot) que você obtém quando cria a conexão de serviço, bem como código de exemplo. Para cada exemplo abaixo, substitua os textos de espaço reservado <mongo-db-admin-user>, <password>, <Azure-Cosmos-DB-API-for-MongoDB-account>, <subscription-ID>, <resource-group-name>, <client-secret> e <tenant-id> com as suas próprias informações. Para obter mais informações sobre convenções de nomenclatura, consulte o artigo interno do Service Connector.

Identidade gerida atribuída pelo sistema

Nome da variável de ambiente padrão Descrição Valor de exemplo
AZURE_COSMOS_LISTCONNECTIONSTRINGURL A URL para obter a string de conexão https://management.azure.com/subscriptions/<subscription-ID>/resourceGroups/<resource-group-name>/providers/Microsoft.DocumentDB/databaseAccounts/<Azure-Cosmos-DB-API-for-MongoDB-account>/listConnectionStrings?api-version=2021-04-15
AZURE_COSMOS_SCOPE Seu escopo de identidade gerenciado https://management.azure.com/.default
AZURE_COSMOS_RESOURCEENDPOINT Seu ponto de extremidade de recurso https://<Azure-Cosmos-DB-API-for-MongoDB-account>.documents.azure.com:443/

Código de exemplo

Consulte as etapas e o código abaixo para se conectar ao Azure Cosmos DB para MongoDB usando uma identidade gerenciada atribuída ao sistema.

Como o Cosmos DB não oferece suporte nativo à autenticação por meio de identidade gerenciada, no exemplo de código a seguir, usamos a identidade gerenciada para recuperar a cadeia de conexão, e a conexão é estabelecida usando essa cadeia de conexão.

  1. Instalar dependências

    dotnet add package MongoDb.Driver
    dotnet add package Azure.Identity
    
  2. Obtenha um token de acesso para a identidade gerida ou o principal de serviço usando a biblioteca cliente Azure.Identity. Use o token de acesso e AZURE_COSMOS_LISTCONNECTIONSTRINGURL para obter a cadeia de conexão. Obtenha as informações de conexão das variáveis de ambiente adicionadas pelo Service Connector e conecte-se ao Azure Cosmos DB para MongoDB. Ao usar o código abaixo, descomente a parte do trecho de código para o tipo de autenticação que você deseja usar.

    using System;
    using System.Security.Authentication;
    using System.Net.Security;
    using System.Net.Http;
    using System.Security.Authentication;
    using System.Security.Cryptography.X509Certificates;
    using System.Threading.Tasks;
    using MongoDB.Driver;
    using Azure.Identity;
    using System.Text.Json;
    
    // you can retrieve the endpoint of the resource with the following env variable:
    // Environment.GetEnvironmentVariable("AZURE_COSMOS_RESOURCEENDPOINT");
    var listConnectionStringUrl = Environment.GetEnvironmentVariable("AZURE_COSMOS_LISTCONNECTIONSTRINGURL");
    var scope = Environment.GetEnvironmentVariable("AZURE_COSMOS_SCOPE");
    
    // Uncomment the following lines corresponding to the authentication type you want to use.
    // For system-assigned identity.
    // var tokenProvider = new DefaultAzureCredential();
    
    // For user-assigned identity.
    // var tokenProvider = new DefaultAzureCredential(
    //     new DefaultAzureCredentialOptions
    //     {
    //         ManagedIdentityClientId = Environment.GetEnvironmentVariable("AZURE_COSMOS_CLIENTID")
    //     }
    // );
    
    // For service principal.
    // var tenantId = Environment.GetEnvironmentVariable("AZURE_COSMOS_TENANTID");
    // var clientId = Environment.GetEnvironmentVariable("AZURE_COSMOS_CLIENTID");
    // var clientSecret = Environment.GetEnvironmentVariable("AZURE_COSMOS_CLIENTSECRET");
    // var tokenProvider = new ClientSecretCredential(tenantId, clientId, clientSecret);
    
    // Acquire the access token. 
    AccessToken accessToken = await tokenProvider.GetTokenAsync(
        new TokenRequestContext(scopes: new string[]{ scope }));
    
    // Get the connection string.
    var httpClient = new HttpClient();
    httpClient.DefaultRequestHeaders.Add("Authorization", $"Bearer {accessToken.Token}");
    var response = await httpClient.PostAsync(new Uri(listConnectionStringUrl), null);
    var responseBody = await response.Content.ReadAsStringAsync();
    var connectionStrings = JsonSerializer.Deserialize<Dictionary<string, List<Dictionary<string, string>>>>(responseBody);
    var connectionString = connectionStrings["connectionStrings"][0]["connectionString"];
    
    // Connect to Azure Cosmos DB for MongoDB
    var client = new MongoClient(connectionString);
    

Identidade gerida atribuída pelo utilizador

Nome da variável de ambiente padrão Descrição Valor de exemplo
AZURE_COSMOS_LISTCONNECTIONSTRINGURL URL para obter a cadeia de conexão https://management.azure.com/subscriptions/<subscription-ID>/resourceGroups/<resource-group-name>/providers/Microsoft.DocumentDB/databaseAccounts/<Azure-Cosmos-DB-API-for-MongoDB-account>/listConnectionStrings?api-version=2021-04-15
AZURE_COSMOS_SCOPE O seu âmbito de identidade gerida https://management.azure.com/.default
AZURE_COSMOS_CLIENTID O seu ID de cliente <client-ID>
AZURE_COSMOS_RESOURCEENDPOINT Seu ponto de extremidade de recurso https://<Azure-Cosmos-DB-API-for-MongoDB-account>.documents.azure.com:443/

Código de exemplo

Consulte as etapas e o código abaixo para se conectar ao Azure Cosmos DB para MongoDB usando uma identidade gerenciada atribuída pelo usuário.

Como o Cosmos DB não oferece suporte nativo à autenticação por meio de identidade gerenciada, no exemplo de código a seguir, usamos a identidade gerenciada para recuperar a cadeia de conexão, e a conexão é estabelecida usando essa cadeia de conexão.

  1. Instalar dependências

    dotnet add package MongoDb.Driver
    dotnet add package Azure.Identity
    
  2. Obtenha um token de acesso para a identidade gerida ou a entidade de serviço usando a biblioteca cliente Azure.Identity. Use o token de acesso e AZURE_COSMOS_LISTCONNECTIONSTRINGURL para obter a cadeia de conexão. Obtenha as informações de conexão das variáveis de ambiente adicionadas pelo Service Connector e conecte-se ao Azure Cosmos DB para MongoDB. Ao usar o código abaixo, descomente a parte do trecho de código para o tipo de autenticação que você deseja usar.

    using System;
    using System.Security.Authentication;
    using System.Net.Security;
    using System.Net.Http;
    using System.Security.Authentication;
    using System.Security.Cryptography.X509Certificates;
    using System.Threading.Tasks;
    using MongoDB.Driver;
    using Azure.Identity;
    using System.Text.Json;
    
    // you can retrieve the endpoint of the resource with the following env variable:
    // Environment.GetEnvironmentVariable("AZURE_COSMOS_RESOURCEENDPOINT");
    var listConnectionStringUrl = Environment.GetEnvironmentVariable("AZURE_COSMOS_LISTCONNECTIONSTRINGURL");
    var scope = Environment.GetEnvironmentVariable("AZURE_COSMOS_SCOPE");
    
    // Uncomment the following lines corresponding to the authentication type you want to use.
    // For system-assigned identity.
    // var tokenProvider = new DefaultAzureCredential();
    
    // For user-assigned identity.
    // var tokenProvider = new DefaultAzureCredential(
    //     new DefaultAzureCredentialOptions
    //     {
    //         ManagedIdentityClientId = Environment.GetEnvironmentVariable("AZURE_COSMOS_CLIENTID")
    //     }
    // );
    
    // For service principal.
    // var tenantId = Environment.GetEnvironmentVariable("AZURE_COSMOS_TENANTID");
    // var clientId = Environment.GetEnvironmentVariable("AZURE_COSMOS_CLIENTID");
    // var clientSecret = Environment.GetEnvironmentVariable("AZURE_COSMOS_CLIENTSECRET");
    // var tokenProvider = new ClientSecretCredential(tenantId, clientId, clientSecret);
    
    // Acquire the access token. 
    AccessToken accessToken = await tokenProvider.GetTokenAsync(
        new TokenRequestContext(scopes: new string[]{ scope }));
    
    // Get the connection string.
    var httpClient = new HttpClient();
    httpClient.DefaultRequestHeaders.Add("Authorization", $"Bearer {accessToken.Token}");
    var response = await httpClient.PostAsync(new Uri(listConnectionStringUrl), null);
    var responseBody = await response.Content.ReadAsStringAsync();
    var connectionStrings = JsonSerializer.Deserialize<Dictionary<string, List<Dictionary<string, string>>>>(responseBody);
    var connectionString = connectionStrings["connectionStrings"][0]["connectionString"];
    
    // Connect to Azure Cosmos DB for MongoDB
    var client = new MongoClient(connectionString);
    

Cadeia de conexão

Aviso

A Microsoft recomenda que você use o fluxo de autenticação mais seguro disponível. O fluxo de autenticação descrito neste procedimento requer um grau muito alto de confiança no aplicativo e acarreta riscos que não estão presentes em outros fluxos. Você só deve usar esse fluxo quando outros fluxos mais seguros, como identidades gerenciadas, não forem viáveis.

Tipo de cliente Spring Boot

Nome da variável de ambiente padrão Descrição Valor de exemplo
spring.data.mongodb.database A sua base de dados <database-name>
spring.data.mongodb.uri O URI do banco de dados mongodb://<mongo-db-admin-user>:<password>@<mongo-db-server>.mongo.cosmos.azure.com:10255/?ssl=true&replicaSet=globaldb&retrywrites=false&maxIdleTimeMS=120000&appName=@<mongo-db-server>@

Outros tipos de clientes

Nome da variável de ambiente padrão Descrição Valor de exemplo
AZURE_COSMOS_CONNECTIONSTRING Cadeia de conexão da API do MongoDB mongodb://<mongo-db-admin-user>:<password>@<mongo-db-server>.mongo.cosmos.azure.com:10255/?ssl=true&replicaSet=globaldb&retrywrites=false&maxIdleTimeMS=120000&appName=@<mongo-db-server>@

Código de exemplo

Consulte as etapas e o código abaixo para se conectar ao Azure Cosmos DB para MongoDB usando uma cadeia de conexão.

  1. Instalar dependência.

    dotnet add package MongoDb.Driver
    
  2. Obtenha a cadeia de conexão da variável de ambiente adicionada pelo Service Connector e conecte-se ao Azure Cosmos DB para MongoDB.

    using MongoDB.Driver;
    
    var connectionString = Environment.GetEnvironmentVariable("AZURE_COSMOS_CONNECTIONSTRING");
    var client = new MongoClient(connectionString);
    

Service principal

Nome da variável de ambiente padrão Descrição Valor de exemplo
AZURE_COSMOS_LISTCONNECTIONSTRINGURL URL para obter cadeia de ligação https://management.azure.com/subscriptions/<subscription-ID>/resourceGroups/<resource-group-name>/providers/Microsoft.DocumentDB/databaseAccounts/<Azure-Cosmos-DB-API-for-MongoDB-account>/listConnectionStrings?api-version=2021-04-15
AZURE_COSMOS_SCOPE O seu âmbito de identidade gerida https://management.azure.com/.default
AZURE_COSMOS_CLIENTID O seu ID de cliente <client-ID>
AZURE_COSMOS_CLIENTSECRET O segredo do seu cliente <client-secret>
AZURE_COSMOS_TENANTID O seu ID de inquilino <tenant-ID>
AZURE_COSMOS_RESOURCEENDPOINT Seu ponto de extremidade de recurso https://<Azure-Cosmos-DB-API-for-MongoDB-account>.documents.azure.com:443/

Código de exemplo

Consulte os passos e o código abaixo para se conectar ao Azure Cosmos DB para MongoDB utilizando um principal de serviço.

  1. Instalar dependências

    dotnet add package MongoDb.Driver
    dotnet add package Azure.Identity
    
  2. Obtenha um token de acesso para a identidade gerida ou entidade de serviço utilizando a biblioteca cliente Azure.Identity. Use o token de acesso e AZURE_COSMOS_LISTCONNECTIONSTRINGURL para obter a cadeia de conexão. Obtenha as informações de conexão das variáveis de ambiente adicionadas pelo Service Connector e conecte-se ao Azure Cosmos DB para MongoDB. Ao usar o código abaixo, descomente a parte do trecho de código para o tipo de autenticação que você deseja usar.

    using System;
    using System.Security.Authentication;
    using System.Net.Security;
    using System.Net.Http;
    using System.Security.Authentication;
    using System.Security.Cryptography.X509Certificates;
    using System.Threading.Tasks;
    using MongoDB.Driver;
    using Azure.Identity;
    using System.Text.Json;
    
    // you can retrieve the endpoint of the resource with the following env variable:
    // Environment.GetEnvironmentVariable("AZURE_COSMOS_RESOURCEENDPOINT");
    var listConnectionStringUrl = Environment.GetEnvironmentVariable("AZURE_COSMOS_LISTCONNECTIONSTRINGURL");
    var scope = Environment.GetEnvironmentVariable("AZURE_COSMOS_SCOPE");
    
    // Uncomment the following lines corresponding to the authentication type you want to use.
    // For system-assigned identity.
    // var tokenProvider = new DefaultAzureCredential();
    
    // For user-assigned identity.
    // var tokenProvider = new DefaultAzureCredential(
    //     new DefaultAzureCredentialOptions
    //     {
    //         ManagedIdentityClientId = Environment.GetEnvironmentVariable("AZURE_COSMOS_CLIENTID")
    //     }
    // );
    
    // For service principal.
    // var tenantId = Environment.GetEnvironmentVariable("AZURE_COSMOS_TENANTID");
    // var clientId = Environment.GetEnvironmentVariable("AZURE_COSMOS_CLIENTID");
    // var clientSecret = Environment.GetEnvironmentVariable("AZURE_COSMOS_CLIENTSECRET");
    // var tokenProvider = new ClientSecretCredential(tenantId, clientId, clientSecret);
    
    // Acquire the access token. 
    AccessToken accessToken = await tokenProvider.GetTokenAsync(
        new TokenRequestContext(scopes: new string[]{ scope }));
    
    // Get the connection string.
    var httpClient = new HttpClient();
    httpClient.DefaultRequestHeaders.Add("Authorization", $"Bearer {accessToken.Token}");
    var response = await httpClient.PostAsync(new Uri(listConnectionStringUrl), null);
    var responseBody = await response.Content.ReadAsStringAsync();
    var connectionStrings = JsonSerializer.Deserialize<Dictionary<string, List<Dictionary<string, string>>>>(responseBody);
    var connectionString = connectionStrings["connectionStrings"][0]["connectionString"];
    
    // Connect to Azure Cosmos DB for MongoDB
    var client = new MongoClient(connectionString);
    

Próximos passos

Siga os tutoriais listados abaixo para saber mais sobre o Service Connector.