Inicio rápido: Biblioteca cliente de Azure Cosmos DB para Apache Cassandra para Java

Se aplica a: ✅ Apache Cassanda

Introducción a la biblioteca cliente de Azure Cosmos DB para Apache Cassandra para Java para almacenar, administrar y consultar datos no estructurados. Siga los pasos de esta guía para crear una nueva cuenta, instalar una biblioteca cliente de Java, conectarse a la cuenta, realizar operaciones comunes y consultar los datos de ejemplo finales.

Documentación de referencia de API | Código fuente de la biblioteca | Paquete (Maven)

Prerrequisitos

Una suscripción de Azure
- Si no tiene una suscripción a Azure, cree una cuenta gratuita antes de empezar.

La versión más reciente de Azure CLI en Azure Cloud Shell.
- Si prefiere ejecutar comandos de referencia de la CLI localmente, inicie sesión en la CLI de Azure mediante el az login comando .

Java 21 o posterior

Instalación

Primero, configure la cuenta y el entorno de desarrollo para esta guía. En esta sección se explica el proceso de creación de una cuenta, la obtención de sus credenciales y la preparación del entorno de desarrollo.

Crear una cuenta

Empiece por crear una API para una cuenta de Apache Cassandra. Una vez creada la cuenta, cree los recursos de espacio de claves y tabla.

Azure CLI
Azure Portal

Si aún no tiene un grupo de recursos de destino, use el az group create comando para crear un nuevo grupo de recursos en la suscripción.
```
az group create \
    --name "<resource-group-name>" \
    --location "<location>"
```

Use el az cosmosdb create comando para crear una nueva cuenta de Azure Cosmos DB para Apache Cassandra con la configuración predeterminada.

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

Cree un nuevo espacio de claves usando az cosmosdb cassandra keyspace create llamado cosmicworks.

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

Cree un nuevo objeto JSON para representar el esquema mediante un comando bash de varias líneas. A continuación, use el az cosmosdb cassandra table create comando para crear una nueva tabla denominada 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"

