Compartilhar via


Integrar o Azure Cosmos DB for Cassandra ao Conector de Serviço

Esta página mostra os métodos de autenticação e clientes compatíveis, além de exibir um código de exemplo que você pode usar para conectar o Azure Cosmos DB for Apache Cassandra a outros serviços de nuvem usando o Conector de Serviço. Você ainda pode se conectar ao Azure Cosmos DB for Cassandra em outras linguagens de programação sem usar o conector de serviço. Esta página também mostra nomes e valores da variável de ambiente padrão (ou configuração do Spring Boot) que você obtém ao criar a conexão de serviço.

Serviço de computação com suporte

O Conector de Serviço pode ser usado para conectar os seguintes serviços de computação ao Azure Cosmos DB for Apache Cassandra:

  • Serviço de Aplicativo do Azure
  • Aplicativos de Contêiner do Azure
  • Azure Functions
  • AKS (Serviço de Kubernetes do Azure)
  • Azure Spring Apps

Tipos de autenticação e tipos de cliente com suporte

A tabela abaixo mostra quais combinações de tipos de cliente e métodos de autenticação são compatíveis para conectar seu serviço de computação ao Azure Cosmos DB for Apache Cassandra usando o Conector de Serviço. “Sim” indica que a combinação tem suporte e “Não” indica que ela não tem.

Tipo de cliente Identidade gerenciada atribuída pelo sistema Identidade gerenciada atribuída pelo usuário Cadeia de conexão/segredo Entidade de serviço
.NET Sim Sim Sim Yes
Go Sim Sim Sim Sim
Java Sim Sim Sim Yes
Java – Spring Boot Não No Sim No
Node.js Sim Sim Sim Sim
Python Sim Sim Sim Yes
Nenhum Sim Sim Sim Sim

Esta tabela indica que todas as combinações de tipos de cliente e métodos de autenticação apresentados são compatíveis, exceto para o tipo de cliente Java – Spring Boot, que só é compatível com o método de segredo/cadeia de conexão. Todos os outros tipos de cliente podem usar qualquer um dos métodos de autenticação para se conectar ao Azure Cosmos DB for Apache Cassandra usando o Conector de Serviço.

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

Consulte os detalhes da conexão e o código de exemplo nas tabelas a seguir, de acordo com o tipo de autenticação e o tipo de cliente da sua conexão, para conectar seus serviços de computação ao Azure Cosmos DB for Apache Cassandra. Para saber mais sobre as convenções de nomenclatura, confira o artigo Detalhes internos no conector de serviço.

Identidade Gerenciada atribuída pelo sistema

Nome da variável de ambiente padrão Descrição Valor de exemplo
AZURE_COSMOS_LISTKEYURL A 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-account>/listKeys?api-version=2021-04-15
AZURE_COSMOS_SCOPE O escopo de sua identidade gerenciada https://management.azure.com/.default
AZURE_COSMOS_RESOURCEENDPOINT O ponto de extremidade do seu recurso https://<Azure-Cosmos-DB-account>.documents.azure.com:443/
AZURE_COSMOS_CONTACTPOINT Ponto de contato do Azure Cosmos DB for Apache Cassandra <Azure-Cosmos-DB-account>.cassandra.cosmos.azure.com
AZURE_COSMOS_PORT Porta de conexão do Cassandra 10350
AZURE_COSMOS_KEYSPACE Keyspace do Cassandra <keyspace>
AZURE_COSMOS_USERNAME Nome de usuário do Cassandra <username>

