Guia de Início Rápido: Biblioteca cliente do Azure Cosmos DB para Apache Cassandra em Java

Aplica-se a: ✅ Apache Cassanda

Introdução à biblioteca de clientes 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 clientes 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 você não tiver uma assinatura do Azure, crie uma conta gratuita antes de começar.

A versão mais recente da CLI do Azure no Azure Cloud Shell.
- Se você preferir executar comandos de referência da CLI localmente, entre na CLI do Azure usando o az login comando.

Java 21 ou posterior

Configurando

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, obtendo suas credenciais e, em seguida, preparando seu ambiente de desenvolvimento.

Criar uma conta

Comece criando uma conta da API para Apache Cassandra. Depois que a conta for criada, crie o keyspace e os recursos da tabela.

Azure CLI
Portal do Azure

Se você ainda não tiver um grupo de recursos de destino, use o az group create comando para criar um novo grupo de recursos em sua assinatura.
```
az group create \
    --name "<resource-group-name>" \
    --location "<location>"
```

Use o az cosmosdb create comando para criar uma nova conta do Azure Cosmos DB para Apache Cassandra com configurações padrão.

az cosmosdb create \
    --resource-group "<resource-group-name>" \
    --name "<account-name>" \
    --locations "regionName=<location>" \
    --capabilities "EnableCassandra"

Criar um novo keyspace usando az cosmosdb cassandra keyspace create com o nome cosmicworks.

az cosmosdb cassandra keyspace create \
    --resource-group "<resource-group-name>" \
    --account-name "<account-name>" \
    --name "cosmicworks"

Crie um novo objeto JSON para representar seu esquema usando um comando Bash de várias linhas. Em seguida, use o az cosmosdb cassandra table create comando para criar uma nova tabela chamada products.

schemaJson=$(cat <<EOF
{
  "columns": [
    {
      "name": "id",
      "type": "text"
    },
    {
      "name": "name",
      "type": "text"
    },
    {
      "name": "category",
      "type": "text"
    },
    {
      "name": "quantity",
      "type": "int"
    },
    {
      "name": "price",
      "type": "decimal"
    },
    {
      "name": "clearance",
      "type": "boolean"
    }
  ],
  "partitionKeys": [
    {
      "name": "id"
    }
  ]
}
EOF
)

az cosmosdb cassandra table create \
    --resource-group "<resource-group-name>" \
    --account-name "<account-name>" \
    --keyspace-name "cosmicworks" \
    --name "product" \
    --schema "$schemaJson"

Entre no portal do Azure (https://portal.azure.com).
Insira o Azure Cosmos DB na barra de pesquisa global.
Em Serviços, selecione Azure Cosmos DB.
No painel do Azure Cosmos DB , selecione Criar e, em seguida, Azure Cosmos DB para Apache Cassandra na guia Outros .
Selecione a conta de banco de dados RU (Unidade de Solicitação) para o tipo de conta.

No painel Noções básicas, configure as seguintes opções e, em seguida, escolha Revisar + criar:

	Valor
Tipo de carga de trabalho	Aprendizagem
Subscrição	Selecione sua Assinatura do Azure.
Grupo de Recursos	Crie um novo grupo de recursos ou escolha um grupo de recursos existente
Nome da Conta	Forneça um nome global exclusivo
zonas de disponibilidade	Desabilitar
Localidade	Escolha uma região do Azure compatível com sua assinatura

Dica

Você pode deixar as opções não especificadas com os valores padrão. Você também pode configurar a conta para limitar a taxa de transferência total da conta a 1.000 unidades de solicitação por segundo (RU/s) ou habilitar a camada gratuita para minimizar seus custos.

No painel Revisar + criar , aguarde a conclusão bem-sucedida da validação da conta e escolha Criar.
O portal navega automaticamente para o painel Implantação. Aguarde até que a implantação seja concluída.
Depois que a implantação for concluída, selecione Ir para o recurso para navegar até a nova conta da API para Apache Cassandra.
No menu de recursos, selecione a opção Data Explorer .
No Data Explorer, selecione + Nova Tabela.

Na caixa de diálogo Adicionar Tabela , configure as seguintes opções e selecione OK:

	Valor
Keyspace	Criar novo
Nome do Keyspace	`cosmicworks`
Nome da tabela	`product`
Esquema de tabela	`(id text, name text, category text, quantity int, price decimal, clearance boolean, PRIMARY KEY (id))`

Dica

Você pode deixar as opções não especificadas com os valores padrão.

Obter credenciais

Agora, obtenha a senha da biblioteca de clientes a ser usada para criar uma conexão com a conta criada recentemente.

Azure CLI
Portal do Azure

Use az cosmosdb show para obter o ponto de contato e o nome de usuário da conta.

az cosmosdb show \
    --resource-group "<resource-group-name>" \
    --name "<account-name>" \
    --query "{username:name,contactPoint:documentEndpoint}"

Registre o valor das propriedades contactPoint e username da saída dos comandos anteriores. Os valores dessas propriedades são o ponto de contato e o nome de usuário que você usará posteriormente neste guia para se conectar à conta com a biblioteca.

Use az cosmosdb keys list para obter as chaves da conta.

az cosmosdb keys list \
    --resource-group "<resource-group-name>" \
    --name "<account-name>" \
    --type "keys"

Anote o valor da propriedade primaryMasterKey na saída dos comandos anteriores. O valor dessa propriedade é a senha que você usará posteriormente neste guia para se conectar à conta com a biblioteca.

Prepare o ambiente de desenvolvimento

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

Inicie em um diretório vazio.

Gere um novo projeto de console Java usando o Maven.

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

Importe o pacote java-driver-core do Maven. Adicione esta seção ao arquivo pom.xml .

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

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

Observe a clichê do aplicativo Java existente.

package quickstart;

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

Remova os comentários e a saída do console da clichê. Esse bloco de código é o ponto de partida para o restante deste guia.
```
package quickstart;

public class App 
{
    public static void main(String[] args)
    {
    }
}
```
Importe o java.security.NoSuchAlgorithmException namespace.
```
import java.security.NoSuchAlgorithmException;
```
Atualize a assinatura do método main para indicar que ela pode lançar a exceção NoSuchAlgorithmException.
```
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.
Compile o projeto.
```
mvn compile
```

Modelo de objeto

	Descrição
`CqlSession`	Representa uma conexão específica com um cluster
`PreparedStatement`	Representa uma instrução CQL pré-compilada que pode ser executada várias vezes com eficiência
`BoundStatement`	Representa uma instrução preparada com parâmetros associados
`Row`	Representa uma única linha de um resultado de consulta

Autenticar cliente

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

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

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;

Crie variáveis de cadeia de caracteres para as credenciais coletadas anteriormente neste guia. Nomeie as variáveis usernamee passwordcontactPoint. 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>";
```
Crie outra variável de cadeia de caracteres para a região em que você criou sua conta do Azure Cosmos DB para Apache Cassandra. Nomeie essa variável region.
```
String region = "<region>";
```
Crie um SSLContext objeto para garantir que você esteja usando o protocolo TLS (segurança da camada de transporte).
```
SSLContext sslContext = SSLContext.getDefault();
```

Crie um novo CqlSession objeto usando as variáveis de configuração e credencial criadas nas etapas anteriores. Defina o ponto de contato, o data center local, as credenciais de autenticação, o keyspace 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();

Aviso

A validação completa da TLS (segurança da camada de transporte) está desabilitada neste guia para simplificar a autenticação. Para implantações de produção, habilite totalmente a validação.

Inserir ou atualizar dados

Em seguida, insira novos dados em uma tabela. O upserting garante que os dados sejam criados ou substituídos adequadamente, dependendo se os mesmos dados já existem na tabela.

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

Dica

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

Criar 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
);

