Início rápido: criar um aplicativo Java para gerenciar dados do Azure Cosmos DB for Apache Cassandra (driver v4)

Artigo
08/15/2024

APLICA-SE AO: Cassandra

Neste início rápido, você cria uma conta do Azure Cosmos DB for Apache Cassandra e usa um aplicativo Cassandra Java clonado do GitHub para criar um banco de dados e um contêiner Cassandra usando os drivers v4.x Apache Cassandra para Java. O Azure Cosmos DB é um serviço de banco de dados multimodelo que permite criar e consultar rapidamente bancos de dados de documentos, tabelas, pares chave-valor e grafo com funcionalidades de escala horizontal e distribuição global.

Pré-requisitos

Uma conta do Azure com uma assinatura ativa. Crie um gratuitamente. Ou então experimente o Azure Cosmos DB gratuitamente sem uma assinatura do Azure.
JDK (Java Development Kit) 8. Aponte a variável de ambiente JAVA_HOME para a pasta em que 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.

Observação

Este é um início rápido simples que usa a versão 4 do driver do Apache Cassandra de software livre para Java. Na maioria dos casos, você deve conseguir conectar um aplicativo Java dependente do Apache Cassandra existente ao Azure Cosmos DB for Apache Cassandra sem nenhuma alteração no código existente. No entanto, recomendamos a adição da extensão Java personalizada, que inclui políticas personalizadas de nova tentativa e de balanceamento de carga, bem como as configurações de conexão recomendadas, para aprimorar a experiência geral. Assim é possível lidar com a limitação de taxa e o failover no nível do aplicativo no Azure Cosmos DB quando necessário. Veja aqui um exemplo abrangente que implementa a extensão.

Criar uma conta de banco de dados

Antes de criar um banco de dados de documentos, você precisa criar uma conta Cassandra com o Azure Cosmos DB.

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

A API determina o tipo de conta a ser criada. O Azure Cosmos DB oferece cinco APIs: NoSQL para bancos de dados de documentos, Gremlin para bancos de dados de grafo, MongoDB para bancos de dados de documentos, Tabela do Azure e Cassandra. Você deve criar uma conta separada para cada API.

Selecione Cassandra, porque neste guia de início rápido você está criando uma tabela que funciona com a API para Cassandra.

Saiba mais sobre a API para Cassandra.

Na página Criar uma Conta do Azure Cosmos DB, insira as configurações básicas da nova conta do Azure Cosmos DB.

Configuração	Valor	Descrição
Subscription	Sua assinatura	Selecione a assinatura do Azure que você deseja usar para essa conta do Azure Cosmos DB.
Grupo de recursos	Create new Em seguida, digite o mesmo nome que o Nome da Conta	Selecione Criar novo. Em seguida, insira um novo nome de grupo de recursos para a conta. Para simplificar, use o mesmo nome que o Nome da Conta do Azure Cosmos DB.
Nome da Conta	Insira um nome exclusivo	Insira um nome exclusivo para identificar a conta do Azure Cosmos DB. O URI da sua conta será cassandra.cosmos.azure.com acrescentado ao nome da conta exclusivo. O nome da conta pode usar apenas letras minúsculas, números e hifens (-) e deve ter de 3 a 31 caracteres.
Location	A região mais próxima dos usuários	Selecione uma localização geográfica para hospedar a sua conta do Azure Cosmos DB. Use a localização mais próxima dos usuários para fornecer a eles acesso mais rápido aos dados.
Modo de capacidade	Taxa de transferência provisionada ou sem servidor	Selecione Taxa de transferência provisionada para criar uma conta no modo taxa de transferência provisionada. Selecione Sem servidor para criar uma conta no modo sem servidor.
Aplicar o desconto por nível gratuito do Azure Cosmos DB	Aplicar ou Não aplicar	Com o nível gratuito do Azure Cosmos DB, você receberá os primeiros 1000 RU/s e 25 GB de armazenamento gratuitamente em uma conta. Saiba mais sobre o nível gratuito.
Limitar a taxa de transferência total da conta	Selecione para limitar a taxa de transferência da conta	Isso será útil se você quiser limitar a taxa de transferência total da conta a um valor específico.

Observação

Você pode ter no máximo uma conta do nível gratuito do Azure Cosmos DB por assinatura do Azure e deve aceitar ao criar a conta. Se você não vir a opção de aplicar o desconto por nível gratuito, significa que outra conta da assinatura já foi habilitada com o nível gratuito.

