Azure Cosmos DB: Creare un database di documenti con Java e il portale di Azure

Azure Cosmos DB è il servizio di database multimodello distribuito a livello globale di Microsoft. È possibile creare ed eseguire rapidamente query su database di documenti, coppie chiave/valore e grafi, sfruttando in ognuno dei casi i vantaggi offerti dalle funzionalità di scalabilità orizzontale e distribuzione globale alla base di Azure Cosmos DB.

Questa guida introduttiva illustra come creare un database di documenti con gli strumenti del portale di Azure per Azure Cosmos DB. Illustra anche come creare rapidamente un'app console Java usando l'API Java DocumentDB. Le istruzioni di questa guida introduttiva possono essere eseguite in qualsiasi sistema operativo in grado di eseguire Java. Completando questa guida introduttiva si acquisirà familiarità con la creazione e la modifica di risorse database di documenti nell'interfaccia utente o a livello di codice, in base alle proprie preferenze.

Prerequisiti

  • Java Development Kit (JDK) 1.7+
    • In Ubuntu eseguire apt-get install default-jdk per installare JDK.
    • Assicurarsi di impostare la variabile di ambiente JAVA_HOME in modo che faccia riferimento alla cartella di installazione di JDK.
  • Scaricare e installare un archivio binario Maven
    • In Ubuntu è possibile eseguire apt-get install maven per installare Maven.
  • Git
    • In Ubuntu è possibile eseguire sudo apt-get install git per installare Git.

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

Creare un account di database

Prima di poter creare un database di grafi, è necessario creare un account di database SQL (DocumentDB) con Azure Cosmos DB.

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

    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 DocumentDB nel riquadro Tutte le risorse

Aggiungere una raccolta

È ora possibile usare lo strumento Esplora dati nel portale di Azure per creare un database e una raccolta.

  1. Nel menu di navigazione a sinistra del portale di Azure fare clic su Esplora dati (anteprima).

  2. Nel pannello Esplora dati (anteprima) fare clic su Nuova raccolta e quindi specificare le informazioni seguenti:

    Pannello Esplora dati nel portale di Azure

    Impostazione Valore consigliato Descrizione
    ID database Attività Nome del nuovo database. I nomi dei database devono avere una lunghezza compresa tra 1 e 255 caratteri e non possono contenere /, \, #, ? o spazi finali.
    ID raccolta Items Nome della nuova raccolta. I nomi delle raccolte prevedono requisiti per i caratteri uguali a quelli degli ID dei database.
    Capacità di archiviazione Fissa (10 GB) Usare il valore predefinito. Questo valore indica la capacità di archiviazione del database.
    Velocità effettiva 400 UR Usare il valore predefinito. Se si vuole ridurre la latenza, è possibile aumentare la velocità effettiva in un secondo momento.
    UR/min Off Lasciare il valore predefinito. Se in seguito sarà necessario gestire carichi di lavoro di picco, sarà possibile attivare la funzionalità UR/min al momento.
    Chiave di partizione /category Chiave di partizione che distribuisce i dati in modo uniforme a ogni partizione. Quando si crea una raccolta ad alte prestazioni è importante selezionare la chiave di partizione corretta. Per altre informazioni, vedere Progettazione per il partizionamento.
  3. Dopo aver completato il modulo, fare clic su OK.

Esplora dati mostrerà il nuovo database e la nuova raccolta.

Aggiungere dati di esempio

È ora possibile aggiungere dati alla nuova raccolta usando Esplora dati.

  1. In Esplora dati il nuovo database viene visualizzato nel riquadro Raccolte. Espandere il database Tasks, espandere la raccolta Items, fare clic su Documenti e quindi su Nuovo documento.

    Creare nuovi documenti in Esplora dati nel portale di Azure

  2. Aggiungere ora un documento alla raccolta con la struttura seguente.

    {
        "id": "1",
        "category": "personal",
        "name": "groceries",
        "description": "Pick up apples and strawberries.",
        "isComplete": false
    }
    
  3. Dopo avere aggiunto il codice JSON alla scheda Documenti, fare clic su Salva.

    Copiare i dati JSON e fare clic su Salva in Esplora dati nel portale di Azure

  4. Creare e salvare uno o più documenti in cui si inserisce un valore univoco per la proprietà id e modificare le altre proprietà come necessario. I nuovi documenti possono avere la struttura desiderata, perché Azure Cosmos DB non impone alcuno schema per i dati.

    È ora possibile usare query in Esplora dati per recuperare i dati facendo clic sui pulsanti Modifica filtro e Applica filtro. Per impostazione predefinita, Esplora dati usa SELECT * FROM c per recuperare tutti i documenti della raccolta, ma è possibile usare unaquery SQL diversa, ad esempio SELECT * FROM c ORDER BY c._ts DESC, per restituire tutti i documenti in ordine decrescente in base al timestamp.

    È anche possibile usare Esplora dati per creare stored procedure, funzioni definite dall'utente e trigger per eseguire la logica di business sul lato server e aumentare la velocità effettiva. Esplora dati espone tutti i tipi di accesso ai dati a livello di codice predefiniti disponibili nelle API, ma consente anche di accedere facilmente ai dati nel portale di Azure.

Clonare l'applicazione di esempio

A questo punto, è possibile passare all'uso del codice. Si clonerà un'app per le API DocumentDB da GitHub, si imposterà la stringa di connessione e la si eseguirà. Come si noterà, è facile usare i dati a livello di codice.

  1. Aprire una finestra del terminale Git, ad esempio Git Bash, ed eseguire il comando CD per passare a una directory di lavoro.

  2. Eseguire il comando seguente per clonare l'archivio di esempio.

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