Crie uma nova variável de cadeia de caracteres nomeada insertQuery com a consulta CQL (Cassandra Query Language) para inserir uma nova linha.
```
String insertQuery = "INSERT INTO product (id, name, category, quantity, clearance) VALUES (?, ?, ?, ?, ?)";
```

Prepare a instrução de inserção e associe 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
);

Insira o produto executando a instrução associada.
```
session.execute(boundInsert);
```

Ler dados

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

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";
```
Crie uma variável de cadeia de caracteres nomeada id com o mesmo valor que o produto criado anteriormente neste guia.
```
String id = "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb";
```

Prepare a declaração e associe o campo id do produto como um parâmetro.

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

Execute a instrução associada e armazene o resultado em uma variável chamada readResult.
```
ResultSet readResult = session.execute(boundRead);
```

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.

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";
```
Crie uma variável de cadeia de caracteres nomeada id com o mesmo valor que o produto criado anteriormente neste guia.
```
String category = "gear-surf-surfboards";
```

Prepare a instrução e associe a categoria do produto como um parâmetro.

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

Execute a instrução associada e armazene o resultado em uma variável chamada findResults.
```
ResultSet results = session.execute(boundFind);
```

Iterar sobre os resultados da consulta e mapear cada linha para um objeto Product.

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

No Java, você precisará fechar a sessão depois de terminar as consultas e operações.

session.close();

Executar 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"

Dica

Verifique se você está executando esse comando no caminho /console criado neste guia.

Limpar os recursos

Agora, obtenha a senha da biblioteca de clientes a ser usada para criar uma conexão com a conta criada recentemente.

Azure CLI
Portal do Azure

Use az cosmosdb show para obter o ponto de contato e o nome de usuário da conta.

az cosmosdb show \
    --resource-group "<resource-group-name>" \
    --name "<account-name>" \
    --query "{username:name,contactPoint:documentEndpoint}"

Registre o valor das propriedades contactPoint e username da saída dos comandos anteriores. Os valores dessas propriedades são o ponto de contato e o nome de usuário que você usará posteriormente neste guia para se conectar à conta com a biblioteca.

Use az cosmosdb keys list para obter as chaves da conta.

az cosmosdb keys list \
    --resource-group "<resource-group-name>" \
    --name "<account-name>" \
    --type "keys"

Anote o valor da propriedade primaryMasterKey na saída dos comandos anteriores. O valor dessa propriedade é a senha que você usará posteriormente neste guia para se conectar à conta com a biblioteca.

Próxima etapa

Visão geral do Azure Cosmos DB para Apache Cassandra

Comentários

Esta página foi útil?

Last updated on 2025-07-22

Compartilhar via

Guia de Início Rápido: Biblioteca cliente do Azure Cosmos DB para Apache Cassandra em Java

Pré-requisitos

Configurando

Criar uma conta

Obter credenciais

Prepare o ambiente de desenvolvimento

Modelo de objeto

Exemplos de código

Autenticar cliente

Inserir ou atualizar dados

Ler dados

Consultar dados

Fechar sessão

Executar o código

Limpar os recursos

Próxima etapa

Comentários

Recursos adicionais