A página da nova conta do Azure Cosmos DB for Apache Cassandra

Na guia Distribuição global, configure os detalhes a seguir. Você pode deixar os valores padrão para a finalidade deste guia de início rápido:

Configuração	Valor	Descrição
Redundância geográfica	Desabilitar	Habilite ou desabilite a distribuição global em sua conta emparelhando sua região com uma região de par. Você poderá adicionar mais regiões à sua conta posteriormente.
Gravações de várias regiões	Desabilitar	A capacidade de gravação de várias regiões permite que você aproveite a taxa de transferência provisionada para seus bancos de dados e contêineres em todo o mundo.
Zonas de Disponibilidades	Desabilitar	As Zonas de Disponibilidade são localizações isoladas exclusivas em uma região do Azure. Cada zona é composta por um ou mais datacenters equipados com energia, resfriamento e rede independentes.

Observação

As seguintes opções não estarão disponíveis se você selecionar Sem servidor como Modo de capacidade:

Aplicar desconto por nível gratuito
Redundância geográfica
Gravações de várias regiões

Opcionalmente, você pode configurar detalhes adicionais nas seguintes guias:
- Rede – configurar o acesso de uma rede virtual.
- Política de Backup – configurar a política de backup periódica ou contínua.
- Criptografia – use a chave gerenciada por serviço ou uma chave gerenciada pelo cliente.
- Marcas – marcas são pares nome/valor que permitem categorizar recursos e exibir a cobrança consolidada por meio da aplicação da mesma marca a vários recursos e grupos de recursos.
Selecione Examinar + criar.
Examine as configurações da conta e selecione Criar. São necessários alguns minutos para criar a conta. Aguarde até que a página do portal exiba Sua implantação está concluída.
Selecione Ir para recurso para ir para a página da conta do Azure Cosmos DB.

Clonar o aplicativo de exemplo

Agora, vamos trabalhar com o código. Agora vamos clonar um aplicativo do Cassandra do GitHub, definir a cadeia de conexão e executá-lo. Você verá como é fácil trabalhar usando dados de forma programática.

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

Examine o código

Esta etapa é opcional. Se você estiver interessado em aprender como o código cria os recursos de banco de dados,examine os snippets a seguir. Caso contrário, você poderá pular para Atualizar sua cadeia de conexão. Esses snippets são extraídos do arquivo src/main/java/com/azure/cosmosdb/cassandra/util/CassandraUtils.java.

O CqlSession se conecta ao Azure Cosmos DB for Apache Cassandra e retorna uma sessão para acessar (o objeto Cluster do driver v3 agora está obsoleto). O host, a porta e a senha e o nome de usuário do Cassandra são definidos usando a página de cadeia de conexão no portal do Azure.
```
    this.session = CqlSession.builder().withSslContext(sc)
            .addContactPoint(new InetSocketAddress(cassandraHost, cassandraPort)).withLocalDatacenter(region)
            .withAuthCredentials(cassandraUsername, cassandraPassword).build();
```

Os snippets de código a seguir são do arquivo src/main/java/com/azure/cosmosdb/cassandra/repository/UserRepository.java.

Remova o keyspace se ele já existir em uma execução anterior.

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

Um novo keyspace é criado.

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

Uma nova tabela é criada.

  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+"'");
  }

Entidades de usuário são inseridas usando 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 as informações de todos os usuários.

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 informações de um usuário único.

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 sua cadeia de conexão

Agora, volte ao portal do Azure para obter informações sobre a cadeia de conexão e copiá-las para o aplicativo. Os detalhes da cadeia de conexão permitem que o aplicativo se comunique com o banco de dados hospedado.

Em sua conta do Azure Cosmos DB no portal do Azure, selecione Cadeia de Conexão.
Use o botão no lado direito da tela para copiar o valor do PONTO DE CONTATO.
Abra o arquivo config.properties da pasta C:\git-samples\azure-cosmosdb-cassandra-java-getting-started\java-examples\src\main\resources.
Cole o valor do PONTO DE CONTATO do portal sobre <Cassandra endpoint host> na linha 2.

A linha 2 do config.properties agora deve ser semelhante a

cassandra_host=cosmos-db-quickstart.cassandra.cosmosdb.azure.com
Volte ao portal e copie o valor do NOME DE USUÁRIO. Cole o valor do NOME DE USUÁRIO do portal sobre <cassandra endpoint username> na linha 4.

