Avvio rapido: Creare un'app Java per gestire i dati di Azure Cosmos DB for Apache Cassandra (driver v4)

Articolo
08/15/2024

SI APPLICA A: Cassandra

In questo argomento di avvio rapido si apprende come creare un account Azure Cosmos DB for Apache Cassandra e come usare un'app Cassandra in Java clonata da GitHub per creare un contenitore e un database Cassandra con i driver Apache Cassandra v4.x per Java. Azure Cosmos DB è un servizio di database modello che consente di creare ed eseguire rapidamente query su database di documenti, tabelle, valori chiave e grafi, con funzionalità di scalabilità orizzontale e distribuzione globale.

Prerequisiti

Un account Azure con una sottoscrizione attiva. Crearne una gratuitamente. In alternativa, è possibile provare gratuitamente Azure Cosmos DB senza una sottoscrizione di Azure.
Java Development Kit (JDK) 8. Indirizzare la variabile di ambiente JAVA_HOME alla cartella di installazione di JDK.
Un archivio binario Maven. In Ubuntu eseguire apt-get install maven per installare Maven.
Git. In Ubuntu eseguire sudo apt-get install git per installare Git.

Nota

Si tratta di un semplice avvio rapido che usa la versione 4 del driver Apache Cassandra open source per Java. Nella maggior parte dei casi, dovrebbe essere possibile connettere un'applicazione Java dipendente da Apache Cassandra esistente ad Azure Cosmos DB for Apache Cassandra senza apportare modifiche al codice esistente. È tuttavia consigliabile aggiungere un'estensione Java personalizzata che includa criteri di ripetizione e bilanciamento del carico personalizzati, nonché impostazioni di connessione consigliate, per un'esperienza complessiva migliore. In questo modo è possibile gestire la limitazione della frequenza e il failover a livello di applicazione in Azure Cosmos DB, quando necessario. È possibile trovare qui un esempio completo di implementazione dell'estensione.

Creare un account di database

Prima di poter creare un database di documenti, è necessario creare un account di Cassandra con Azure Cosmos DB.

Nel menu del portale di Azure o dalla pagina Home selezionare Crea una risorsa.
Nella pagina Nuovo cercare e selezionare Azure Cosmos DB.
Nella pagina Azure Cosmos DB selezionare Crea.
Nella pagina API, selezionare Crea nella sezione Cassandra.

L'API determina il tipo di account da creare. Azure Cosmos DB mette a disposizione cinque API: NoSQL per i database di documenti, Gremlin per i database di grafi, MongoDB per i database di documenti, Azure Table e Cassandra. È necessario creare un account separato per ogni API.

Selezionare Cassandra, poiché in questo avvio rapido si creerà una tabella che utilizza l'API per Cassandra.

Altre informazioni sull'API per Cassandra.

Nella pagina Crea account Azure Cosmos DB, immettere le impostazioni di base per il nuovo account Azure Cosmos DB.

Impostazione	valore	Descrizione
Subscription	Sottoscrizione in uso	Selezionare la sottoscrizione di Azure da usare per l'account Azure Cosmos DB.
Gruppo di risorse	Crea nuovo Immettere quindi lo stesso nome specificato nome dell'account.	Selezionare Crea nuovo. Immettere quindi il nome di un nuovo gruppo di risorse per l'account. Per semplicità, usare lo stesso nome usato come nome dell'account Azure Cosmos DB.
Nome conto	Immettere un nome univoco	Immettere un nome univoco per identificare l'account Azure Cosmos DB. L'URI dell'account sarà cassandra.cosmos.azure.com e verrà aggiunto al nome dell'account univoco. Il nome dell'account può contenere solo lettere minuscole, numeri e trattini e deve avere una lunghezza compresa tra 3 e 31 caratteri.
Ufficio	Area più vicina ai propri utenti	Selezionare una posizione geografica in cui ospitare l'account Azure Cosmos DB. Usare la località più vicina agli utenti per offrire loro la massima velocità di accesso ai dati.
Modalità di capacità	Velocità effettiva con provisioning o Serverless	Selezionare Provisioning velocità effettiva per creare un account in modalità Provisioning velocità effettiva. Selezionare Serverless per creare un account in modalità Serverless.
Applicare lo sconto del livello gratuito di Azure Cosmos DB	Applicare o non applicare	Il livello gratuito di Azure Cosmos DB offre i primi 1000 UR/s e 25 GB di spazio di archiviazione gratuiti per account. Altre informazioni sul livello gratuito.
Limitare la velocità effettiva totale dell'account	Selezionare per limitare la velocità effettiva dell'account	Questa opzione è utile se si vuole limitare la velocità effettiva totale dell'account in base a un valore specifico.

