Início Rápido: Criar uma aplicação Java para gerir dados do Azure Cosmos DB para Apache Cassandra (Controlador v4)

Artigo
03/22/2023

APLICA-SE A: Cassandra

Neste início rápido, vai criar uma conta do Azure Cosmos DB para Apache Cassandra e utilizar uma aplicação Java para Cassandra clonada a partir do GitHub para criar uma base de dados e um contentor do Cassandra com os controladores do Apache Cassandra v4.x para Java. O Azure Cosmos DB é um serviço de base de dados com vários modelos que lhe permite criar e consultar rapidamente bases de dados de documentos, tabelas, chaves-valor e grafos com capacidades de distribuição global e dimensionamento horizontal.

Pré-requisitos

Uma conta do Azure com uma subscrição ativa. Crie uma gratuitamente. Em alternativa, experimente o Azure Cosmos DB gratuitamente sem uma subscrição do Azure.
Java Development Kit (JDK) 8. Aponte a JAVA_HOME variável de ambiente para a pasta onde o JDK está instalado.
Um arquivo binário do Maven. No Ubuntu, execute apt-get install maven para instalar o Maven.
Git. No Ubuntu, execute sudo apt-get install git para instalar o Git.

Nota

Este é um início rápido simples que utiliza a versão 4 do controlador Apache Cassandra open source para Java. Na maioria dos casos, deve conseguir ligar uma aplicação Java dependente do Apache Cassandra existente ao Azure Cosmos DB para Apache Cassandra sem quaisquer alterações ao código existente. No entanto, recomendamos que adicione a nossa extensão Java personalizada, que inclui políticas personalizadas de repetição e balanceamento de carga, bem como definições de ligação recomendadas, para uma melhor experiência geral. Isto serve para processar a limitação de taxa e a ativação pós-falha ao nível da aplicação no Azure Cosmos DB, sempre que necessário. Pode encontrar um exemplo abrangente que implementa a extensão aqui.

Criar uma conta de base de dados

Antes de poder criar uma base de dados de documentos, tem de criar uma conta do Cassandra com o Azure Cosmos DB.

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.

Clonar a aplicação de exemplo

Agora, vamos trabalhar com código. Vamos clonar uma aplicação do Cassandra a partir do GitHub, definir a cadeia de ligação e executá-la. Vai ver como é fácil trabalhar com dados programaticamente.

Abra uma linha de comandos. Crie uma nova pasta com o nome git-samples. Em seguida, feche a linha de comandos.
```
md "C:\git-samples"
```
Abra uma janela de terminal do git, como o git bash e utilize o comando cd para alterar para uma nova pasta e instalar a aplicação de exemplo.
```
cd "C:\git-samples"
```
Execute o seguinte comando para clonar o repositório de exemplo. Este comando cria uma cópia da aplicação de exemplo no seu computador.
```
git clone https://github.com/Azure-Samples/azure-cosmos-db-cassandra-java-getting-started-v4.git
```

Rever o código

Este passo é opcional. Se estiver interessado em saber de que forma o código cria os recursos da base de dados, pode rever os fragmentos seguintes. Caso contrário, pode avançar diretamente para Update your connection string (Atualizar a cadeia de ligação). Estes fragmentos são retirados do ficheiro src/main/java/com/azure/cosmosdb/cassandra/util/CassandraUtils.java .

O CqlSession liga ao Azure Cosmos DB para Apache Cassandra e devolve uma sessão para aceder (Cluster o objeto do controlador v3 é agora obsoleto). O Anfitrião, a Porta, o Nome de utilizador e a palavra-passe do Cassandra são definidos através da página da cadeia de ligação no portal do Azure.
```
    this.session = CqlSession.builder().withSslContext(sc)
            .addContactPoint(new InetSocketAddress(cassandraHost, cassandraPort)).withLocalDatacenter(region)
            .withAuthCredentials(cassandraUsername, cassandraPassword).build();
```

Os fragmentos seguintes são do ficheiro src/main/java/com/azure/cosmosdb/cassandra/repository/UserRepository.java .

Remova o espaço de chaves se já existir de uma execução anterior.

public void dropKeyspace() {
    String query = "DROP KEYSPACE IF EXISTS "+keyspace+"";
    session.execute(query);
    LOGGER.info("dropped keyspace '"+keyspace+"'");
}

É criado um novo keyspace.

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

É criada uma nova tabela.

  public void createTable() {
      String query = "CREATE TABLE "+keyspace+"."+table+" (user_id int PRIMARY KEY, user_name text, user_bcity text)";
      session.execute(query);
      LOGGER.info("Created table '"+table+"'");
  }

As entidades de utilizador são inseridas com um objeto de instrução preparado.

public String prepareInsertStatement() {
    final String insertStatement = "INSERT INTO  "+keyspace+"."+table+" (user_id, user_name , user_bcity) VALUES (?,?,?)";
    return insertStatement;
}

public void insertUser(String preparedStatement, int id, String name, String city) {
    PreparedStatement prepared = session.prepare(preparedStatement);
    BoundStatement bound = prepared.bind(id, city, name).setIdempotent(true);
    session.execute(bound);
}

Consulte para obter todas as informações do Utilizador.

public void selectAllUsers() {
    final String query = "SELECT * FROM "+keyspace+"."+table+"";
    List<Row> rows = session.execute(query).all();

    for (Row row : rows) {
        LOGGER.info("Obtained row: {} | {} | {} ", row.getInt("user_id"), row.getString("user_name"), row.getString("user_bcity"));
    }
}

Consulte para obter uma única informação do Utilizador.

