Esercitazione su NoSQL: Compilare un'applicazione console Java con l'API di DocumentDB

Esercitazione su NoSQL per l'API di DocumentDB per Azure Cosmos DB Java SDK. Dopo aver seguito questa esercitazione, si otterrà un'applicazione console che consente di creare e ridefinire le query delle risorse Azure Cosmos DB.

Argomenti trattati:

  • Creazione e connessione a un account Azure Cosmos DB
  • Configurare una soluzione Visual Studio
  • Creazione di un database online
  • Creare una raccolta
  • Creazione di documenti JSON
  • Esecuzione di query sulla raccolta
  • Creazione di documenti JSON
  • Esecuzione di query sulla raccolta
  • Sostituzione di un documento
  • Eliminazione di un documento
  • Eliminazione del database

Ecco come procedere.

Prerequisiti

Assicurarsi che sia disponibile quanto segue:

Passaggio 1: Creare un account di Azure Cosmos DB

Creare prima di tutto un account Azure Cosmos DB. Se è già disponibile un account da usare, è possibile andare direttamente al passaggio Clonare il progetto GitHub. Se si usa l'emulatore Azure Cosmos DB, seguire la procedura illustrata nell'articolo relativo all'emulatore Azure Cosmos DB per configurare l'emulatore e proseguire con il passaggio Clonare il progetto GitHub.

  1. In una nuova finestra accedere al portale di Azure.
  2. Nel riquadro a sinistra fare clic su Nuovo, quindi su Database e in Azure Cosmos DB fare clic su Crea.

    Riquadro Database nel portale di Azure

  3. Nel pannello Nuovo account specificare la configurazione desiderata per l'account Azure Cosmos DB.

    Con Azure Cosmos DB è possibile scegliere uno dei quattro modelli di programmazione: Gremlin (grafo), MongoDB, SQL (DocumentDB) e Tabella (chiave/valore), ognuno dei quali attualmente richiede un account separato.

    In questa guida introduttiva viene eseguita la programmazione in base all'API di DocumentDB, quindi scegliere SQL (DocumentDB) quando si compila il modulo. Se si hanno dati di grafi di un'app di social media, dati chiave/valore (tabella) o dati di cui è stata eseguita la migrazione da un'app MongoDB, tenere presente che Azure Cosmos DB può offrire una piattaforma di servizi di database con distribuzione a livello globale e a disponibilità elevata per tutte le applicazioni cruciali.

    Completare i campi nel pannello Nuovo account usando le informazioni riportate nello screenshot seguente come guida. I valori effettivi potrebbero essere diversi.

    Pannello Nuovo account per Azure Cosmos DB

    Impostazione Valore consigliato Descrizione
    ID Valore univoco Nome univoco che identifica l'account Azure Cosmos DB. Poiché alI'ID fornito viene aggiunto documents.azure.com per creare l'URI, usare un ID univoco ma facilmente identificabile. L'ID può contenere solo lettere minuscole, numeri e il segno meno (-) e deve avere una lunghezza compresa tra 3 e 50 caratteri.
    API SQL (DocumentDB) La programmazione in base all'API di DocumentDB verrà eseguita più avanti in questo articolo.
    Sottoscrizione Sottoscrizione in uso Sottoscrizione di Azure da usare per l'account Azure Cosmos DB.
    Gruppo di risorse Stesso valore di ID Nome del nuovo gruppo di risorse per l'account. Per semplicità si può usare lo stesso nome usato come ID.
    Località Area più vicina ai propri utenti Posizione geografica in cui ospitare l'account Azure Cosmos DB. Scegliere la posizione più vicina agli utenti, per offrire loro l'accesso più rapido possibile ai dati.
  4. Fare clic su Crea per creare l'account.
  5. Nella barra degli strumenti superiore fare clic sull'icona delle notifiche icona delle notifiche per monitorare il processo di distribuzione.

    Riquadro Notifiche del portale di Azure

  6. Quando la finestra Notifiche indica che la distribuzione è stata completata, chiudere la finestra di notifica e aprire il nuovo account dal riquadro Tutte le risorse nel Dashboard.

    Account Azure Cosmos DB nel riquadro Tutte le risorse

Passaggio 2: Clonare il progetto GitHub

Per iniziare, è possibile clonare il repository GitHub per l'introduzione ad Azure Cosmos DB e Java. Eseguire questo comando da una directory locale per recuperare il progetto di esempio in locale.

git clone git@github.com:Azure-Samples/azure-cosmos-db-documentdb-java-getting-started.git

cd azure-cosmos-db-documentdb-java-getting-started

La directory contiene un oggetto pom.xml per il progetto e una cartella src che contiene il codice sorgente Java incluso Program.java, che mostra come eseguire semplici operazioni con Azure Cosmos DB, come la creazione di documenti e l'esecuzione di query sui dati all'interno di una raccolta. L'oggetto pom.xml include una dipendenza per DocumentDB Java SDK su Maven.

<dependency>
    <groupId>com.microsoft.azure</groupId>
    <artifactId>azure-documentdb</artifactId>
    <version>LATEST</version>
</dependency>

Passaggio 3: Connettersi a un account Azure Cosmos DB

Tornare al portale di Azure per recuperare l'endpoint e la chiave master primaria. L'endpoint e la chiave primaria di Azure Cosmos DB sono necessari all'applicazione per conoscere la destinazione della connessione e ad Azure Cosmos DB per considerare attendibile la connessione dell'applicazione.