Nota

È possibile avere fino a un account Azure Cosmos DB del livello gratuito per ogni sottoscrizione di Azure ed è necessario acconsentire esplicitamente durante la creazione dell'account. Se l'opzione per l'applicazione dello sconto per il livello gratuito non è visualizzata, un altro account nella sottoscrizione è già stato abilitato per il livello gratuito.

Pagina del nuovo account per Azure Cosmos DB per Apache Cassandra

Nella scheda Distribuzione globale configurare i dettagli seguenti. Ai fini di questa guida introduttiva è possibile lasciare i valori predefiniti:

Impostazione	valore	Descrizione
Ridondanza geografica	Disabilita	Abilitare o disabilitare la distribuzione globale nell'account associando la propria area a un'altra area. È possibile aggiungere altre aree al proprio account in un secondo momento.
Scritture in più aree	Disabilita	La funzionalità Scritture in più aree consente di sfruttare la velocità effettiva di cui è stato effettuato il provisioning per i database e i contenitori in tutto il mondo.
Zone di disponibilità	Disabilita	Le zone di disponibilità sono località isolate all'interno di un'area di Azure. Ogni zona è costituita da uno o più data center dotati di impianti indipendenti per l'alimentazione, il raffreddamento e la connettività di rete.

Nota

Le opzioni seguenti non sono disponibili se si seleziona Serverless come modalità di capacità:

Applica sconto livello gratuito
Ridondanza geografica
Scritture in più aree

Facoltativamente, è possibile configurare i dettagli aggiuntivi nelle schede seguenti:
- Rete: consente di configurare l'accesso da una rete virtuale.
- Criteri di backup: consente di configurare i criteri di backup periodici o continui.
- Crittografia: consente di usare una chiave gestita dal servizio o una chiave gestita dal cliente.
- Tag: i tag sono coppie nome-valore che consentono di classificare le risorse e visualizzare dati di fatturazione consolidati tramite l'applicazione dello stesso tag a più risorse e gruppi di risorse.
Selezionare Rivedi e crea.
Esaminare le impostazioni dell'account e quindi selezionare Crea. La creazione dell'account richiede alcuni minuti. Attendere che la pagina del portale visualizzi La distribuzione è stata completata.
Selezionare Vai alla risorsa per passare alla pagina dell'account Azure Cosmos DB.

Clonare l'applicazione di esempio

Si può ora passare a usare il codice. Clonare un'app Cassandra da GitHub, impostare la stringa di connessione ed eseguirla. Come si noterà, è facile usare i dati a livello di codice.

Apri un prompt dei comandi. Creare una nuova cartella denominata git-samples, quindi chiudere il prompt dei comandi.
```
md "C:\git-samples"
```
Aprire una finestra del terminale Git, ad esempio Git Bash, ed eseguire il comando cd per passare a una nuova cartella in cui installare l'app di esempio.
```
cd "C:\git-samples"
```
Eseguire il comando seguente per clonare l'archivio di esempio. Questo comando crea una copia dell'app di esempio nel computer in uso.
```
git clone https://github.com/Azure-Samples/azure-cosmos-db-cassandra-java-getting-started-v4.git
```

