Guia de início rápido: biblioteca de cliente do Azure Cosmos DB para Apache Cassandra para Java

Introdução à biblioteca de cliente do Azure Cosmos DB para Apache Cassandra para Java para armazenar, gerenciar e consultar dados não estruturados. Siga as etapas neste guia para criar uma nova conta, instalar uma biblioteca de cliente Java, conectar-se à conta, executar operações comuns e consultar seus dados de exemplo finais.

Documentação de referência da API | Código fonte da biblioteca | Pacote (Maven)

Pré-requisitos

• Uma assinatura do Azure

  • Se não tiver uma subscrição do Azure, crie uma conta gratuita antes de começar.

• A versão mais recente da CLI do Azure no Azure Cloud Shell.

  • Se preferir executar comandos de referência da CLI localmente, entre na CLI do Azure usando o az login comando.

• Java 21 ou posterior

Preparação

Primeiro, configure a conta e o ambiente de desenvolvimento para este guia. Esta seção orienta você pelo processo de criação de uma conta, obtenção de suas credenciais e, em seguida, preparação do ambiente de desenvolvimento.

Criar uma conta

Comece criando uma API para a conta Apache Cassandra. Depois de criar a conta, crie o keyspace e os recursos de tabela.

Obter credenciais

Agora, obtenha a senha para a biblioteca do cliente usar para criar uma conexão com a conta criada recentemente.

Preparar o ambiente de desenvolvimento

Em seguida, configure seu ambiente de desenvolvimento com um novo projeto e a biblioteca do cliente. Esta etapa é o último pré-requisito necessário antes de passar para o resto deste guia.

1. Comece em um diretório vazio.

2. Gere um novo projeto de console Java usando o Maven.

   mvn archetype:generate -DgroupId=quickstart -DartifactId=console -DarchetypeArtifactId=maven-archetype-quickstart -DinteractiveMode=false
   

3. Importe o pacote java-driver-core do Maven. Adicione esta secção ao seu ficheiropom.xml .

   <dependency>
     <groupId>org.apache.cassandra</groupId>
     <artifactId>java-driver-core</artifactId>
     <version>[4.,)</version>
   </dependency>
   

4. Abra o arquivo /console/src/main/java/quickstart/App.java .

5. Observe o código padrão da aplicação Java existente.

   package quickstart;
   
   /**
    * Hello world!
    *
    */
   public class App 
   {
       public static void main( String[] args )
       {
           System.out.println( "Hello World!" );
       }
   }
   

6. Remova os comentários e a saída do console do código padrão. Este bloco de código é o ponto de partida para o restante deste guia.

   package quickstart;
   
   public class App 
   {
       public static void main(String[] args)
       {
       }
   }
   

7. Importar o namespace java.security.NoSuchAlgorithmException.

   import java.security.NoSuchAlgorithmException;
   

8. Atualize a assinatura do main método para indicar que ele pode lançar a NoSuchAlgorithmException exceção.

   public static void main(String[] args) throws NoSuchAlgorithmException
   {    
   }
   

   Importante

   As etapas restantes neste guia pressupõem que você está adicionando seu código dentro do main método.

9. Construa o projeto.

   mvn compile
   

Modelo de objeto

Exemplos de código

• Autenticar cliente
• Atualizar ou Inserir dados
• Ler dados
• Consultar dados

Autenticar cliente

Comece autenticando o cliente usando as credenciais reunidas anteriormente neste guia.

1. Abra o arquivo /console/src/main/java/quickstart/App.java em seu ambiente de desenvolvimento integrado (IDE).

2. Importe os seguintes tipos:

   • java.net.InetSocketAddress
   • javax.net.ssl.SSLContext
   • com.datastax.oss.driver.api.core.CqlIdentifier
   • com.datastax.oss.driver.api.core.CqlSession
   • com.datastax.oss.driver.api.core.cql.BoundStatement
   • com.datastax.oss.driver.api.core.cql.PreparedStatement
   • com.datastax.oss.driver.api.core.cql.ResultSet
   • com.datastax.oss.driver.api.core.cql.Row

   import java.net.InetSocketAddress;    
   
   import javax.net.ssl.SSLContext;
   
   import com.datastax.oss.driver.api.core.CqlIdentifier;
   import com.datastax.oss.driver.api.core.CqlSession;
   import com.datastax.oss.driver.api.core.cql.BoundStatement;
   import com.datastax.oss.driver.api.core.cql.PreparedStatement;
   import com.datastax.oss.driver.api.core.cql.ResultSet;
   import com.datastax.oss.driver.api.core.cql.Row;
   

3. Crie variáveis de cadeia de caracteres para as credenciais coletadas anteriormente neste guia. Nomeie as variáveis username, passworde contactPoint. Crie também uma variável de cadeia de caracteres nomeada region para o data center local.

   String username = "<username>";
   String password = "<password>";
   String contactPoint = "<contact-point>";
   

4. Crie outra variável de cadeia de caracteres para a região onde você criou sua conta do Azure Cosmos DB para Apache Cassandra. Nomeie esta variável region.

   String region = "<region>";
   

5. Crie um SSLContext objeto para garantir que você esteja usando o protocolo TLS (Transport Layer Security).

   SSLContext sslContext = SSLContext.getDefault();
   

