Guida introduttiva: Libreria client di Azure Cosmos DB per Apache Cassandra per Java

Si applica a: ✅ Apache Cassanda

Introduzione alla libreria client di Azure Cosmos DB per Apache Cassandra per Java per archiviare, gestire ed eseguire query sui dati non strutturati. Seguire la procedura descritta in questa guida per creare un nuovo account, installare una libreria client Java, connettersi all'account, eseguire operazioni comuni ed eseguire query sui dati di esempio finali.

Documentazione di riferimento API | Codice sorgente della libreria | Pacchetto (Maven)

Prerequisiti

Una sottoscrizione di Azure
- Se non si ha una sottoscrizione di Azure, creare un account gratuito prima di iniziare.

Versione più recente dell'interfaccia della riga di comando di Azure in Azure Cloud Shell.
- Se si preferisce eseguire i comandi CLI di riferimento in locale, accedere all'interfaccia della riga di comando di Azure usando il comando az login.

Java 21 o versione successiva

Configurazione

Prima di tutto, configurare l'account e l'ambiente di sviluppo per questa guida. Questa sezione illustra il processo di creazione di un account, il recupero delle credenziali e la preparazione dell'ambiente di sviluppo.

Crea un account

Per iniziare, creare un'API per l'account Apache Cassandra. Dopo aver creato l'account, creare il keyspace e le risorse della tabella.

Interfaccia della riga di comando di Azure
Portale di Azure

Se non si ha già un gruppo di risorse di destinazione, usare il az group create comando per creare un nuovo gruppo di risorse nella sottoscrizione.
```
az group create \
    --name "<resource-group-name>" \
    --location "<location>"
```

Usare il az cosmosdb create comando per creare un nuovo account Azure Cosmos DB per Apache Cassandra con le impostazioni predefinite.

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

Creare un nuovo keyspace utilizzando az cosmosdb cassandra keyspace create denominato cosmicworks.

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

Creare un nuovo oggetto JSON per rappresentare lo schema usando un comando Bash a più righe. Usare quindi il az cosmosdb cassandra table create comando per creare una nuova tabella denominata 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"

