Avvio rapido: Creare un'applicazione .NET Framework o Core usando l'account Azure Cosmos DB per Gremlin

SI APPLICA A: Gremlin

Azure Cosmos DB è il servizio di database di Microsoft multimodello distribuito a livello globale. È possibile creare rapidamente e eseguire query su documenti, chiave/valore e database grafici. Tutti vantaggi delle funzionalità di distribuzione globale e scalabilità orizzontale al centro di Azure Cosmos DB.

Questo avvio rapido illustra come creare un account, un database e un grafo (contenitore) dell'API Gremlin in Azure Cosmos DB tramite il portale di Azure. In seguito, si crea e si esegue un'app console basata sul driver open source Gremlin.Net.

Prerequisiti

Visual Studio più recente con il carico di lavoro di sviluppo di Azure. È possibile iniziare a usare l'IDE gratuitoVisual Studio Community. Abilitare il carico di lavoro di sviluppo di Azure durante la configurazione di Visual Studio.

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

Creare un account di database

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

  2. Nel menu a sinistra selezionare Crea una risorsa.

    Creare una risorsa nel portale di Azure

  3. Nella pagina Nuovo selezionare Database>Azure Cosmos DB.

    Riquadro Database nel portale di Azure

  4. Nella pagina Crea account Azure Cosmos DB immettere le impostazioni per il nuovo account Azure Cosmos DB.

    Impostazione Valore Descrizione
    Subscription Nome sottoscrizione Selezionare la sottoscrizione di Azure da usare per l'account Azure Cosmos DB.
    Gruppo di risorse Nome del gruppo di risorse Selezionare un gruppo di risorse oppure fare clic su Crea nuovo, quindi immettere un nome univoco per il nuovo gruppo di risorse.
    Nome account Immettere un nome univoco Immettere un nome univoco per identificare l'account Azure Cosmos DB. L'URI dell'account sarà gremlin.cosmos.azure.com e verrà aggiunto al nome dell'account univoco.

    Il nome dell'account può usare solo lettere minuscole, numeri e trattini (-) e deve essere compreso tra 3 e 44 caratteri.
    API Gremlin (grafo) L'API determina il tipo di account da creare. Azure Cosmos DB offre cinque API: NoSQL per i database di documenti, Gremlin per i database graph, MongoDB per i database di documenti, Tabella di Azure e Cassandra. È necessario creare un account separato per ogni API.

    Selezionare Gremlin (graph) perché in questa guida introduttiva si sta creando una tabella che funziona con l'API per Gremlin.

    Altre informazioni sull'API per Gremlin.
    Location 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à Provisioning velocità effettiva 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 in base al 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.

    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

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

    Nota

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

    • Applica sconto per il livello gratuito
    • Ridondanza geografica
    • Scritture in più aree
  6. 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.
  7. Selezionare Rivedi e crea.

  8. La creazione dell'account richiede alcuni minuti. Attendere che nel portale venga visualizzata la pagina Complimenti, l'account Azure Cosmos DB è stato creato.

    Pagina che segnala che la creazione dell'account Azure Cosmos DB è stata completata

Aggiungere un grafo

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

  1. Selezionare Esplora dati>Nuovo grafico.

    Viene visualizzata l'area Add Graph (Aggiungi grafo) all'estrema destra. Per vederla potrebbe essere necessario scorrere la schermata.

    Pagina Esplora dati, Add Graph (Aggiungi grafico) nel portale di Azure

  2. Nella pagina Add Graph (Aggiungi grafo) immettere le impostazioni per il nuovo grafo.

    Impostazione Valore consigliato Descrizione
    ID database sample-database Immettere sample-database come 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.
    Velocità effettiva 400 UR/s Modificare la velocità effettiva in 400 unità richiesta al secondo (UR/sec). Se si vuole ridurre la latenza, è possibile aumentare la velocità effettiva in un secondo momento.
    ID grafo sample-graph Immettere sample-graph come nome della nuova raccolta. I nomi dei grafi presentano gli stessi requisiti relativi ai caratteri degli ID di database.
    Partition Key (Chiave partizione) /pk Tutti gli account Azure Cosmos DB necessitano di una chiave di partizione per la scalabilità orizzontale. Per informazioni su come selezionare una chiave di partizione appropriata, vedere l'articolo Partizionamento dei dati dei grafici.
  3. Dopo avere compilato il modulo, fare clic su OK.

Clonare l'applicazione di esempio

Per clonare un'app API Gremlin da GitHub, impostare la stringa di connessione ed eseguirla. Si noterà quanto sia facile usare i dati a livello di codice.

  1. Aprire un prompt dei comandi, creare una nuova cartella denominata git-samples e quindi chiudere il prompt dei comandi.

    md "C:\git-samples"
    
  2. 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"
    
  3. Eseguire il comando seguente per clonare l'archivio di esempio. Il git clone comando crea una copia dell'app di esempio nel computer.

    git clone https://github.com/Azure-Samples/azure-cosmos-db-graph-gremlindotnet-getting-started.git
    
  4. Aprire quindi Visual Studio e il file della soluzione.

  5. Ripristinare i pacchetti NuGet nel progetto. L'operazione di ripristino deve includere il driver Gremlin.Net e il pacchetto Newtonsoft.Json.

  6. È anche possibile installare manualmente il driver Gremlin.Net@v3.4.13 usando gestione pacchetti NuGet o l'utilità della riga di comando NuGet:

    nuget install Gremlin.NET -Version 3.4.13
    

