Integrar o Azure Cosmos DB para Cassandra 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 Apache Cassandra a outros serviços na nuvem utilizando o Service Connector. Talvez você ainda consiga se conectar ao Azure Cosmos DB para Cassandra 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 Apache Cassandra:

  • 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 Apache Cassandra 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 Service principal (Principal de serviço)
.NET Sim Sim Sim Sim
Go Sim Sim Sim Sim
Java Sim Sim Sim Sim
Java - Arranque primavera No No Sim No
Node.js Sim Sim Sim Sim
Python 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 Apache Cassandra usando o Service Connector.

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 para Apache Cassandra. Para obter mais informações sobre convenções de nomenclatura, consulte o artigo interno do Service Connector.

Identidade gerenciada atribuída pelo sistema

Nome da variável de ambiente padrão Description 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 Seu escopo de identidade gerenciado https://management.azure.com/.default
AZURE_COSMOS_RESOURCEENDPOINT Seu ponto de extremidade de recurso https://<Azure-Cosmos-DB-account>.documents.azure.com:443/
AZURE_COSMOS_CONTACTPOINT Ponto de contato do Azure Cosmos DB para Apache Cassandra <Azure-Cosmos-DB-account>.cassandra.cosmos.azure.com
AZURE_COSMOS_PORT Porta de conexão Cassandra 10350
AZURE_COSMOS_KEYSPACE Chaveiro Cassandra <keyspace>
AZURE_COSMOS_USERNAME Cassandra nome de utilizador <username>

Código de exemplo

Consulte as etapas e o código abaixo para se conectar ao Azure Cosmos DB para Cassandra usando uma identidade gerenciada atribuída ao 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 a entidade de serviço usando a biblioteca de cliente 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, 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 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 pelo usuário

Nome da variável de ambiente padrão Description 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 Seu escopo de identidade gerenciado https://management.azure.com/.default
AZURE_COSMOS_RESOURCEENDPOINT Seu ponto de extremidade de recurso https://<Azure-Cosmos-DB-account>.documents.azure.com:443/
AZURE_COSMOS_CONTACTPOINT Ponto de contato do Azure Cosmos DB para Apache Cassandra <Azure-Cosmos-DB-account>.cassandra.cosmos.azure.com
AZURE_COSMOS_PORT Porta de conexão Cassandra 10350
AZURE_COSMOS_KEYSPACE Chaveiro Cassandra <keyspace>
AZURE_COSMOS_USERNAME Cassandra nome de utilizador <username>
AZURE_COSMOS_CLIENTID O seu ID de cliente <client-ID>

Código de exemplo

Consulte as etapas e o código abaixo para se conectar ao Azure Cosmos DB para 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 a entidade de serviço usando a biblioteca de cliente 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, 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 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 Ligaçã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 SpringBoot

Nome da variável de ambiente padrão Description Valor de exemplo
spring.data.cassandra.pontos de contacto Ponto de contato do Azure Cosmos DB para Apache Cassandra <Azure-Cosmos-DB-account>.cassandra.cosmos.azure.com
spring.data.cassandra.port Porta de conexão Cassandra 10350
spring.data.cassandra.keyspace-nome Chaveiro Cassandra <keyspace>
spring.data.cassandra.nome de usuário Cassandra nome de utilizador <username>
spring.data.cassandra.password Cassandra senha <password>
spring.data.cassandra.local-datacenter Região do Azure <Azure-region>
primavera.data.cassandra.ssl Estado SSL verdadeiro

Outros tipos de clientes

Nome da variável de ambiente padrão Description Valor de exemplo
AZURE_COSMOS_CONTACTPOINT Ponto de contato do Azure Cosmos DB para Apache Cassandra <Azure-Cosmos-DB-account>.cassandra.cosmos.azure.com
AZURE_COSMOS_PORT Porta de conexão Cassandra 10350
AZURE_COSMOS_KEYSPACE Chaveiro Cassandra <keyspace>
AZURE_COSMOS_USERNAME Cassandra nome de utilizador <username>
AZURE_COSMOS_PASSWORD Cassandra senha <password>

Código de exemplo

Consulte as etapas e o código abaixo para se conectar ao Azure Cosmos DB para 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 obter mais informações, consulte Criar um aplicativo Apache Cassandra com o SDK do .NET e o Azure Cosmos DB.

Service principal (Principal de serviço)

Nome da variável de ambiente padrão Description 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 Seu escopo de identidade gerenciado https://management.azure.com/.default
AZURE_COSMOS_RESOURCEENDPOINT Seu ponto de extremidade de recurso https://<Azure-Cosmos-DB-account>.documents.azure.com:443/
AZURE_COSMOS_CONTACTPOINT Ponto de contato do Azure Cosmos DB para Apache Cassandra <Azure-Cosmos-DB-account>.cassandra.cosmos.azure.com
AZURE_COSMOS_PORT Porta de conexão Cassandra 10350
AZURE_COSMOS_KEYSPACE Chaveiro Cassandra <keyspace>
AZURE_COSMOS_USERNAME Cassandra nome de utilizador <username>
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>

Código de exemplo

Consulte as etapas e o código abaixo para se conectar ao Azure Cosmos DB para 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 a entidade de serviço usando a biblioteca de cliente 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, 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 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óximos passos

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