Accedere al portale di Azure (https://portal.azure.com).
Immettere Azure Cosmos DB nella barra di ricerca globale.
In Servizi selezionare Azure Cosmos DB.
Nel riquadro Azure Cosmos DB selezionare Crea e quindi Azure Cosmos DB per Apache Cassandra nella scheda Altri .
Selezionare Account di database unità richiesta (UR) per il tipo di account.

Nel riquadro Dati principali configurare le opzioni seguenti, quindi selezionare Rivedi e crea:

	Valore
Tipo di carico di lavoro	Apprendimento
Abbonamento	Selezionare la sottoscrizione di Azure
Gruppo di risorse	Creare un nuovo gruppo di risorse o selezionarne uno esistente
Account Name:	Specificare un nome univoco globale
Zone di disponibilità	Disabilitare
Ubicazione	Selezionare un'area di Azure supportata per la sottoscrizione

Suggerimento

È possibile lasciare qualsiasi opzione non specificata ai valori predefiniti. È anche possibile configurare l'account per limitare la velocità effettiva totale dell'account a 1.000 unità richiesta al secondo (UR/sec) o abilitare il livello gratuito per ridurre al minimo i costi.

Nel riquadro Rivedi e crea attendere il completamento della convalida dell'account e quindi selezionare Crea.
Il portale passa automaticamente al riquadro Distribuzione. Attendere il completamento della distribuzione.
Al termine della distribuzione, selezionare Vai alla risorsa per passare alla nuova API per l'account Apache Cassandra.
Nel menu delle risorse selezionare l'opzione Esplora dati .
In Esplora dati selezionare + Nuova tabella.

Nella finestra di dialogo Aggiungi tabella configurare le opzioni seguenti e quindi selezionare OK:

	Valore
Keyspace	Crea nuovo
Nome dello spazio delle chiavi	`cosmicworks`
Nome della tabella	`product`
Schema della tabella	`(id text, name text, category text, quantity int, price decimal, clearance boolean, PRIMARY KEY (id))`

Suggerimento

È possibile lasciare qualsiasi opzione non specificata ai valori predefiniti.

Ottenere le credenziali

Ottenere ora la password per la libreria client da usare per creare una connessione all'account creato di recente.

Interfaccia della riga di comando di Azure
Portale di Azure

Usare az cosmosdb show per ottenere il punto di contatto e il nome utente per l'account.

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

Registrare il valore delle proprietà contactPoint e username dall'output dei comandi precedenti. Questi valori delle proprietà sono il punto di contatto e il nome utente usati più avanti in questa guida per connettersi all'account con la libreria.

Usare az cosmosdb keys list per ottenere le chiavi per l'account.

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

Registrare il valore della primaryMasterKey proprietà dall'output dei comandi precedenti. Il valore di questa proprietà è la password usata più avanti in questa guida per connettersi all'account con la libreria.

Preparare l'ambiente di sviluppo

Configurare quindi l'ambiente di sviluppo con un nuovo progetto e la libreria client. Questo passaggio è l'ultimo prerequisito necessario prima di passare al resto di questa guida.

Iniziare in una directory vuota.

Generare un nuovo progetto console Java usando Maven.

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

Importare il java-driver-core pacchetto da Maven. Aggiungere questa sezione al file pom.xml .

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

Aprire il file /console/src/main/java/quickstart/App.java .

Osservare il boilerplate dell'applicazione Java esistente.

package quickstart;

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

Rimuovere i commenti e l'output della console dal boilerplate. Questo blocco di codice è il punto di partenza per la parte restante di questa guida.
```
package quickstart;

public class App 
{
    public static void main(String[] args)
    {
    }
}
```
Importare lo java.security.NoSuchAlgorithmException spazio dei nomi.
```
import java.security.NoSuchAlgorithmException;
```
Aggiornare la firma del metodo main per indicare che potrebbe generare l'eccezione NoSuchAlgorithmException.
```
public static void main(String[] args) throws NoSuchAlgorithmException
{    
}
```
Importante

I passaggi rimanenti all'interno di questa guida presuppongono che si stia aggiungendo il codice all'interno del main metodo .
Costruisci il progetto.
```
mvn compile
```

Modello a oggetti

	Descrizione
`CqlSession`	Rappresenta una connessione specifica a un cluster
`PreparedStatement`	Rappresenta un'istruzione CQL precompilata che può essere eseguita più volte in modo efficiente
`BoundStatement`	Rappresenta un'istruzione preparata con parametri associati
`Row`	Rappresenta una singola riga di un risultato della query

Autenticare il client

Per iniziare, autenticare il client usando le credenziali raccolte in precedenza in questa guida.

Aprire il file /console/src/main/java/quickstart/App.java nell'ambiente di sviluppo integrato (IDE).

Importare i tipi seguenti:

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;

Creare variabili stringa per le credenziali raccolte in precedenza in questa guida. Nomina le variabili username, password e contactPoint. Creare anche una variabile stringa denominata region per il data center locale.
```
String username = "<username>";
String password = "<password>";
String contactPoint = "<contact-point>";
```
Creare un'altra variabile stringa per l'area in cui è stato creato l'account Azure Cosmos DB per Apache Cassandra. Assegnare alla variabile regionil nome .
```
String region = "<region>";
```
Creare un SSLContext oggetto per assicurarsi di usare il protocollo TLS (Transport Layer Security).
```
SSLContext sslContext = SSLContext.getDefault();
```

Creare un nuovo CqlSession oggetto usando le credenziali e le variabili di configurazione create nei passaggi precedenti. Impostare il punto di contatto, il data center locale, le credenziali di autenticazione, il keyspace e il contesto 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();

Avvertimento

La convalida completa di TLS (Transport Layer Security) è disabilitata in questa guida per semplificare l'autenticazione. Per le distribuzioni di produzione, abilitare completamente la convalida.

Aggiornare o inserire i dati

Eseguire quindi l'operazione di upsert dei nuovi dati in una tabella. L'upserting garantisce che i dati vengano creati o sostituiti in modo appropriato a seconda che nella tabella esistano già gli stessi dati.

Definire una nuova classe denominata Product con i campi corrispondenti alla tabella creata in precedenza in questa guida.

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

Suggerimento

In Java è possibile creare questo tipo in un altro file o crearlo alla fine del file esistente.

Creare un nuovo oggetto di tipo Product. Archiviare l'oggetto in una variabile denominata product.

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

Creare una nuova variabile stringa denominata insertQuery con la query CQL (Cassandra Query Language) per inserire una nuova riga.
```
String insertQuery = "INSERT INTO product (id, name, category, quantity, clearance) VALUES (?, ?, ?, ?, ?)";
```

Preparare l'istruzione insert e associare le proprietà del prodotto come parametri.

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

Eseguire l'upsert del prodotto eseguendo l'istruzione associata.
```
session.execute(boundInsert);
```

Leggere dati

Leggere quindi i dati precedentemente inseriti nella tabella.

Creare una nuova variabile stringa denominata readQuery con una query CQL che corrisponde agli elementi con lo stesso id campo.
```
String readQuery = "SELECT * FROM product WHERE id = ? LIMIT 1";
```
Creare una variabile stringa denominata id con lo stesso valore del prodotto creato in precedenza in questa guida.
```
String id = "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb";
```

Preparare l'istruzione e associare il campo id del prodotto come parametro.

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

Eseguire l'istruzione associata e archiviare il risultato in una variabile denominata readResult.
```
ResultSet readResult = session.execute(boundRead);
```

Recuperare la prima riga dal set di risultati ed eseguirne il mapping a un oggetto Product se presente.

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

Dati di query

Usare ora una query per trovare tutti i dati corrispondenti a un filtro specifico nella tabella.

Creare una nuova variabile stringa denominata findQuery con una query CQL che corrisponde agli elementi con lo stesso category campo.
```
String findQuery = "SELECT * FROM product WHERE category = ? ALLOW FILTERING";
```
Creare una variabile stringa denominata id con lo stesso valore del prodotto creato in precedenza in questa guida.
```
String category = "gear-surf-surfboards";
```

Preparare la dichiarazione e associare la categoria di prodotto come parametro.

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

Eseguire l'istruzione associata e archiviare il risultato in una variabile denominata findResults.
```
ResultSet results = session.execute(boundFind);
```

Iterare sui risultati della query e mappare ogni riga a un oggetto 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
}

