Azure Cosmos DB: Creare un'applicazione .NET 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 di avvio rapido mostra come creare un account, un database e un grafo (contenitore) di Azure Cosmos DB tramite il portale di Azure. Quindi, si creerà ed eseguirà un'app console basata sull'API Graph (anteprima).

Prerequisiti

Se Visual Studio 2017 non è ancora installato, è possibile scaricare e usare la versione gratuita Visual Studio 2017 Community Edition. Durante l'installazione di Visual Studio abilitare Sviluppo di Azure.

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 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 Graph, quindi 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 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 deve contenere solo lettere minuscole, numeri e il segno meno (-) e 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. 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 un grafo

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

  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 New Graph (Nuovo grafo) e quindi compilare i campi della pagina con 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.
    UR/min Off Lasciare il valore predefinito.
    Chiave di partizione /userId Chiave di partizione che distribuisce i dati in modo uniforme a ogni partizione. La selezione della chiave di partizione corretta è importante per creare un grafo efficiente. Per altre informazioni, vedere Progettazione per il partizionamento.
  3. Dopo aver 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, 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-graph-dotnet-getting-started.git
    
  3. Aprire quindi Visual Studio e il file della soluzione.

Esaminare il codice

Ecco una breve analisi di ciò che accade nell'app. Aprire il file Program.cs. Come si noterà, queste righe di codice creano le risorse di Azure Cosmos DB.

  • Viene inizializzato DocumentClient. Nell'anteprima è stata aggiunta un'API di estensione Graph nel client Azure Cosmos DB. È in corso lo sviluppo di un client Graph autonomo separato dal client e dalle risorse di Azure Cosmos DB.

    using (DocumentClient client = new DocumentClient(
        new Uri(endpoint),
        authKey,
        new ConnectionPolicy { ConnectionMode = ConnectionMode.Direct, ConnectionProtocol = Protocol.Tcp }))
    
  • Viene creato un nuovo database.

    Database database = await client.CreateDatabaseIfNotExistsAsync(new Database { Id = "graphdb" });
    
  • Viene creato un nuovo grafo.

    DocumentCollection graph = await client.CreateDocumentCollectionIfNotExistsAsync(
        UriFactory.CreateDatabaseUri("graphdb"),
        new DocumentCollection { Id = "graph" },
        new RequestOptions { OfferThroughput = 1000 });
    
  • Viene eseguita una serie di passaggi di Gremlin tramite il metodo CreateGremlinQuery.

    // The CreateGremlinQuery method extensions allow you to execute Gremlin queries and iterate
    // results asychronously
    IDocumentQuery<dynamic> query = client.CreateGremlinQuery<dynamic>(graph, "g.V().count()");
    while (query.HasMoreResults)
    {
        foreach (dynamic result in await query.ExecuteNextAsync())
        {
            Console.WriteLine($"\t {JsonConvert.SerializeObject(result)}");
        }
    }
    

Aggiornare la stringa di connessione

Tornare ora al portale di Azure per recuperare le informazioni sulla stringa di connessione e copiarle nell'app.

  1. In Visual Studio 2017 aprire il file App.config.

  2. Nell'account Azure Cosmos DB nel portale di Azure fare clic su Chiavi nel riquadro di spostamento a sinistra.

    Visualizzare e copiare una chiave primaria nella pagina Chiavi del portale di Azure

  3. Copiare il valore URI dal portale e impostarlo come valore della chiave di endpoint in App.config. Come illustrato nello screenshot precedente è possibile usare il pulsante di copia per copiare il valore.

    <add key="Endpoint" value="https://FILLME.documents.azure.com:443" />

  4. Copiare il valore di CHIAVE PRIMARIA dal portale e impostarlo come valore della chiave AuthKey in App.config, quindi salvare le modifiche.

    <add key="AuthKey" value="FILLME" />

L'app è stata aggiornata con tutte le informazioni necessarie per comunicare con Azure Cosmos DB.

Eseguire l'app console

  1. In Visual Studio fare clic con il pulsante destro del mouse sul progetto GraphGetStarted in Esplora soluzioni e quindi scegliere Gestisci pacchetti NuGet.

  2. Nella casella Sfoglia di NuGet digitare Microsoft.Azure.Graphs e selezionare la casella Includi versione preliminare.

  3. Dai risultati installare la libreria Microsoft.Azure.Graphs . Viene installato il pacchetto della libreria di estensioni Graph per Azure Cosmos DB, insieme a tutte le dipendenze.

    Se viene visualizzato un messaggio sulla verifica delle modifiche alla soluzione, fare clic su OK. Se viene visualizzato un messaggio sull'accettazione della licenza, fare clic su Accetto.

  4. Premere CTRL+F5 per eseguire l'applicazione.

    La finestra della console visualizza i vertici e gli archi aggiunti al grafo. Al termine dello script, premere INVIO due volte per chiudere la finestra della console.

Esplorare i dati con Esplora dati

È ora possibile tornare a Esplora dati nel portale di Azure per esplorare i nuovi dati del grafo ed eseguire query su di essi.

  1. In Esplora dati il nuovo database viene visualizzato nel riquadro Graph. Espandere graphdb e graphcollz e quindi fare clic su Grafico.

  2. Fare clic sul pulsante Applica filtro per usare la query predefinita per visualizzare tutti i vertici nel grafico. I dati generati dall'app di esempio vengono visualizzati nel riquadro Graphs (Grafi).

    È possibile ingrandire o ridurre il grafico, espanderne lo spazio di visualizzazione, aggiungere altri vertici e spostare i vertici nell'area di visualizzazione.

    Visualizzare il grafico in Esplora dati nel portale di Azure

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, 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.