Tutorial: Criar uma API para a conta do Cassandra no Azure Cosmos DB com uma aplicação Java para armazenar dados de chave/valor

Artigo
04/11/2023

APLICA-SE A: Cassandra

Enquanto programador, poderá ter aplicações que utilizam pares chave/valor. Pode utilizar uma API para a conta do Cassandra no Azure Cosmos DB para armazenar os dados de chave/valor. Este tutorial descreve como utilizar uma aplicação Java para criar uma conta API para Cassandra no Azure Cosmos DB, adicionar uma base de dados (também denominada espaço de chaves) e adicionar uma tabela. A aplicação Java utiliza o controlador Java para criar uma base de dados de utilizador que contém detalhes como o ID de utilizador, o nome de utilizador e a cidade do utilizador.

Este tutorial abrange as seguintes tarefas:

Criar uma conta de base de dados Cassandra
Obter a cadeia de ligação da conta
Criar um projeto e dependências do Maven
Adicionar uma base de dados e uma tabela
Executar a aplicação

Pré-requisitos

Se não tiver uma subscrição do Azure, crie uma conta gratuita antes de começar.
Obtenha a versão mais recente do Java Development Kit (JDK).
Transfira e instale o arquivo binário do Maven .
- No Ubuntu, pode executar apt-get install maven para instalar o Maven.

Criar uma conta de base de dados

No menu portal do Azure ou na Home page, selecione Criar um recurso.
Na página Novo , procure e selecione Azure Cosmos DB.
Na página Azure Cosmos DB , selecione Criar.
Na página API , selecione Criar na secção Cassandra .

A API determina o tipo de conta a criar. O Azure Cosmos DB fornece cinco APIs: NoSQL para bases de dados de documentos, Gremlin para bases de dados de gráficos, MongoDB para bases de dados de documentos, Tabela do Azure e Cassandra. Tem de criar uma conta separada para cada API.

Selecione Cassandra, porque neste início rápido está a criar uma tabela que funciona com a API para Cassandra.

Saiba mais sobre a API para Cassandra.

Na página Criar Conta do Azure Cosmos DB , introduza as definições básicas para a nova conta do Azure Cosmos DB.

Definição	Valor	Descrição
Subscrição	A sua subscrição	Selecione a subscrição do Azure que quer utilizar para esta conta do Azure Cosmos DB.
Grupo de Recursos	Criar novo Em seguida, introduza o mesmo nome que Nome da Conta	Selecione Criar novo. Em seguida, introduza um novo nome de grupo de recursos para a sua conta. Para simplificar, utilize o mesmo nome que o nome da sua conta do Azure Cosmos DB.
Nome da Conta	Introduza um nome exclusivo	Introduza um nome exclusivo para identificar a sua conta do Azure Cosmos DB. O URI da conta será cassandra.cosmos.azure.com anexado ao nome exclusivo da sua conta. O nome da conta só pode utilizar letras minúsculas, números e hífenes (-) e tem de ter entre 3 e 31 carateres de comprimento.
Localização	A região mais próxima dos seus utilizadores	Selecione a localização geográfica para alojar a sua conta do Azure Cosmos DB. Utilize a localização mais próxima dos utilizadores para lhes dar o acesso mais rápido aos dados.
Modo de capacidade	Débito aprovisionado ou Sem servidor	Selecione Débito aprovisionado para criar uma conta no modo de débito aprovisionado . Selecione Sem servidor para criar uma conta no modo sem servidor .
Aplicar o desconto de escalão gratuito do Azure Cosmos DB	Aplicar ou Não aplicar	Com o escalão gratuito do Azure Cosmos DB, obterá as primeiras 1000 RU/s e 25 GB de armazenamento gratuitamente numa conta. Saiba mais sobre o escalão gratuito.
Limitar débito total da conta	Selecionar para limitar o débito da conta	Isto é útil se quiser limitar o débito total da conta a um valor específico.

Nota

Pode ter até uma conta do Azure Cosmos DB de escalão gratuito por subscrição do Azure e tem de optar ativamente por participar ao criar a conta. Se não vir a opção para aplicar o desconto de escalão gratuito, significa que já foi ativada outra conta na subscrição com o escalão gratuito.

A nova página de conta do Azure Cosmos DB para Apache Cassandra

No separador Distribuição Global , configure os seguintes detalhes. Pode deixar os valores predefinidos para efeitos deste início rápido:

Definição	Valor	Descrição
Redundância Geográfica	Desativar	Ative ou desative a distribuição global na sua conta ao emparelhar a sua região com uma região de par. Pode adicionar mais regiões à sua conta mais tarde.
Escritas de várias regiões	Desativar	A capacidade de escrita de várias regiões permite-lhe tirar partido do débito aprovisionado para as suas bases de dados e contentores em todo o mundo.
Zonas de Disponibilidade	Desativar	Zonas de Disponibilidade são localizações isoladas numa região do Azure. Cada zona é composta por um ou mais datacenters equipados com energia, refrigeração e rede independentes.

Nota

As seguintes opções não estão disponíveis se selecionar Sem servidor como modo de Capacidade:

Aplicar Desconto de Escalão Gratuito
Georredundância
Escritas de várias regiões

Opcionalmente, pode configurar detalhes adicionais nos seguintes separadores:
- Rede – configure o acesso a partir de uma rede virtual.
- Política de Cópia de Segurança – configure uma política de cópia de segurança periódica ou contínua .
- Encriptação – utilize uma chave gerida pelo serviço ou uma chave gerida pelo cliente.
- Etiquetas – as etiquetas são pares nome/valor que lhe permitem categorizar recursos e ver a faturação consolidada ao aplicar a mesma etiqueta a vários recursos e grupos de recursos.
Selecione Rever + criar.
Reveja as definições da conta e, em seguida, selecione Criar. A criação da conta demora alguns minutos. Aguarde até que a página do portal apresente A implementação está concluída.
Selecione Ir para recurso para aceder à página da conta do Azure Cosmos DB.

Obter os detalhes de ligação da conta

Obtenha as informações da cadeia de ligação do portal do Azure e copie-as para o ficheiro de configuração Java. A cadeia de ligação permite que a aplicação comunique com a base de dados alojada.

No portal do Azure, aceda à sua conta do Azure Cosmos DB.
Abra o painel Cadeia de Ligação .
Copie os valores de PONTO DE CONTACTO, PORTA, NOME DE UTILIZADOR e PALAVRA-PASSE PRINCIPAL para utilizá-los nos passos seguintes.

Criar o projeto e as dependências

O projeto de exemplo java que utiliza neste artigo está alojado no GitHub. Pode executar os passos neste documento ou transferir o exemplo do repositório azure-cosmos-db-cassandra-java-getting-started .

Depois de transferir os ficheiros, atualize as informações da cadeia de ligação no ficheiro e execute-as java-examples\src\main\resources\config.properties .

cassandra_host=<FILLME_with_CONTACT POINT> 
cassandra_port = 10350 
cassandra_username=<FILLME_with_USERNAME> 
cassandra_password=<FILLME_with_PRIMARY PASSWORD>

Utilize os seguintes passos para criar o exemplo de raiz:

No terminal ou na linha de comandos, crie um novo projeto Maven com o nome Cassandra-demo.

mvn archetype:generate -DgroupId=com.azure.cosmosdb.cassandra -DartifactId=cassandra-demo -DarchetypeArtifactId=maven-archetype-quickstart -DinteractiveMode=false

Localize a pasta cassandra-demo. Com um editor de texto, abra o ficheiro pom.xml que foi gerado.

Adicione as dependências do Cassandra e os plug-ins de compilação exigidos pelo projeto, conforme mostrado no ficheiro pom.xml .
Na pasta cassandra-demo\src\main, crie uma nova pasta com o nome resources. Na pasta de recursos, adicione os ficheiros config.properties e log4j.properties:
- O ficheiro config.properties armazena o ponto final de ligação e os valores chave da API para a conta do Cassandra.
- O ficheiro log4j.properties define o nível de registo necessário para interagir com a API para Cassandra.
Navegue para a src/main/java/com/azure/cosmosdb/cassandra/ pasta. Na pasta cassandra, crie outra pasta com o nome utils. A nova pasta armazena as classes de utilitários necessárias para ligar à API para a conta do Cassandra.

Adicione a classe CassandraUtils para criar o cluster e abrir e fechar as sessões de Cassandra. O cluster liga-se à conta da API para Cassandra no Azure Cosmos DB e devolve uma sessão para aceder. Utilize a classe Configurações para ler as informações da cadeia de ligação do ficheiro config.properties.
O exemplo Java cria uma base de dados com informações de utilizador, como o nome de utilizador, o ID de utilizador e a cidade do utilizador. Terá de definir os métodos obter e definir, para aceder aos detalhes do utilizador na função principal.

