Azure Cosmos DB: Creare un'applicazione Node.js tramite l'API Graph

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 mostra come creare un account Azure Cosmos DB per l'API Graph (anteprima), un database e un grafo tramite il portale di Azure. Si creerà ed eseguirà quindi un'app console usando il driver open source Gremlin Node.js.

Prerequisiti

Prima di poter eseguire questo esempio, è necessario soddisfare i prerequisiti seguenti:

  • Node.js versione v0.10.29 o versioni successive
  • Git

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

Creare un account di database

  1. In una nuova finestra accedere al portale di Azure.

  2. Nel riquadro a sinistra selezionare Nuovo > Database > Azure Cosmos DB > Crea.

    Riquadro "Database" nel portale di Azure

  3. In 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 (graph), MongoDB, SQL (DocumentDB) e Table (key-value). Attualmente ogni modello richiede un account separato.

    Poiché in questa guida introduttiva viene eseguita la programmazione in base all'API Graph, scegliere Gremlin (grafo) quando si compila il modulo. Se si hanno tuttavia dati di documenti di un'app di catalogo, dati chiave/valore (tabella) o dati di cui è stata eseguita la migrazione da un'app MongoDB, tenere presente che Azure Cosmos DB può fornire 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 potrebbero essere diversi da quelli dello screenshot.

    Pannello "Nuovo account"

    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 deve contenere solo lettere minuscole, numeri e il segno meno (-). Deve avere una lunghezza compresa tra 3 e 50 caratteri.
    API Gremlin (graph) La programmazione in base all'API Graph 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 ai propri utenti per fornire loro l'accesso più rapido possibile ai dati.
  4. Selezionare Crea per creare l'account.

  5. Nella barra degli strumenti selezionare l'icona Notifiche Icona 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. Aprire il nuovo account dal riquadro Tutte le risorse nel dashboard.

    Riquadro "Tutte le risorse"

Aggiungere un grafo

È ora possibile usare lo strumento Esplora dati nel portale di Azure per creare un database a grafo.

  1. Dal menu a sinistra del portale di Azure scegliere Esplora dati (anteprima).

  2. In Esplora dati (anteprima) selezionare New Graph (Nuovo grafo). Compilare quindi la pagina usando le informazioni seguenti:

    Esplora dati nel portale di Azure

    Impostazione Valore consigliato Descrizione
    ID database sample-database ID del nuovo database. I nomi dei database devono avere una lunghezza compresa tra 1 e 255 caratteri e non possono contenere / \ # ? o spazi finali.
    Graph id (ID grafo) sample-graph ID del nuovo grafo. I nomi dei grafi presentano gli stessi requisiti relativi ai caratteri degli ID di database.
    Capacità di archiviazione 10 GB Lasciare il valore predefinito. Indica la capacità di archiviazione del database.
    Velocità effettiva 400 UR/s Lasciare il valore predefinito. È possibile aumentare la velocità effettiva in un secondo momento se si desidera ridurre la latenza.
    Chiave di partizione /userId Chiave di partizione che distribuisce i dati in modo uniforme a ogni partizione. Quando si crea un grafo ad alte prestazioni, è importante selezionare la chiave di partizione corretta. Per altre informazioni, vedere Progettazione per il partizionamento.
  3. Dopo avere compilato il modulo, fare clic su OK.

Clonare l'applicazione di esempio

Clonare ora un'app per le API Graph da GitHub, impostare la stringa di connessione ed eseguirla. Come si noterà, è facile usare i dati a livello di codice.

  1. Aprire una finestra del terminale Git, ad esempio Git Bash, e usare il comando cd per passare a una directory di lavoro.

  2. Eseguire il comando seguente per clonare il repository di esempio:

    git clone https://github.com/Azure-Samples/azure-cosmos-db-graph-nodejs-getting-started.git
    
  3. Aprire il file della soluzione in Visual Studio.

Esaminare il codice