Nota

La versione supportata del driver Gremlin.NET per l'API Gremlin è disponibile qui. Le versioni rilasciate più recenti di Gremlin.NET potrebbero riscontrare incompatibilità, quindi controllare la tabella collegata per gli aggiornamenti della compatibilità.

Esaminare il codice

Questo passaggio è facoltativo. Per scoprire in che modo le risorse del database vengono create nel codice, è possibile esaminare i frammenti di codice seguenti. In alternativa, è possibile passare ad Aggiornare la stringa di connessione.

Tutti i frammenti di codice seguenti sono tratti dal file Program.cs.

  • Impostare i parametri di connessione in base all'account creato in precedenza:

    private static string Host => Environment.GetEnvironmentVariable("Host") ?? throw new ArgumentException("Missing env var: Host");
    private static string PrimaryKey => Environment.GetEnvironmentVariable("PrimaryKey") ?? throw new ArgumentException("Missing env var: PrimaryKey");
    private static string Database => Environment.GetEnvironmentVariable("DatabaseName") ?? throw new ArgumentException("Missing env var: DatabaseName");
    private static string Container => Environment.GetEnvironmentVariable("ContainerName") ?? throw new ArgumentException("Missing env var: ContainerName");
    
    private static bool EnableSSL
    {
        get
        {
            if (Environment.GetEnvironmentVariable("EnableSSL") == null)
            {
                return true;
            }
    
            if (!bool.TryParse(Environment.GetEnvironmentVariable("EnableSSL"), out bool value))
            {
                throw new ArgumentException("Invalid env var: EnableSSL is not a boolean");
            }
    
            return value;
        }
    }
    
    private static int Port
    {
        get
        {
            if (Environment.GetEnvironmentVariable("Port") == null)
            {
                return 443;
            }
    
            if (!int.TryParse(Environment.GetEnvironmentVariable("Port"), out int port))
            {
                throw new ArgumentException("Invalid env var: Port is not an integer");
            }
    
            return port;
        } 
    }
    
  • I comandi Gremlin da eseguire sono elencati in un dizionario:

    private static Dictionary<string, string> gremlinQueries = new Dictionary<string, string>
    {
        { "Cleanup",        "g.V().drop()" },
        { "AddVertex 1",    "g.addV('person').property('id', 'thomas').property('firstName', 'Thomas').property('age', 44).property('pk', 'pk')" },
        { "AddVertex 2",    "g.addV('person').property('id', 'mary').property('firstName', 'Mary').property('lastName', 'Andersen').property('age', 39).property('pk', 'pk')" },
        { "AddVertex 3",    "g.addV('person').property('id', 'ben').property('firstName', 'Ben').property('lastName', 'Miller').property('pk', 'pk')" },
        { "AddVertex 4",    "g.addV('person').property('id', 'robin').property('firstName', 'Robin').property('lastName', 'Wakefield').property('pk', 'pk')" },
        { "AddEdge 1",      "g.V('thomas').addE('knows').to(g.V('mary'))" },
        { "AddEdge 2",      "g.V('thomas').addE('knows').to(g.V('ben'))" },
        { "AddEdge 3",      "g.V('ben').addE('knows').to(g.V('robin'))" },
        { "UpdateVertex",   "g.V('thomas').property('age', 44)" },
        { "CountVertices",  "g.V().count()" },
        { "Filter Range",   "g.V().hasLabel('person').has('age', gt(40))" },
        { "Project",        "g.V().hasLabel('person').values('firstName')" },
        { "Sort",           "g.V().hasLabel('person').order().by('firstName', decr)" },
        { "Traverse",       "g.V('thomas').out('knows').hasLabel('person')" },
        { "Traverse 2x",    "g.V('thomas').out('knows').hasLabel('person').out('knows').hasLabel('person')" },
        { "Loop",           "g.V('thomas').repeat(out()).until(has('id', 'robin')).path()" },
        { "DropEdge",       "g.V('thomas').outE('knows').where(inV().has('id', 'mary')).drop()" },
        { "CountEdges",     "g.E().count()" },
        { "DropVertex",     "g.V('thomas').drop()" },
    };
    
  • Creare i nuovi oggetti connessione GremlinServer e GremlinClient usando i parametri forniti in precedenza:

    string containerLink = "/dbs/" + Database + "/colls/" + Container;
    Console.WriteLine($"Connecting to: host: {Host}, port: {Port}, container: {containerLink}, ssl: {EnableSSL}");
    var gremlinServer = new GremlinServer(Host, Port, enableSsl: EnableSSL, 
                                            username: containerLink, 
                                            password: PrimaryKey);
    
    ConnectionPoolSettings connectionPoolSettings = new ConnectionPoolSettings()
    {
        MaxInProcessPerConnection = 10,
        PoolSize = 30, 
        ReconnectionAttempts= 3,
        ReconnectionBaseDelay = TimeSpan.FromMilliseconds(500)
    };
    
    var webSocketConfiguration =
        new Action<ClientWebSocketOptions>(options =>
        {
            options.KeepAliveInterval = TimeSpan.FromSeconds(10);
        });
    
    
    using (var gremlinClient = new GremlinClient(
        gremlinServer, 
        new GraphSON2Reader(), 
        new GraphSON2Writer(), 
        GremlinClient.GraphSON2MimeType, 
        connectionPoolSettings, 
        webSocketConfiguration))
    {
    
  • Eseguire ogni query Gremlin usando l'oggetto GremlinClient con un'attività asincrona. È possibile leggere le query Gremlin dal dizionario definito nel passaggio precedente ed eseguirle. Recuperare successivamente il risultato e leggere i valori, formattati come dizionario, usando la classe JsonSerializer del pacchetto Newtonsoft.Json:

    foreach (var query in gremlinQueries)
    {
        Console.WriteLine(String.Format("Running this query: {0}: {1}", query.Key, query.Value));
    
        // Create async task to execute the Gremlin query.
        var resultSet = SubmitRequest(gremlinClient, query).Result;
        if (resultSet.Count > 0)
        {
            Console.WriteLine("\tResult:");
            foreach (var result in resultSet)
            {
                // The vertex results are formed as Dictionaries with a nested dictionary for their properties
                string output = JsonConvert.SerializeObject(result);
                Console.WriteLine($"\t{output}");
            }
            Console.WriteLine();
        }
    
        // Print the status attributes for the result set.
        // This includes the following:
        //  x-ms-status-code            : This is the sub-status code which is specific to Cosmos DB.
        //  x-ms-total-request-charge   : The total request units charged for processing a request.
        //  x-ms-total-server-time-ms   : The total time executing processing the request on the server.
        PrintStatusAttributes(resultSet.StatusAttributes);
        Console.WriteLine();
    }
    

Aggiornare la stringa di connessione

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

  1. Dal portale di Azure passare all'account di database del grafo. Nella scheda Panoramica sono visualizzati due endpoint:

    URI .NET SDK: questo valore viene usato quando ci si connette all'account del grafo tramite la libreria Microsoft.Azure.Graphs.

    Endpoint Gremlin: questo valore viene usato quando ci si connette all'account del grafo tramite la libreria Gremlin.Net.

    Copiare l'endpoint

    Per questo esempio, registrare il valore Hostdell'endpoint Gremlin. Ad esempio, se l'URI è https://graphtest.gremlin.cosmosdb.azure.com, il valore host sarà graphtest.gremlin.cosmosdb.azure.com.

  2. Passare quindi alla scheda Chiavi e registrare il valore CHIAVE PRIMARIA dal portale di Azure.

  3. Dopo aver copiato l'URI e la CHIAVE PRIMARIA dell'account, salvarli in una nuova variabile di ambiente nel computer locale che esegue l'applicazione. Per impostare la variabile di ambiente, aprire una finestra del prompt dei comandi ed eseguire il comando seguente. Assicurarsi di sostituire i valori <cosmos-account-name> e <cosmos-account-primary-key>.

    setx Host "<cosmos-account-name>.gremlin.cosmosdb.azure.com"
    setx PrimaryKey "<cosmos-account-primary-key>"
    
  4. Aprire il file Program.cs e aggiornare le variabili "database" e "container" con i nomi del database e del contenitore (che è anche il nome del grafico) creati sopra.

    private static string database = "your-database-name"; private static string container = "your-container-or-graph-name";

  5. Salvare il file Program.cs.

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

Eseguire l'app console

Premere CTRL + F5 per eseguire l'applicazione. L'applicazione stamperà i comandi della query Gremlin e i risultati nella console.

La finestra della console visualizza i vertici e gli archi aggiunti al grafo. Al completamento dello script, premere INVIO 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 il database e i nodi del contenitore e quindi selezionare Graph.

  2. Selezionare il 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 eseguire lo zoom avanti e indietro del grafico, è possibile espandere lo spazio di visualizzazione del grafico, aggiungere vertici aggiuntivi e spostare vertici sulla superficie di visualizzazione.

    Visualizzare il grafico in Esplora dati nel portale di Azure

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:

  1. Selezionare Metriche nel menu di spostamento dell'account Azure Cosmos DB.

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

    Gruppo di metriche di Azure Cosmos DB

  3. 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:

  1. Nella barra di ricerca del portale di Azure cercare e selezionare Gruppi di risorse.

  2. Selezionare nell'elenco il gruppo di risorse creato in questa guida di avvio rapido.

    Selezionare il gruppo di risorse da eliminare

  3. Nella pagina Panoramica del gruppo di risorse selezionare Elimina gruppo di risorse.

    Eliminare il gruppo di risorse.

  4. Nella finestra successiva immettere il nome del gruppo di risorse da eliminare e quindi selezionare 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.