Código de exemplo

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

  1. Instalar dependências

    dotnet add package CassandraCSharpDriver --version 3.19.3
    dotnet add package Azure.Identity
    
  2. Obtenha um token de acesso para a identidade gerenciada ou entidade de serviço usando a biblioteca de clientes Azure.Identity. Use o token de acesso e AZURE_COSMOS_LISTKEYURL para obter a senha. Obtenha as informações de conexão das variáveis de ambiente adicionadas pelo Service Connector e conecte-se ao Azure Cosmos DB for Cassandra. Ao usar o código abaixo, descompacte a parte do snippet 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 Cassandra;
    using Azure.Identity;
    
    public class Program
    {
    	public static async Task Main()
    	{
            var cassandraContactPoint = Environment.GetEnvironmentVariable("AZURE_COSMOS_CONTACTPOINT");
            var userName = Environment.GetEnvironmentVariable("AZURE_COSMOS_USERNAME");
            var cassandraPort = Int32.Parse(Environment.GetEnvironmentVariable("AZURE_COSMOS_PORT"));
            var cassandraKeyspace = Environment.GetEnvironmentVariable("AZURE_COSMOS_KEYSPACE");
            var listKeyUrl = Environment.GetEnvironmentVariable("AZURE_COSMOS_LISTKEYURL");
            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 password.
            var httpClient = new HttpClient();
            httpClient.DefaultRequestHeaders.Add("Authorization", $"Bearer {accessToken.Token}");
            var response = await httpClient.POSTAsync(listKeyUrl);
            var responseBody = await response.Content.ReadAsStringAsync();
            var keys = JsonConvert.DeserializeObject<Dictionary<string, string>>(responseBody);
            var password = keys["primaryMasterKey"];
    
            // Connect to Azure Cosmos DB for Cassandra
            var options = new Cassandra.SSLOptions(SslProtocols.Tls12, true, ValidateServerCertificate);
            options.SetHostNameResolver((ipAddress) => cassandraContactPoint);
            Cluster cluster = Cluster
                .Builder()
                .WithCredentials(userName, password)
                .WithPort(cassandraPort)
                .AddContactPoint(cassandraContactPoint).WithSSL(options).Build();
            ISession session = await cluster.ConnectAsync();
        }
    
        public static bool ValidateServerCertificate
    	(
            object sender,
            X509Certificate certificate,
            X509Chain chain,
            SslPolicyErrors sslPolicyErrors
        )
        {
            if (sslPolicyErrors == SslPolicyErrors.None)
                return true;
    
            Console.WriteLine("Certificate error: {0}", sslPolicyErrors);
            // Do not allow this client to communicate with unauthenticated servers.
            return false;
        }
    }
    
    

Identidade gerenciada atribuída ao usuário

Nome da variável de ambiente padrão Descrição Valor de exemplo
AZURE_COSMOS_LISTKEYURL A 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-account>/listKeys?api-version=2021-04-15
AZURE_COSMOS_SCOPE O escopo de sua identidade gerenciada https://management.azure.com/.default
AZURE_COSMOS_RESOURCEENDPOINT O ponto de extremidade do seu recurso https://<Azure-Cosmos-DB-account>.documents.azure.com:443/
AZURE_COSMOS_CONTACTPOINT Ponto de contato do Azure Cosmos DB for Apache Cassandra <Azure-Cosmos-DB-account>.cassandra.cosmos.azure.com
AZURE_COSMOS_PORT Porta de conexão do Cassandra 10350
AZURE_COSMOS_KEYSPACE Keyspace do Cassandra <keyspace>
AZURE_COSMOS_USERNAME Nome de usuário do Cassandra <username>
AZURE_COSMOS_CLIENTID Sua ID de cliente <client-ID>

Código de exemplo

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

  1. Instalar dependências

    dotnet add package CassandraCSharpDriver --version 3.19.3
    dotnet add package Azure.Identity
    
  2. Obtenha um token de acesso para a identidade gerenciada ou entidade de serviço usando a biblioteca de clientes Azure.Identity. Use o token de acesso e AZURE_COSMOS_LISTKEYURL para obter a senha. Obtenha as informações de conexão das variáveis de ambiente adicionadas pelo Service Connector e conecte-se ao Azure Cosmos DB for Cassandra. Ao usar o código abaixo, descompacte a parte do snippet 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 Cassandra;
    using Azure.Identity;
    
    public class Program
    {
    	public static async Task Main()
    	{
            var cassandraContactPoint = Environment.GetEnvironmentVariable("AZURE_COSMOS_CONTACTPOINT");
            var userName = Environment.GetEnvironmentVariable("AZURE_COSMOS_USERNAME");
            var cassandraPort = Int32.Parse(Environment.GetEnvironmentVariable("AZURE_COSMOS_PORT"));
            var cassandraKeyspace = Environment.GetEnvironmentVariable("AZURE_COSMOS_KEYSPACE");
            var listKeyUrl = Environment.GetEnvironmentVariable("AZURE_COSMOS_LISTKEYURL");
            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 password.
            var httpClient = new HttpClient();
            httpClient.DefaultRequestHeaders.Add("Authorization", $"Bearer {accessToken.Token}");
            var response = await httpClient.POSTAsync(listKeyUrl);
            var responseBody = await response.Content.ReadAsStringAsync();
            var keys = JsonConvert.DeserializeObject<Dictionary<string, string>>(responseBody);
            var password = keys["primaryMasterKey"];
    
            // Connect to Azure Cosmos DB for Cassandra
            var options = new Cassandra.SSLOptions(SslProtocols.Tls12, true, ValidateServerCertificate);
            options.SetHostNameResolver((ipAddress) => cassandraContactPoint);
            Cluster cluster = Cluster
                .Builder()
                .WithCredentials(userName, password)
                .WithPort(cassandraPort)
                .AddContactPoint(cassandraContactPoint).WithSSL(options).Build();
            ISession session = await cluster.ConnectAsync();
        }
    
        public static bool ValidateServerCertificate
    	(
            object sender,
            X509Certificate certificate,
            X509Chain chain,
            SslPolicyErrors sslPolicyErrors
        )
        {
            if (sslPolicyErrors == SslPolicyErrors.None)
                return true;
    
            Console.WriteLine("Certificate error: {0}", sslPolicyErrors);
            // Do not allow this client to communicate with unauthenticated servers.
            return false;
        }
    }
    
    