Ecco una breve analisi di ciò che accade nell'app. Aprire il file app.js. Verranno visualizzate le righe di codice seguenti.

  • Viene creato il client di Gremlin.

    const client = Gremlin.createClient(
        443, 
        config.endpoint, 
        { 
            "session": false, 
            "ssl": true, 
            "user": `/dbs/${config.database}/colls/${config.collection}`,
            "password": config.primaryKey
        });
    

    Le configurazioni sono tutte incluse in config.js, che verrà modificato nella sezione seguente.

  • Viene eseguita una serie di passaggi di Gremlin con il metodo client.execute.

    console.log('Running Count'); 
    client.execute("g.V().count()", { }, (err, results) => {
        if (err) return console.error(err);
        console.log(JSON.stringify(results));
        console.log();
    });
    

Aggiornare la stringa di connessione

  1. Aprire il file config.js.

  2. In config.js compilare la chiave config.endpoint con il valore URI Gremlin disponibile nella pagina Panoramica del portale di Azure.

    config.endpoint = "GRAPHENDPOINT";

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

    Se il valore di URI Gremlin è vuoto, è possibile generarlo dalla pagina Chiavi nel portale. Usare il valore di URI, rimuovere https:// e modificare i documenti in grafi.

    L'endpoint Gremlin deve essere solo il nome host senza protocollo/numero di porta, ad esempio mygraphdb.graphs.azure.com (non https://mygraphdb.graphs.azure.com o mygraphdb.graphs.azure.com:433).

  3. Nel file config.js compilare il valore di config.primaryKey con il valore Chiave primaria disponibile nella pagina Chiavi del portale di Azure.

    config.primaryKey = "PRIMARYKEY";

    Pannello "Chiavi" del portale di Azure

  4. Immettere il nome del database e il nome del grafo (contenitore) per il valore di config.database e config.collection.

Ecco un esempio dell'aspetto che dovrebbe avere il file config.js completato:

var config = {}

// Note that this must not have HTTPS or the port number
config.endpoint = "testgraphacct.graphs.azure.com";
config.primaryKey = "Pams6e7LEUS7LJ2Qk0fjZf3eGo65JdMWHmyn65i52w8ozPX2oxY3iP0yu05t9v1WymAHNcMwPIqNAEv3XDFsEg==";
config.database = "graphdb"
config.collection = "Persons"

module.exports = config;

Eseguire l'app console

  1. Aprire una finestra del terminale e usare il comando cd per passare alla directory di installazione del file package.json incluso nel progetto.

  2. Eseguire npm install per installare i moduli npm necessari, tra cui gremlin.

  3. Eseguire node app.js in un terminale per avviare l'applicazione Node.js.

Esplorare con Esplora dati

È ora possibile tornare a Esplora dati nel portale di Azure per visualizzare, modificare e usare i nuovi dati del grafo ed eseguire query su di essi.

In Esplora dati il nuovo database viene visualizzato nel riquadro Graph. Espandere il database e la raccolta, quindi fare clic su Graph.

I dati generati dall'app di esempio vengono visualizzati nel riquadro successivo nella scheda Graph quando si fa clic su Applica filtro.

Provare a completare g.V() con .has('firstName', 'Thomas') per testare il filtro. Il valore distingue tra maiuscole e minuscole.

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. Queste informazioni offrono una panoramica chiara 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, selezionare Metriche.

    App elenco attività con dati di esempio

Pulire le risorse

Se non si prevede di continuare a usare questa app, eliminare tutte le risorse create in questo articolo eseguendo la procedura illustrata di seguito:

  1. Nel portale di Azure, nel menu di spostamento di sinistra selezionare Gruppi di risorse. Selezionare quindi il nome della risorsa che è stata creata.

  2. Nella pagina del gruppo di risorse selezionare Elimina. Digitare il nome della risorsa da eliminare, quindi selezionare Elimina.

Passaggi successivi

In questo articolo si è appreso come creare un account Azure Cosmos DB, come creare un grafo con Esplora dati e come eseguire un'app. È ora possibile creare query più complesse e implementare la potente logica di attraversamento dei grafi usando Gremlin.