Crie uma classe User.java na src/main/java/com/azure/cosmosdb/cassandra/ pasta com métodos get and set.

Adicionar uma base de dados e uma tabela

Esta secção descreve como adicionar uma base de dados (espaço de chaves) e uma tabela com o CQL.

Na pasta src\main\java\com\azure\cosmosdb\cassandra, crie uma nova pasta com o nome repository.

Crie a UserRepository classe Java e adicione o seguinte código à mesma:

package com.azure.cosmosdb.cassandra.repository; 
import java.util.List; 
import com.datastax.driver.core.BoundStatement; 
import com.datastax.driver.core.PreparedStatement; 
import com.datastax.driver.core.Row; 
import com.datastax.driver.core.Session; 
import org.slf4j.Logger; 
import org.slf4j.LoggerFactory; 

/** 
 * Create a Cassandra session 
 */ 
public class UserRepository { 

    private static final Logger LOGGER = LoggerFactory.getLogger(UserRepository.class); 
    private Session session; 
    public UserRepository(Session session) { 
        this.session = session; 
    } 

    /** 
    * Create keyspace uprofile in cassandra DB 
     */ 

    public void createKeyspace() { 
         final String query = "CREATE KEYSPACE IF NOT EXISTS uprofile WITH REPLICATION = { 'class' : 'NetworkTopologyStrategy', 'datacenter1' : 1 }"; 
        session.execute(query); 
        LOGGER.info("Created keyspace 'uprofile'"); 
    } 

    /** 
     * Create user table in cassandra DB 
     */ 

    public void createTable() { 
        final String query = "CREATE TABLE IF NOT EXISTS uprofile.user (user_id int PRIMARY KEY, user_name text, user_bcity text)"; 
        session.execute(query); 
        LOGGER.info("Created table 'user'"); 
    } 
}

Localize a pasta src\main\java\com\azure\cosmosdb\cassandra e crie uma nova subpasta com o nome examples.

Crie a UserProfile classe Java. Esta classe contém o método principal que chama os métodos createKeyspace e createTable definidos anteriormente:

package com.azure.cosmosdb.cassandra.examples; 
import java.io.IOException; 
import com.azure.cosmosdb.cassandra.repository.UserRepository; 
import com.azure.cosmosdb.cassandra.util.CassandraUtils; 
import com.datastax.driver.core.PreparedStatement; 
import com.datastax.driver.core.Session; 
import org.slf4j.Logger; 
import org.slf4j.LoggerFactory; 

/** 
 * Example class which will demonstrate following operations on Cassandra Database on CosmosDB 
 * - Create Keyspace 
 * - Create Table 
 * - Insert Rows 
 * - Select all data from a table 
 * - Select a row from a table 
 */ 

public class UserProfile { 

    private static final Logger LOGGER = LoggerFactory.getLogger(UserProfile.class); 
    public static void main(String[] s) throws Exception { 
        CassandraUtils utils = new CassandraUtils(); 
        Session cassandraSession = utils.getSession(); 

        try { 
            UserRepository repository = new UserRepository(cassandraSession); 
            //Create keyspace in cassandra database 
            repository.createKeyspace(); 
            //Create table in cassandra database 
            repository.createTable(); 

        } finally { 
            utils.close(); 
            LOGGER.info("Please delete your table after verifying the presence of the data in portal or from CQL"); 
        } 
    } 
}

Executar a aplicação

Abra uma linha de comandos ou janela de terminal. Cole o seguinte bloco de código.

Este código altera o diretório (cd) para o caminho da pasta onde criou o projeto. Em seguida, executa o comando mvn clean install para gerar o ficheiro cosmosdb-cassandra-examples.jar na pasta de destino. Por fim, executa a aplicação Java.
```
cd cassandra-demo

mvn clean install 

java -cp target/cosmosdb-cassandra-examples.jar com.azure.cosmosdb.cassandra.examples.UserProfile 
```
A janela de terminal apresenta notificações quando o keyspace e a tabela estão criados.
Agora, no portal do Azure, abra o Data Explorer para confirmar que o keyspace e a tabela foram criados.

Passos seguintes

Neste tutorial, aprendeu a criar uma API para uma conta do Cassandra no Azure Cosmos DB, numa base de dados e numa tabela com uma aplicação Java. Pode agora avançar para o artigo seguinte:

carregar dados de exemplo para a tabela API para Cassandra.