Nel portale di Azure passare all'account Azure Cosmos DB e quindi fare clic su Chiavi. Copiare l'URI dal portale e incollarlo in https://FILLME.documents.azure.com nel file Program.java. Copiare quindi la CHIAVE PRIMARIA dal portale e incollarla in FILLME.

this.client = new DocumentClient(
    "https://FILLME.documents.azure.com",
    "FILLME"
    , new ConnectionPolicy(),
    ConsistencyLevel.Session);

Screenshot del portale di Azure usato nell'esercitazione su NoSQL per creare un'applicazione console Java. Mostra un account Azure Cosmos DB, con l'hub ACTIVE evidenziato, il pulsante CHIAVI evidenziato nel pannello dell'account Azure Cosmos DB e i valori di URI, CHIAVE PRIMARIA e CHIAVE SECONDARIA evidenziati nel pannello Chiavi

Passaggio 4: Creare un database

È possibile creare un database di Azure Cosmos DB usando il metodo createDatabase della classe DocumentClient. Un database è il contenitore logico per l'archiviazione di documenti JSON partizionato nelle raccolte.

Database database = new Database();
database.setId("familydb");
this.client.createDatabase(database, null);

Passaggio 5: Creare una raccolta

Avviso

createCollection crea una nuova raccolta con velocità effettiva riservata, che presenta implicazioni in termini di prezzi. Per altre informazioni, visitare la pagina relativa ai prezzi.

È possibile creare una raccolta usando il metodo createCollection della classe DocumentClient. Una raccolta è un contenitore di documenti JSON e di logica dell'applicazione JavaScript associata.

DocumentCollection collectionInfo = new DocumentCollection();
collectionInfo.setId("familycoll");

// Azure Cosmos DB collections can be reserved with throughput specified in request units/second. 
// Here we create a collection with 400 RU/s.
RequestOptions requestOptions = new RequestOptions();
requestOptions.setOfferThroughput(400);

this.client.createCollection("/dbs/familydb", collectionInfo, requestOptions);

Passaggio 6: Creare documenti JSON

È possibile creare un documento usando il metodo createDocument della classe DocumentClient. I documenti sono contenuto JSON definito dall'utente (arbitrario). Ora è possibile inserire uno o più documenti. Se sono già disponibili dati da archiviare nel database, è possibile usare lo strumento di migrazione dei dati di Azure Cosmos DB per importare i dati in un database.

// Insert your Java objects as documents 
Family andersenFamily = new Family();
andersenFamily.setId("Andersen.1");
andersenFamily.setLastName("Andersen")

// More initialization skipped for brevity. You can have nested references
andersenFamily.setParents(new Parent[] { parent1, parent2 });
andersenFamily.setDistrict("WA5");
Address address = new Address();
address.setCity("Seattle");
address.setCounty("King");
address.setState("WA");

andersenFamily.setAddress(address);
andersenFamily.setRegistered(true);

this.client.createDocument("/dbs/familydb/colls/familycoll", family, new RequestOptions(), true);

Diagramma che illustra la relazione gerarchica tra l'account, il database online, la raccolta e i documenti usati nell'esercitazione su NoSQL per creare un'applicazione console Java

Passaggio 7: Eseguire query sulle risorse di Azure Cosmos DB

Azure Cosmos DB supporta query complesse sui documenti JSON archiviati in ogni raccolta. Il codice di esempio seguente mostra come eseguire query su documenti in Azure Cosmos DB usando la sintassi SQL con il metodo queryDocuments.

FeedResponse<Document> queryResults = this.client.queryDocuments(
    "/dbs/familydb/colls/familycoll",
    "SELECT * FROM Family WHERE Family.lastName = 'Andersen'", 
    null);

System.out.println("Running SQL query...");
for (Document family : queryResults.getQueryIterable()) {
    System.out.println(String.format("\tRead %s", family));
}

Passaggio 8: Sostituire un documento JSON

Azure Cosmos DB supporta l'aggiornamento di documenti JSON con il metodo replaceDocument.

// Update a property
andersenFamily.Children[0].Grade = 6;

this.client.replaceDocument(
    "/dbs/familydb/colls/familycoll/docs/Andersen.1", 
    andersenFamily,
    null);

Passaggio 9: Eliminare un documento JSON

Analogamente, Azure Cosmos DB supporta l'eliminazione di documenti JSON con il metodo deleteDocument.

this.client.delete("/dbs/familydb/colls/familycoll/docs/Andersen.1", null);

Passaggio 10: Eliminare il database

Se si elimina il database creato, insieme al database vengono rimosse tutte le risorse figlio, come raccolte, documenti e così via.

this.client.deleteDatabase("/dbs/familydb", null);

Passaggio 11: Eseguire l'intera applicazione console Java

Per eseguire l'applicazione dalla console, passare alla cartella del progetto e compilare usando Maven:

mvn package

L'esecuzione di mvn package scarica la libreria di Azure Cosmos DB più recente da Maven e produce GetStarted-0.0.1-SNAPSHOT.jar. Eseguire l'app usando quanto segue:

mvn exec:java -D exec.mainClass=GetStarted.Program

Congratulazioni. L'esercitazione su NoSQL è stata completata ed è stata creata un'applicazione console Java funzionante.

Passaggi successivi