Cadeia de conexão

Aviso

A Microsoft recomenda usar o fluxo de autenticação mais seguro disponível. O fluxo de autenticação descrito neste procedimento exige um grau muito alto de confiança no aplicativo e traz 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 SpringBoot

Nome da variável de ambiente padrão Descrição Valor de exemplo
spring.data.cassandra.contact-points Ponto de contato do Azure Cosmos DB for Apache Cassandra <Azure-Cosmos-DB-account>.cassandra.cosmos.azure.com
spring.data.cassandra.port Porta de conexão do Cassandra 10350
spring.data.cassandra.keyspace-name Keyspace do Cassandra <keyspace>
spring.data.cassandra.username Nome de usuário do Cassandra <username>
spring.data.cassandra.password Senha do Cassandra <password>
spring.data.cassandra.local-datacenter Região do Azure <Azure-region>
spring.data.cassandra.ssl Status do SSL true

Outros tipos de clientes

Nome da variável de ambiente padrão Descrição Valor de exemplo
AZURE_COSMOS_CONTACTPOINT Ponto de contato do Azure Cosmos DB for Apache Cassandra <Azure-Cosmos-DB-account>.cassandra.cosmos.azure.com
AZURE_COSMOS_PORT Porta de conexão do Cassandra 10350
AZURE_COSMOS_KEYSPACE Keyspace do Cassandra <keyspace>
AZURE_COSMOS_USERNAME Nome de usuário do Cassandra <username>
AZURE_COSMOS_PASSWORD Senha do Cassandra <password>

Código de exemplo

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

  1. Instalar dependências

    dotnet add package CassandraCSharpDriver --version 3.19.3
    
  2. Obtenha as informações de conexão das variáveis de ambiente adicionadas pelo Service Connector e conecte-se ao Azure Cosmos DB for Cassandra.

    using System;
    using System.Security.Authentication;
    using System.Net.Security;
    using System.Security.Authentication;
    using System.Security.Cryptography.X509Certificates;
    using System.Threading.Tasks;
    using Cassandra;
    
    public class Program
    {
    	public static async Task Main()
    	{
            var cassandraContactPoint = Environment.GetEnvironmentVariable("AZURE_COSMOS_CONTACTPOINT");
            var userName = Environment.GetEnvironmentVariable("AZURE_COSMOS_USERNAME");
            var password = Environment.GetEnvironmentVariable("AZURE_COSMOS_PASSWORD");
            var cassandraPort = Int32.Parse(Environment.GetEnvironmentVariable("AZURE_COSMOS_PORT"));
            var cassandraKeyspace = Environment.GetEnvironmentVariable("AZURE_COSMOS_KEYSPACE");
    
            var options = new Cassandra.SSLOptions(SslProtocols.Tls12, true, ValidateServerCertificate);
            options.SetHostNameResolver((ipAddress) => cassandraContactPoint);
            Cluster cluster = Cluster
                .Builder()
                .WithCredentials(userName, password)
                .WithPort(cassandraPort)
                .AddContactPoint(cassandraContactPoint).WithSSL(options).Build();
            ISession session = await cluster.ConnectAsync();
        }
    
        public static bool ValidateServerCertificate
    	(
            object sender,
            X509Certificate certificate,
            X509Chain chain,
            SslPolicyErrors sslPolicyErrors
        )
        {
            if (sslPolicyErrors == SslPolicyErrors.None)
                return true;
    
            Console.WriteLine("Certificate error: {0}", sslPolicyErrors);
            // Do not allow this client to communicate with unauthenticated servers.
            return false;
        }
    }
    
    