Inicie sesión en Azure Portal (https://portal.azure.com).
Introduzca Azure Cosmos DB en la barra de búsqueda global.
En Servicios, seleccione Azure Cosmos DB.
En el panel Azure Cosmos DB , seleccione Crear y, después, Azure Cosmos DB para Apache Cassandra en la pestaña Otros .
Seleccione Cuenta de base de datos de unidad de solicitud (RU) para el tipo de cuenta.

En el panel Aspectos básicos, configure las siguientes opciones y, a continuación, seleccione Revisar y crear:

	Importancia
Tipo de carga de trabajo	Aprendizaje
Suscripción	Seleccione su suscripción a Azure.
Grupo de recursos	Cree un grupo de recursos nuevo o seleccione uno existente
Nombre de cuenta	Proporcione un nombre único global.
Zonas de disponibilidad	Deshabilitar
Ubicación	Seleccione una región de Azure compatible para su suscripción

Sugerencia

Puede dejar cualquier opción no especificada con sus valores predeterminados. También puede configurar la cuenta para limitar el rendimiento total de la cuenta a 1000 unidades de solicitud por segundo (RU/s) o habilitar el nivel gratis para minimizar los costos.

En el panel Revisar y crear, espere a que la validación de la cuenta finalice correctamente y seleccione Crear.
El portal navega automáticamente al panel Implementación. Espere a que la implementación se complete.
Una vez completada la implementación, seleccione Ir al recurso para ir a la nueva API para la cuenta de Apache Cassandra.
En el menú de recursos, seleccione la opción Explorador de datos .
En el Explorador de datos, seleccione + Nueva tabla.

En el cuadro de diálogo Agregar tabla , configure las opciones siguientes y, a continuación, seleccione Aceptar:

	Importancia
Keyspace	Crear nuevo
Nombre del Keyspace	`cosmicworks`
Nombre de la tabla	`product`
Esquema de tabla	`(id text, name text, category text, quantity int, price decimal, clearance boolean, PRIMARY KEY (id))`

Sugerencia

Puede dejar cualquier opción no especificada con sus valores predeterminados.

Obtener credenciales

Ahora, obtenga la contraseña de la biblioteca cliente que se usará para crear una conexión a la cuenta creada recientemente.

Azure CLI
Azure Portal

Use az cosmosdb show para obtener el punto de contacto y el nombre de usuario de la cuenta.

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

Registre el valor de las propiedades contactPoint y username de la salida de los comandos anteriores. Los valores de estas propiedades son el punto de contacto y el nombre de usuario que usa más adelante en esta guía para conectarse a la cuenta con la biblioteca.

Use az cosmosdb keys list para obtener las claves de la cuenta.

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

Registre el valor de la propiedad primaryMasterKey de la salida de los comandos anteriores. El valor de esta propiedad es la contraseña que se usa más adelante en esta guía para conectarse a la cuenta con la biblioteca.

Preparación del entorno de desarrollo

A continuación, configure el entorno de desarrollo con un nuevo proyecto y la biblioteca cliente. Este paso es el último requisito previo necesario antes de pasar al resto de esta guía.

Inicie en un directorio vacío.

Genere un nuevo proyecto de consola de Java mediante Maven.

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

Importe el java-driver-core paquete desde Maven. Agregue esta sección al archivo pom.xml .

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

Abra el archivo /console/src/main/java/quickstart/App.java .

Observe el código base de la aplicación de Java existente.

package quickstart;

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

Quite los comentarios y la salida de la consola de la reutilizable. Este bloque de código es el punto de partida para el resto de esta guía.
```
package quickstart;

public class App 
{
    public static void main(String[] args)
    {
    }
}
```
Importe el java.security.NoSuchAlgorithmException espacio de nombres.
```
import java.security.NoSuchAlgorithmException;
```
Actualice la firma del main método para indicar que podría producir la NoSuchAlgorithmException excepción.
```
public static void main(String[] args) throws NoSuchAlgorithmException
{    
}
```
Importante

En los pasos restantes de esta guía se supone que va a agregar el código dentro del método main.
Compile el proyecto.
```
mvn compile
```

Modelo de objetos

	Descripción
`CqlSession`	Representa una conexión específica a un clúster
`PreparedStatement`	Representa una instrucción CQL precompilada que se puede ejecutar varias veces de forma eficaz.
`BoundStatement`	Representa una instrucción preparada con parámetros enlazados
`Row`	Representa una sola fila de un resultado de consulta

Autenticar cliente

Empiece por autenticar al cliente con las credenciales recopiladas anteriormente en esta guía.

Abra el archivo /console/src/main/java/quickstart/App.java en el entorno de desarrollo integrado (IDE).

Importe los siguientes 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;

Cree variables de cadena para las credenciales recopiladas anteriormente en esta guía. Asigne un nombre a las variables username, passwordy contactPoint. Cree también una variable de cadena denominada region para el centro de datos local.
```
String username = "<username>";
String password = "<password>";
String contactPoint = "<contact-point>";
```
Cree otra variable de cadena que indique la región donde ha creado la cuenta de Azure Cosmos DB para Apache Cassandra. Asigne a esta variable regionel nombre .
```
String region = "<region>";
```
Cree un SSLContext objeto para asegurarse de que usa el protocolo de seguridad de la capa de transporte (TLS).
```
SSLContext sslContext = SSLContext.getDefault();
```

Cree un nuevo CqlSession objeto con las variables de configuración y credenciales creadas en los pasos anteriores. Establezca el punto de contacto, el centro de datos local, las credenciales de autenticación, el espacio de claves y el contexto de seguridad de la capa de transporte (TLS).

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

Advertencia

La validación completa de la seguridad de la capa de transporte (TLS) está deshabilitada en esta guía para simplificar la autenticación. Para las implementaciones de producción, habilite completamente la validación.

Inserción o actualización de datos

A continuación, actualice los datos nuevos en una tabla. Upserting garantiza que los datos se creen o reemplacen adecuadamente en función de si los mismos datos ya existen en la tabla.

Defina una nueva clase denominada Product con campos correspondientes a la tabla creada anteriormente en esta guía.

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

Sugerencia

En Java, puede crear este tipo en otro archivo o crearlo al final del archivo existente.

Cree un nuevo objeto de tipo Product. Almacene el objeto en una variable denominada product.

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

Cree una nueva variable de cadena denominada insertQuery con la consulta del lenguaje de consulta cassandra (CQL) para insertar una nueva fila.
```
String insertQuery = "INSERT INTO product (id, name, category, quantity, clearance) VALUES (?, ?, ?, ?, ?)";
```

Prepare la instrucción "insert" y asigne las propiedades del producto como parámetros.

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

Actualiza o inserta el producto ejecutando la instrucción enlazada.
```
session.execute(boundInsert);
```

Leer datos

A continuación, lea los datos que se han insertado o actualizado anteriormente en la tabla.

Cree una nueva variable de cadena denominada readQuery con una consulta CQL que coincida con los elementos con el mismo id campo.
```
String readQuery = "SELECT * FROM product WHERE id = ? LIMIT 1";
```
Cree una variable de cadena denominada id con el mismo valor que el producto creado anteriormente en esta guía.
```
String id = "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb";
```

Prepare la declaración y enlace el campo id del producto como un parámetro.

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

Ejecute la instrucción enlazada y almacene el resultado en una variable denominada readResult.
```
ResultSet readResult = session.execute(boundRead);
```

Recupere la primera fila del conjunto de resultados y asígnela a un Product objeto si se encuentra.

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

Consultar datos

Ahora, use una consulta para buscar todos los datos que coincidan con un filtro específico de la tabla.

Cree una nueva variable de cadena denominada findQuery con una consulta CQL que coincida con los elementos con el mismo category campo.
```
String findQuery = "SELECT * FROM product WHERE category = ? ALLOW FILTERING";
```
Cree una variable de cadena denominada id con el mismo valor que el producto creado anteriormente en esta guía.
```
String category = "gear-surf-surfboards";
```

Prepare la instrucción y enlace la categoría de producto como parámetro.

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

Ejecute la instrucción enlazada y almacene el resultado en una variable denominada findResults.
```
ResultSet results = session.execute(boundFind);
```

Recorre en iteración los resultados de la consulta y asigna cada fila a un 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
}