Esaminare il codice

Ecco una breve analisi di ciò che accade nell'app. Aprire il file Program.java dalla cartella \src\GetStarted e trovare queste righe di codice che creano le risorse di Azure Cosmos DB.

  • Viene inizializzato DocumentClient.

    this.client = new DocumentClient("https://FILLME.documents.azure.com",
            "FILLME", 
            new ConnectionPolicy(),
            ConsistencyLevel.Session);
    
  • Viene creato un nuovo database.

    Database database = new Database();
    database.setId(databaseName);
    
    this.client.createDatabase(database, null);
    
  • Viene creata una nuova raccolta.

    DocumentCollection collectionInfo = new DocumentCollection();
    collectionInfo.setId(collectionName);
    
    ...
    
    this.client.createCollection(databaseLink, collectionInfo, requestOptions);
    
  • Vengono creati alcuni documenti.

    // Any Java object within your code can be serialized into JSON and written to Azure Cosmos DB
    Family andersenFamily = new Family();
    andersenFamily.setId("Andersen.1");
    andersenFamily.setLastName("Andersen");
    // More properties
    
    String collectionLink = String.format("/dbs/%s/colls/%s", databaseName, collectionName);
    this.client.createDocument(collectionLink, family, new RequestOptions(), true);
    
  • Viene eseguita una query SQL su JSON.

    FeedOptions queryOptions = new FeedOptions();
    queryOptions.setPageSize(-1);
    queryOptions.setEnableCrossPartitionQuery(true);
    
    String collectionLink = String.format("/dbs/%s/colls/%s", databaseName, collectionName);
    FeedResponse<Document> queryResults = this.client.queryDocuments(
        collectionLink,
        "SELECT * FROM Family WHERE Family.lastName = 'Andersen'", queryOptions);
    
    System.out.println("Running SQL query...");
    for (Document family : queryResults.getQueryIterable()) {
        System.out.println(String.format("\tRead %s", family));
    }
    

Aggiornare la stringa di connessione

Tornare ora al portale di Azure per recuperare le informazioni sulla stringa di connessione e copiarle nell'app. In questo modo l'app potrà comunicare con il database ospitato.

  1. Nell'account Azure Cosmos DB nel portale di Azure fare clic su Chiavi nel riquadro di spostamento a sinistra e quindi su Chiavi di lettura/scrittura. Usare i pulsanti di copia sul lato destro dello schermo per copiare URI e CHIAVE PRIMARIA nel file Program.java nel passaggio seguente.

    Visualizzazione e copia di una chiave di accesso nel portale di Azure, pannello Chiavi

  2. Nel file Program.java aperto copiare il valore di URI dal portale (usando il pulsante di copia) e impostarlo come valore dell'endpoint del costruttore DocumentClient in Program.java.

    "https://FILLME.documents.azure.com"

  3. Copiare quindi il valore di CHIAVE PRIMARIA dal portale e incollarlo sopra "FILLME", come secondo parametro del costruttore DocumentClient. L'app è stata aggiornata con tutte le informazioni necessarie per comunicare con Azure Cosmos DB.

Esecuzione dell'app

  1. Nella finestra del terminale Git eseguire il comando cd per passare alla cartella azure-cosmos-db-documentdb-java-getting-started.

  2. Nella finestra del terminale Git digitare mvn package per installare i pacchetti Java necessari.

  3. Nella finestra del terminale Git eseguire mvn exec:java -D exec.mainClass=GetStarted.Program per avviare l'applicazione Java.

    Nella finestra del terminale si riceverà la notifica che indica che il database FamilyDB è stato creato e in cui viene chiesto di premere un tasto per continuare. Premere un tasto per creare il database, quindi passare a Esplora dati e osservare che ora contiene un database FamilyDB. Continuare a premere i tasti per creare la raccolta e i documenti e quindi eseguire una query. Quando viene completato il progetto, le risorse vengono eliminate dall'account.

    Visualizzazione e copia di una chiave di accesso nel portale di Azure, pannello Chiavi

Esaminare i contratti di servizio nel portale di Azure

Ora che l'app è operativa, è opportuno garantire la continuità aziendale e controllare l'accesso degli utenti per garantire disponibilità elevata. Per esaminare la disponibilità, la latenza, la velocità effettiva e la coerenza della raccolta, si può usare il portale di Azure.

Ogni grafo associato ai contratti di servizio per Azure Cosmos DB fornisce una linea che mostra la quota necessaria per soddisfare il contratto di servizio e l'utilizzo effettivo, per garantire informazioni chiare sulle prestazioni del database. Nel portale sono anche incluse altre metriche, ad esempio per quanto riguarda l'uso dello spazio di archiviazione e il numero di richieste al minuto.

  • Nel riquadro a sinistra del portale di Azure, in Monitoraggio, fare clic su Metriche.

    App Todo con dati di esempio

Pulire le risorse

Se non si intende continuare a usare l'app, eliminare tutte le risorse create tramite questa guida di avvio rapido nel portale di Azure eseguendo questi passaggi:

  1. Scegliere Gruppi di risorse dal menu a sinistra del portale di Azure e quindi fare clic sul nome della risorsa creata.
  2. Nella pagina del gruppo di risorse fare clic su Elimina, digitare il nome della risorsa da eliminare nella casella di testo e quindi fare clic su Elimina.

Passaggi successivi

In questa guida di avvio rapido si è appreso come creare un account Azure Cosmos DB, un database di documenti e una raccolta usando Esplora dati e come creare eseguire un'app per ottenere lo stesso risultato a livello di codice. È ora possibile importare dati aggiuntivi nell'account Cosmos DB.