6. Crie um novo CqlSession objeto usando as variáveis de credencial e configuração criadas nas etapas anteriores. Defina o ponto de contato, o data center local, as credenciais de autenticação, o espaço de chave e o contexto TLS (Transport Layer Security).

   CqlSession session = CqlSession.builder()
       .addContactPoint(new InetSocketAddress(contactPoint, 10350))
       .withLocalDatacenter(region)
       .withAuthCredentials(username, password)
       .withKeyspace(CqlIdentifier.fromCql("cosmicworks"))
       .withSslContext(sslContext)
       .build();
   

Atualizar ou inserir dados

Em seguida, atualize novos dados para uma tabela. A atualização garante que os dados sejam criados ou substituídos adequadamente, dependendo se os mesmos dados já existem na tabela.

1. Defina uma nova classe nomeada Product com campos correspondentes à tabela criada anteriormente neste guia.

   class Product {
       public String id;
       public String name;
       public String category;
       public int quantity;
       public boolean clearance;
   
       public Product(String id, String name, String category, int quantity, boolean clearance) {
           this.id = id;
           this.name = name;
           this.category = category;
           this.quantity = quantity;
           this.clearance = clearance;
       }
   
       @Override
       public String toString() {
           return String.format("Product{id='%s', name='%s', category='%s', quantity=%d, clearance=%b}",
                   id, name, category, quantity, clearance);
       }
   }
   

   Sugestão

   Em Java, você pode criar esse tipo em outro arquivo ou criá-lo no final do arquivo existente.

2. Crie um novo objeto do tipo Product. Armazene o objeto em uma variável chamada product.

   Product product = new Product(
       "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb",
       "Yamba Surfboard",
       "gear-surf-surfboards",
       12,
       false
   );
   

3. Crie uma nova variável de cadeia de caracteres nomeada insertQuery com a consulta Cassandra Query Language (CQL) para inserir uma nova linha.

   String insertQuery = "INSERT INTO product (id, name, category, quantity, clearance) VALUES (?, ?, ?, ?, ?)";
   

4. Prepare a instrução de inserção e vincule as propriedades do produto como parâmetros.

   PreparedStatement insertStmt = session.prepare(insertQuery);
   BoundStatement boundInsert = insertStmt.bind(
       product.id,
       product.name,
       product.category,
       product.quantity,
       product.clearance
   );
   

5. Atualize o produto executando a instrução vinculada.

   session.execute(boundInsert);
   

Ler dados

Em seguida, leia os dados que foram inseridos anteriormente na tabela.

1. Crie uma nova variável de cadeia de caracteres nomeada readQuery com uma consulta CQL que corresponda a itens com o mesmo id campo.

   String readQuery = "SELECT * FROM product WHERE id = ? LIMIT 1";
   

2. Crie uma variável de cadeia de caracteres nomeada id com o mesmo valor do produto criado anteriormente neste guia.

   String id = "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb";
   

3. Prepare a instrução e vincule o campo do produto id como parâmetro.

   PreparedStatement readStmt = session.prepare(readQuery);
   BoundStatement boundRead = readStmt.bind(id);
   

4. Execute a instrução bound e armazene o resultado em uma variável chamada readResult.

   ResultSet readResult = session.execute(boundRead);
   

5. Recupere a primeira linha do conjunto de resultados e mapeie-a para um Product objeto, se encontrado.

   Row row = readResult.one();
   Product matchedProduct = new Product(
       row.getString("id"),
       row.getString("name"),
       row.getString("category"),
       row.getInt("quantity"),
       row.getBoolean("clearance")
   );
   

Consultar dados

Agora, use uma consulta para localizar todos os dados que correspondem a um filtro específico na tabela.

1. Crie uma nova variável de cadeia de caracteres nomeada findQuery com uma consulta CQL que corresponda a itens com o mesmo category campo.

   String findQuery = "SELECT * FROM product WHERE category = ? ALLOW FILTERING";
   

2. Crie uma variável de cadeia de caracteres nomeada id com o mesmo valor do produto criado anteriormente neste guia.

   String category = "gear-surf-surfboards";
   

3. Prepare a instrução e vincule a categoria de produto como um parâmetro.

   PreparedStatement findStmt = session.prepare(findQuery);
   BoundStatement boundFind = findStmt.bind(category);
   

4. Execute a instrução bound e armazene o resultado em uma variável chamada findResults.

   ResultSet results = session.execute(boundFind);
   

5. Itere sobre os resultados da consulta e mapeie cada linha para um Product objeto.

   for (Row result : results) {
       Product queriedProduct = new Product(
           result.getString("id"),
           result.getString("name"),
           result.getString("category"),
           result.getInt("quantity"),
           result.getBoolean("clearance")
       );
       // Do something here with each result
   }
   

Fechar sessão

Em Java, é necessário fechar a sessão depois de concluir as consultas e operações.

session.close();

Execute o código

Execute o aplicativo recém-criado usando um terminal no diretório do aplicativo.

mvn compile
mvn exec:java -Dexec.mainClass="quickstart.App"

Limpeza de recursos

Agora, obtenha a senha para a biblioteca do cliente usar para criar uma conexão com a conta criada recentemente.

Próximo passo