Cerrar sesión

En Java, es necesario cerrar la sesión después de que haya terminado con las consultas y las operaciones.

session.close();

Ejecución del código

Ejecute la aplicación recién creada mediante un terminal en el directorio de la aplicación.

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

Sugerencia

Asegúrese de que está ejecutando este comando dentro de la ruta /console que se creó en esta guía.

Limpieza de recursos

Ahora, obtenga la contraseña de la biblioteca cliente que se usará para crear una conexión a la cuenta creada recientemente.

Azure CLI
Azure Portal

Use az cosmosdb show para obtener el punto de contacto y el nombre de usuario de la cuenta.

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

Registre el valor de las propiedades contactPoint y username de la salida de los comandos anteriores. Los valores de estas propiedades son el punto de contacto y el nombre de usuario que usa más adelante en esta guía para conectarse a la cuenta con la biblioteca.

Use az cosmosdb keys list para obtener las claves de la cuenta.

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

Registre el valor de la propiedad primaryMasterKey de la salida de los comandos anteriores. El valor de esta propiedad es la contraseña que se usa más adelante en esta guía para conectarse a la cuenta con la biblioteca.

Paso siguiente

Introducción a Azure Cosmos DB para Apache Cassandra

Comentarios

¿Le ha resultado útil esta página?

Last updated on 2025-07-23

Compartir a través de

Inicio rápido: Biblioteca cliente de Azure Cosmos DB para Apache Cassandra para Java

Prerrequisitos

Instalación

Crear una cuenta

Obtener credenciales

Preparación del entorno de desarrollo

Modelo de objetos

Ejemplos de código

Autenticar cliente

Inserción o actualización de datos

Leer datos

Consultar datos

Cerrar sesión

Ejecución del código

Limpieza de recursos

Paso siguiente

Comentarios

Recursos adicionales