Chiudi sessione

In Java è necessario chiudere la sessione dopo aver completato tutte le query e le operazioni.

session.close();

Eseguire il codice

Eseguire l'applicazione appena creata usando un terminale nella directory dell'applicazione.

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

Suggerimento

Assicurarsi di eseguire questo comando all'interno del percorso /console creato in questa guida.

Pulire le risorse

Ottenere ora la password per la libreria client da usare per creare una connessione all'account creato di recente.

Interfaccia della riga di comando di Azure
Portale di Azure

Usare az cosmosdb show per ottenere il punto di contatto e il nome utente per l'account.

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

Registrare il valore delle proprietà contactPoint e username dall'output dei comandi precedenti. Questi valori delle proprietà sono il punto di contatto e il nome utente usati più avanti in questa guida per connettersi all'account con la libreria.

Usare az cosmosdb keys list per ottenere le chiavi per l'account.

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

Registrare il valore della primaryMasterKey proprietà dall'output dei comandi precedenti. Il valore di questa proprietà è la password usata più avanti in questa guida per connettersi all'account con la libreria.

Passo successivo

Panoramica di Azure Cosmos DB per Apache Cassandra

Commenti e suggerimenti

Questa pagina è stata utile?

Last updated on 2025-07-24

Condividi tramite

Guida introduttiva: Libreria client di Azure Cosmos DB per Apache Cassandra per Java

Prerequisiti

Configurazione

Crea un account

Ottenere le credenziali

Preparare l'ambiente di sviluppo

Modello a oggetti

Esempi di codice

Autenticare il client

Aggiornare o inserire i dati

Leggere dati

Dati di query

Chiudi sessione

Eseguire il codice

Pulire le risorse

Passo successivo

Commenti e suggerimenti

Risorse aggiuntive