Esaminare il codice

Questo passaggio è facoltativo. Per comprendere in che modo il codice crea le risorse del database, è possibile esaminare i frammenti di codice seguenti. In alternativa, è possibile passare ad Aggiornare la stringa di connessione. Questi frammenti di codice sono tutti tratti dal file src/main/java/com/azure/cosmosdb/cassandra/util/CassandraUtils.java.

CqlSession si connette all'API Azure Cosmos DB for Apache Cassandra e restituisce una sessione per l'accesso. L'oggetto Cluster del driver v3 è ora obsoleto. Host, porta, nome utente e password di Cassandra vengono impostati nella pagina della stringa di connessione del portale di Azure.
```
    this.session = CqlSession.builder().withSslContext(sc)
            .addContactPoint(new InetSocketAddress(cassandraHost, cassandraPort)).withLocalDatacenter(region)
            .withAuthCredentials(cassandraUsername, cassandraPassword).build();
```

I frammenti di codice seguenti provengono dal file src/main/java/com/azure/cosmosdb/cassandra/repository/UserRepository.java.

Eliminare il keyspace esistente se è già presente da un'esecuzione precedente.

public void dropKeyspace() {
    String query = "DROP KEYSPACE IF EXISTS "+keyspace+"";
    session.execute(query);
    LOGGER.info("dropped keyspace '"+keyspace+"'");
}

Viene creato un nuovo keyspace.

public void createKeyspace() {
    String query = "CREATE KEYSPACE "+keyspace+" WITH REPLICATION = { 'class' : 'NetworkTopologyStrategy', 'datacenter1' : 1 }";
    session.execute(query);
    LOGGER.info("Created keyspace '"+keyspace+"'");
}

Viene creata una nuova tabella.

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

Per inserire le entità utente si usa un oggetto istruzione preparata.

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

Eseguire una query per ottenere le informazioni su tutti gli utenti.

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

Eseguire una query per ottenere le informazioni su un singolo utente.

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

Aggiornare la stringa di connessione

Tornare ora al portale di Azure per recuperare le informazioni sulla stringa di connessione e copiarle nell'app. I dettagli della stringa di connessione consentono all'app di comunicare con il database ospitato.

Nell'account Azure Cosmos DB nel portale di Azure selezionare Stringa di connessione.
Usare il pulsante sul lato destro della schermata per copiare il valore di CONTACT POINT.
Aprire il file config.properties dalla cartella C:\git-samples\azure-cosmosdb-cassandra-java-getting-started\java-examples\src\main\resources.
Incollare il valore di PUNTO DI CONTATTO dal portale su <Cassandra endpoint host> nella riga 2.

La riga 2 di config.properties dovrebbe ora essere simile alla seguente

cassandra_host=cosmos-db-quickstart.cassandra.cosmosdb.azure.com
Tornare al portale e copiare il valore di NOME UTENTE. Incollare il valore di NOME UTENTE dal portale su <cassandra endpoint username> nella riga 4.

La riga 4 di config.properties dovrebbe ora essere simile alla seguente

cassandra_username=cosmos-db-quickstart
Tornare al portale e copiare il valore di PASSWORD. Incollare il valore di PASSWORD dal portale su <cassandra endpoint password> nella riga 5.

La riga 5 di config.properties dovrebbe ora essere simile alla seguente

cassandra_password=2Ggkr662ifxz2Mg...==
Nella riga 6, se si vuole usare un certificato TLS/SSL specifico, sostituire <SSL key store file location> con il percorso del certificato TLS/SSL. Se non è specificato un valore, viene usato il certificato JDK installato in <JAVA_HOME>/jre/lib/security/cacerts.
Se la riga 6 è stata modificata per usare un certificato TLS/ specifico, aggiornare la riga 7 in modo da usare la password per tale certificato.
Tenere presente che è necessario aggiungere l'area predefinita (ad esempio West US) per il punto di contatto, ad esempio