public void selectUser(int id) {
    final String query = "SELECT * FROM "+keyspace+"."+table+" where user_id = 3";
    Row row = session.execute(query).one();

    LOGGER.info("Obtained row: {} | {} | {} ", row.getInt("user_id"), row.getString("user_name"), row.getString("user_bcity"));
}

Atualizar a cadeia de ligação

Agora, regresse ao portal do Azure para obter as informações da cadeia de ligação e copie-as para a aplicação. Os detalhes da cadeia de ligação permitem que a aplicação comunique com a base de dados alojada.

Na sua conta do Azure Cosmos DB no portal do Azure, selecione Cadeia de Ligação.
Utilize o botão no lado direito do ecrã para copiar o valor DE PONTO DE CONTACTO.
Abra o ficheiro config.properties a partir da pasta C:\git-samples\azure-cosmosdb-cassandra-java-getting-started\java-examples\src\main\resources .
Cole o valor do PONTO DE CONTACTO do portal em <Cassandra endpoint host> na linha 2.

A linha 2 de config.properties deve agora ter um aspeto semelhante a

cassandra_host=cosmos-db-quickstart.cassandra.cosmosdb.azure.com
Voltar para o portal e copie o valor USERNAME. Cole o valor do NOME DE UTILIZADOR do portal em <cassandra endpoint username> na linha 4.

A linha 4 de config.properties deve agora ter um aspeto semelhante a

cassandra_username=cosmos-db-quickstart
Voltar para o portal e copie o valor PASSWORD. Cole o valor da PALAVRA-PASSE do portal em <cassandra endpoint password> na linha 5.

A linha 5 de config.properties deve agora ter um aspeto semelhante a

cassandra_password=2Ggkr662ifxz2Mg...==
Na linha 6, se quiser utilizar um certificado TLS/SSL específico, substitua <SSL key store file location> pela localização do certificado TLS/SSL. Se não for fornecido um valor, é utilizado o certificado JDK instalado em <JAVA_HOME>/jre/lib/security/cacerts.
Se alterou a linha 6 para utilizar um certificado TLS/SSL específico, atualize a linha 7 para utilizar a palavra-passe desse certificado.
Tenha em atenção que terá de adicionar a região predefinida (por exemplo, West US) para o ponto de contacto, por exemplo,

region=West US

Isto acontece porque o controlador v.4x só permite que um DC local seja emparelhado com o ponto de contacto. Se quiser adicionar uma região diferente da predefinição (que é a região que foi fornecida quando a conta do Azure Cosmos DB foi criada pela primeira vez), terá de utilizar o sufixo regional ao adicionar um ponto de contacto, por exemplo, host-westus.cassandra.cosmos.azure.com.
Guarde o ficheiro config.properties .

Executar a aplicação Java

Na janela de terminal do git, cd para a pasta azure-cosmosdb-cassandra-java-getting-started-v4.
```
cd "C:\git-samples\azure-cosmosdb-cassandra-java-getting-started-v4"
```
Na janela de terminal do git, utilize o comando seguinte para gerar o ficheiro cosmosdb-cassandra-examples.jar.
```
mvn clean install
```
Na janela de terminal do git, execute o seguinte comando para iniciar a aplicação do Java.
```
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. A seguir, seleciona e devolve todos os utilizadores da tabela e apresenta a saída e, em seguida, seleciona uma linha por ID e apresenta o valor.

Prima Ctrl+C para parar a execução do programa e fechar a janela da consola.
No portal do Azure, abra o Data Explorer para consultar, modificar e trabalhar com estes dados novos.

Rever os SLAs no portal do Azure

O portal do Azure monitoriza o débito, o armazenamento, a disponibilidade, a latência e a consistência da conta do Azure Cosmos DB. Os gráficos para métricas associadas a um Contrato de Nível de Serviço (SLA) do Azure Cosmos DB mostram o valor do SLA em comparação com o desempenho real. Este conjunto de métricas torna a monitorização dos SLAs transparente.

Para rever as métricas e os SLAs:

Selecione Métricas no menu de navegação da sua conta do Azure Cosmos DB.
Selecione um separador, como Latência, e selecione um período de tempo à direita. Compare as linhas Real e SLA nos gráficos.
Reveja as métricas nos outros separadores.

Limpar os recursos

Quando terminar a aplicação e a conta do Azure Cosmos DB, pode eliminar os recursos do Azure que criou para não incorrer em mais custos. Para eliminar os recursos:

Na barra de Pesquisa do portal do Azure, procure e selecione Grupos de recursos.
Na lista, selecione o grupo de recursos que criou para este início rápido.
Na página Descrição geral do grupo de recursos, selecione Eliminar grupo de recursos.
Na janela seguinte, introduza o nome do grupo de recursos a eliminar e, em seguida, selecione Eliminar.

Passos seguintes

Neste início rápido, aprendeu a criar uma conta do Azure Cosmos DB com a API para Cassandra e a executar uma aplicação Java para Cassandra que cria uma base de dados e um contentor do Cassandra. Agora pode importar dados adicionais para a sua conta do Azure Cosmos DB.

Importar dados do Cassandra para o Azure Cosmos DB

Início Rápido: Criar uma aplicação Java para gerir dados do Azure Cosmos DB para Apache Cassandra (Controlador v4)

Pré-requisitos

Criar uma conta de base de dados

Clonar a aplicação de exemplo

Rever o código

Atualizar a cadeia de ligação

Executar a aplicação Java

Rever os SLAs no portal do Azure

Limpar os recursos

Passos seguintes

Recursos adicionais