Para mais informações, confira o artigo Criar um aplicativo do Apache Cassandra com o SDK do .NET e o Azure Cosmos DB.

Entidade de serviço

Nome da variável de ambiente padrão Descrição Valor de exemplo
AZURE_COSMOS_LISTKEYURL A 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-account>/listKeys?api-version=2021-04-15
AZURE_COSMOS_SCOPE O escopo de sua identidade gerenciada https://management.azure.com/.default
AZURE_COSMOS_RESOURCEENDPOINT O ponto de extremidade do seu recurso https://<Azure-Cosmos-DB-account>.documents.azure.com:443/
AZURE_COSMOS_CONTACTPOINT Ponto de contato do Azure Cosmos DB for Apache Cassandra <Azure-Cosmos-DB-account>.cassandra.cosmos.azure.com
AZURE_COSMOS_PORT Porta de conexão do Cassandra 10350
AZURE_COSMOS_KEYSPACE Keyspace do Cassandra <keyspace>
AZURE_COSMOS_USERNAME Nome de usuário do Cassandra <username>
AZURE_COSMOS_CLIENTID Sua ID de cliente <client-ID>
AZURE_COSMOS_CLIENTSECRET Seu segredo do cliente <client-secret>
AZURE_COSMOS_TENANTID Sua ID de locatário <tenant-ID>

Código de exemplo

Confira as etapas e o código abaixo para se conectar ao Azure Cosmos DB for Cassandra usando uma entidade de serviço.

  1. Instalar dependências

    dotnet add package CassandraCSharpDriver --version 3.19.3
    dotnet add package Azure.Identity
    
  2. Obtenha um token de acesso para a identidade gerenciada ou entidade de serviço usando a biblioteca de clientes Azure.Identity. Use o token de acesso e AZURE_COSMOS_LISTKEYURL para obter a senha. Obtenha as informações de conexão das variáveis de ambiente adicionadas pelo Service Connector e conecte-se ao Azure Cosmos DB for Cassandra. Ao usar o código abaixo, descompacte a parte do snippet 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 Cassandra;
    using Azure.Identity;
    
    public class Program
    {
    	public static async Task Main()
    	{
            var cassandraContactPoint = Environment.GetEnvironmentVariable("AZURE_COSMOS_CONTACTPOINT");
            var userName = Environment.GetEnvironmentVariable("AZURE_COSMOS_USERNAME");
            var cassandraPort = Int32.Parse(Environment.GetEnvironmentVariable("AZURE_COSMOS_PORT"));
            var cassandraKeyspace = Environment.GetEnvironmentVariable("AZURE_COSMOS_KEYSPACE");
            var listKeyUrl = Environment.GetEnvironmentVariable("AZURE_COSMOS_LISTKEYURL");
            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 password.
            var httpClient = new HttpClient();
            httpClient.DefaultRequestHeaders.Add("Authorization", $"Bearer {accessToken.Token}");
            var response = await httpClient.POSTAsync(listKeyUrl);
            var responseBody = await response.Content.ReadAsStringAsync();
            var keys = JsonConvert.DeserializeObject<Dictionary<string, string>>(responseBody);
            var password = keys["primaryMasterKey"];
    
            // Connect to Azure Cosmos DB for Cassandra
            var options = new Cassandra.SSLOptions(SslProtocols.Tls12, true, ValidateServerCertificate);
            options.SetHostNameResolver((ipAddress) => cassandraContactPoint);
            Cluster cluster = Cluster
                .Builder()
                .WithCredentials(userName, password)
                .WithPort(cassandraPort)
                .AddContactPoint(cassandraContactPoint).WithSSL(options).Build();
            ISession session = await cluster.ConnectAsync();
        }
    
        public static bool ValidateServerCertificate
    	(
            object sender,
            X509Certificate certificate,
            X509Chain chain,
            SslPolicyErrors sslPolicyErrors
        )
        {
            if (sslPolicyErrors == SslPolicyErrors.None)
                return true;
    
            Console.WriteLine("Certificate error: {0}", sslPolicyErrors);
            // Do not allow this client to communicate with unauthenticated servers.
            return false;
        }
    }
    
    

Próximas etapas

Siga os tutoriais listados abaixo para saber mais sobre o Conector de Serviço.