region=West US

Questo perché il driver v. 4x consente di associare un solo controller di dominio locale al punto di contatto. Se si vuole aggiungere un'area diversa da quella predefinita, ovvero l'area specificata al momento della creazione dell'account Azure Cosmos DB, è necessario usare il suffisso di area quando si aggiunge il punto di contatto, ad esempio host-westus.cassandra.cosmos.azure.com.
Salvare il file config.properties.

Eseguire l'app Java

Nella finestra del terminale Git passare con il comando cd alla cartella azure-cosmosdb-cassandra-java-getting-started-v4.
```
cd "C:\git-samples\azure-cosmosdb-cassandra-java-getting-started-v4"
```
Nella finestra del terminale Git usare il comando seguente per generare il file cosmosdb-cassandra-examples.jar.
```
mvn clean install
```
Nella finestra del terminale Git eseguire il comando seguente per avviare l'applicazione Java.
```
java -cp target/cosmosdb-cassandra-examples.jar com.azure.cosmosdb.cassandra.examples.UserProfile
```
Nella finestra del terminale vengono visualizzate notifiche per il completamento della creazione di keyspace e tabella. Vengono quindi selezionati e restituiti tutti gli utenti nella tabella, viene visualizzato l'output e infine viene selezionata una riga in base all'ID e ne viene visualizzato il valore.

Premere CTRL+C per interrompere l'esecuzione del programma e chiudere la finestra della console.
Nel portale di Azure aprire Esplora dati per modificare e usare questi nuovi dati, nonché eseguire query su di essi.

Esaminare i contratti di servizio nel portale di Azure

Il portale di Azure monitora la velocità effettiva dell'account Azure Cosmos DB, l'archiviazione, la disponibilità, la latenza e la coerenza. I grafici per le metriche associate a un contratto di servizio di Azure Cosmos DB indicano il valore previsto dal contratto di servizio rispetto alle prestazioni effettive. Questo gruppo di metriche garantisce la trasparenza nel monitoraggio dei contratti di servizio.

Per esaminare le metriche e i contratti di servizio:

Selezionare Metriche nel menu di spostamento dell'account Azure Cosmos DB.
Selezionare una scheda, ad esempio Latenza, e quindi un intervallo di tempo sulla destra. Confrontare le righe relative ai valori effettivi e ai valori del contratto di servizio nei grafici.
Esaminare le metriche nelle altre schede.

Pulire le risorse

Dopo aver completato le operazioni con l'app e l'account Azure Cosmos DB, è possibile eliminare le risorse di Azure create in modo da non incorrere in altri costi. Per eliminare le risorse:

Nella barra di ricerca del portale di Azure cercare e selezionare Gruppi di risorse.
Selezionare nell'elenco il gruppo di risorse creato in questa guida di avvio rapido.
Nella pagina Panoramica del gruppo di risorse selezionare Elimina gruppo di risorse.
Nella finestra successiva immettere il nome del gruppo di risorse da eliminare e quindi selezionare Elimina.

Passaggi successivi

In questo argomento di avvio rapido si è appreso come creare un account Azure Cosmos DB con l'API per Cassandra e come eseguire un'app Cassandra in Java per creare un contenitore e un database Cassandra. È ora possibile importare dati aggiuntivi nell'account Azure Cosmos DB.

Importare i dati di Cassandra in Azure Cosmos DB

Condividi tramite

Avvio rapido: Creare un'app Java per gestire i dati di Azure Cosmos DB for Apache Cassandra (driver v4)

Prerequisiti

Creare un account di database

Clonare l'applicazione di esempio

Esaminare il codice

Aggiornare la stringa di connessione

Eseguire l'app Java

Esaminare i contratti di servizio nel portale di Azure

Pulire le risorse

Passaggi successivi

Commenti e suggerimenti

Risorse aggiuntive