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

Artigo
08/15/2024

APLICA-SE A: Cassandra

Neste início rápido, você cria uma conta do Azure Cosmos DB para Apache Cassandra e usa um aplicativo Cassandra Java clonado do GitHub para criar um banco de dados e contêiner Cassandra usando os drivers Apache Cassandra v4.x 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, chave-valor e gráficos com recursos de distribuição global e escala horizontal.

Pré-requisitos

Uma conta do Azure com uma subscrição ativa. Crie um gratuitamente. Ou experimente o Azure Cosmos DB gratuitamente sem uma assinatura do Azure.
Kit de Desenvolvimento Java (JDK) 8. Aponte a variável JAVA_HOME de ambiente para a pasta onde o JDK está instalado.
Um arquivo binário 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 usa a versão 4 do driver Apache Cassandra de código aberto para Java. Na maioria dos casos, você deve ser capaz de conectar um aplicativo Java dependente do Apache Cassandra existente ao Azure Cosmos DB para Apache Cassandra sem nenhuma alteração no código existente. No entanto, recomendamos adicionar nossa extensão Java personalizada, que inclui políticas personalizadas de repetição e balanceamento de carga, bem como configurações de conexão recomendadas, para uma melhor experiência geral. Isso é para lidar com a limitação de taxa e failover de nível de aplicativo no Azure Cosmos DB quando necessário. Você 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.

A partir do menu do portal do Azure ou a partir da 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 seção Cassandra.

A API determina o tipo de conta a criar. O Azure Cosmos DB fornece cinco APIs: NoSQL para bancos de dados de documentos, Gremlin para bancos de dados gráficos, 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 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 Conta do Azure Cosmos DB, insira as configurações básicas para a nova conta do Azure Cosmos DB.

Definição	valor	Description
Subscrição	a sua subscrição	Selecione a subscrição do Azure que pretende utilizar para esta conta do Azure Cosmos DB.
Grupo de Recursos	Criar nova Em seguida, insira o mesmo nome que Nome da conta	Selecione Criar novo. Em seguida, insira um novo nome de grupo de recursos para sua conta. Para simplificar, use o mesmo nome que o nome da sua conta do Azure Cosmos DB.
Nome da Conta	Introduzir um nome exclusivo	Introduza um nome exclusivo para identificar a sua conta do Azure Cosmos DB. O URI da sua conta será cassandra.cosmos.azure.com anexado ao seu nome de conta exclusivo. O nome da conta pode usar apenas letras minúsculas, números e hífenes (-), e deve ter entre 3 e 31 caracteres.
Location	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	Taxa de transferência provisionada ou sem servidor	Selecione Taxa de transferência provisionada para criar uma conta no modo de taxa de transferência provisionada. Selecione Serverless para criar uma conta no modo serverless .
Aplicar desconto de nível gratuito do Azure Cosmos DB	Candidatar-se 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 esta opção para limitar a taxa de transferência da conta	Isso é útil se você quiser limitar a taxa de transferência total da conta a um valor específico.

Nota

Você pode ter até uma conta gratuita do Azure Cosmos DB por assinatura do Azure e deve optar por participar ao criar a conta. Se você não vir a opção de aplicar o desconto de nível gratuito, isso significa que outra conta na assinatura já foi habilitada com o nível gratuito.

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

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

Definição	valor	Description
Georredundância	Desativar	Habilite ou desative a distribuição global em sua conta emparelhando sua região com uma região par. Pode adicionar mais regiões à sua conta mais tarde.
Escritas de várias regiões	Desativar	O recurso de gravação em 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 Disponibilidade	Desativar	As Zonas de Disponibilidade são locais isolados dentro de uma 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 estarão disponíveis se você selecionar Serverless como o modo de Capacidade:

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

Opcionalmente, você pode configurar detalhes adicionais nas seguintes guias:
- Rede - Configure o acesso a partir de uma rede virtual.
- Política de backup - Configure a política de backup periódico ou contínuo .
- Criptografia - Use uma chave gerenciada pelo serviço ou uma chave gerenciada pelo cliente.
- Tags - As tags são pares nome/valor que permitem categorizar recursos e exibir o faturamento consolidado aplicando a mesma tag 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). Esses trechos são todos retirados do arquivo src/main/java/com/azure/cosmosdb/cassandra/util/CassandraUtils.java .

O CqlSession se conecta ao Azure Cosmos DB para Apache Cassandra e retorna uma sessão para acessar (Cluster objeto do driver v3 agora está obsoleto). Cassandra Host, Port, Nome de usuário e senha é definido 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 trechos a seguir são do arquivo src/main/java/com/azure/cosmosdb/cassandra/repository/UserRepository.java .

Solte o espaço de chave se ele 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 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);
}

Consulta para obter todas as informações do usuário.

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

Consulta para obter uma única informação de usuário.

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 Conexão.
Use o botão no lado direito da tela para copiar o valor CONTACT POINT.
Abra o arquivo config.properties na 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 agora deve ser semelhante a

cassandra_host=cosmos-db-quickstart.cassandra.cosmosdb.azure.com
Volte ao 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 agora deve ser semelhante a

cassandra_username=cosmos-db-quickstart
Volte ao 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 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> pelo local do certificado TLS/SSL. Se um valor não for fornecido, o certificado JDK instalado em <JAVA_HOME>/jre/lib/security/cacerts será usado.
Se você alterou a linha 6 para usar um certificado TLS/SSL específico, atualize a linha 7 para usar a senha 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

Isso ocorre porque o driver v.4x só permite que um DC local seja emparelhado com o ponto de contato. Se 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 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.

Pressione Ctrl+C para parar a execução do programa e fechar a janela do console.
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 monitora a taxa de transferência, o armazenamento, a disponibilidade, a latência e a consistência da sua conta do Azure Cosmos DB. Os gráficos para métricas associadas a um SLA (Service Level Agreement, 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 transparente o monitoramento de seus SLAs.

Para rever métricas e SLAs:

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

Clean up resources (Limpar recursos)

Quando terminar de usar seu aplicativo e sua conta do Azure Cosmos DB, você poderá excluir os recursos do Azure criados para não incorrer em mais cobranças. 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 você criou para este início rápido.
Na página Visão geral do grupo de recursos, selecione Excluir grupo de recursos.
Na janela seguinte, introduza o nome do grupo de recursos a eliminar e, em seguida, selecione Eliminar.

Próximos passos

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 contêiner Cassandra. Agora você pode importar dados adicionais para sua conta do Azure Cosmos DB.

Importar dados do Cassandra para o Azure Cosmos DB

Partilhar via

Guia de início rápido: criar um aplicativo Java para gerenciar dados do Azure Cosmos DB para Apache Cassandra (driver 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

Clean up resources (Limpar recursos)

Próximos passos

Comentários

Recursos adicionais