A linha 4 do config.properties agora deve ser semelhante a

cassandra_username=cosmos-db-quickstart
Volte ao portal e copie o valor da SENHA. Cole o valor da SENHA do portal sobre <cassandra endpoint password> na linha 5.

A linha 5 do config.properties agora deve ser semelhante a

cassandra_password=2Ggkr662ifxz2Mg...==
Na linha 6, se você quiser usar um certificado TLS/SSL específico, substitua <SSL key store file location> pela localização do certificado TLS/SSL. Se um valor não for fornecido, será usado o certificado JDK instalado em <JAVA_HOME>/jre/lib/security/cacerts.
Se você alterou a linha 6 para usar um certificado TLS/SSL específico, atualize a linha 7 para usar a senha desse certificado.
Observe que será necessário adicionar a região padrão (por exemplo, West US) para o ponto de contato, por exemplo,

region=West US

Isso ocorre porque o driver v.4x permite que apenas um DC local seja emparelhado com o ponto de contato. Se você quiser adicionar uma região diferente do padrão (que é a região que foi fornecida quando a conta do Azure Cosmos DB foi criada pela primeira vez), você precisará usar o sufixo regional ao adicionar o ponto de contato, por exemplo, host-westus.cassandra.cosmos.azure.com.
Salve o arquivo config.properties.

Executar o aplicativo Java

Na janela do terminal do Git, execute cd na pasta azure-cosmosdb-cassandra-java-getting-started-v4.
```
cd "C:\git-samples\azure-cosmosdb-cassandra-java-getting-started-v4"
```
Na janela do terminal do Git, use o seguinte comando para gerar o arquivo cosmosdb-cassandra-examples.jar.
```
mvn clean install
```
Na janela do terminal git, execute os comandos a seguir para iniciar o aplicativo Java.
```
java -cp target/cosmosdb-cassandra-examples.jar com.azure.cosmosdb.cassandra.examples.UserProfile
```
A janela do terminal exibe notificações de que o keyspace e a tabela foram criados. Em seguida, todos os usuários na tabela são selecionados e retornados, e é exibida a saída. Depois, é selecionada uma linha por ID, e o valor é exibido.

Pressione Ctrl+C para interromper a execução do programa e feche a janela do console.
No portal do Azure, abra Data Explorer para consultar, modificar e trabalhar com esses novos dados.

Examinar SLAs no Portal do Azure

O portal do Azure monitora a taxa de transferência, armazenamento, disponibilidade, latência e consistência da sua conta do Azure Cosmos DB. Gráficos de métricas associados a um SLA (Contrato de Nível de Serviço) do Azure Cosmos DB mostram o valor do SLA em comparação com o desempenho real. Esse conjunto de métricas torna o monitoramento dos SLAs transparente.

Para examinar as métricas e os SLAs:

Selecione Métricas no menu de navegação da conta do Azure Cosmos DB.
Selecione uma guia, tal como Latência, e selecione um período à direita. Comparar as linhas Real e SLA dos gráficos.
Examine as métricas nas outras guias.

Limpar os recursos

Quando o aplicativo e a conta do Azure Cosmos DB estiverem prontos, você poderá excluir os recursos do Azure criados para não incorrer em mais cobranças. Para excluir os recursos:

Na barra de pesquisa do portal do Azure, procure e selecione Grupos de recursos.
Na lista, selecione o grupo de recursos criado neste início rápido.
Na página Visão geral do grupo de recursos, selecione Excluir grupo de recursos.
Na próxima janela, insira o nome do grupo de recursos a ser excluído e selecione Excluir.

Próximas etapas

Neste início rápido, você aprendeu como criar uma conta do Azure Cosmos DB com API para Cassandra e executar um aplicativo Cassandra Java que cria um banco de dados e um contêiner Cassandra. Agora, é possível importar outros dados para sua conta do Azure Cosmos DB.

Importar dados do Cassandra para o Azure Cosmos DB

Compartilhar via

Início rápido: criar um aplicativo Java para gerenciar dados do Azure Cosmos DB for Apache Cassandra (driver v4)

Pré-requisitos

Criar uma conta de banco de dados

Clonar o aplicativo de exemplo

Examine o código

Atualizar sua cadeia de conexão

Executar o aplicativo Java

Examinar SLAs no Portal do Azure

Limpar os recursos

Próximas etapas

Comentários

Recursos adicionais