Guida introduttiva: Libreria Azure Cosmos DB for Apache Gremlin per .NET

SI APPLICA A: Gremlin

• Console
• Python
• Node.JS
• .NET

Azure Cosmos DB per Apache Gremlin è un servizio di database a grafo completamente gestito che implementa il diffuso Apache Tinkerpop, un framework di calcolo a grafo usando il linguaggio di query Gremlin. L'API per Gremlin offre un modo agevole per iniziare a usare Gremlin con un servizio che può crescere e aumentare in base alle esigenze di gestione minima.

In questo avvio rapido, viene usata la libreria Gremlin.Net per connettersi a un account Azure Cosmos DB per Gremlin appena creato.

Codice sorgente della libreria | Pacchetto (NuGet)

Prerequisiti

• Un account Azure con una sottoscrizione attiva.
  • Se non si ha una sottoscrizione di Azure. Sottoscrivere un account Azure gratuito.
  • Se non si vuole una sottoscrizione di Azure. È possibile provare gratuitamente Azure Cosmos DB senza la necessità di alcuna sottoscrizione.
• .NET (LTS)
  • .NET non è installato? Provare questo avvio rapido in GitHub Codespaces.
• Interfaccia della riga di comando di Azure

Azure Cloud Shell

Azure Cloud Shell è un ambiente di shell interattivo ospitato in Azure e usato tramite il browser. È possibile usare Bash o PowerShell con Cloud Shell per usare i servizi di Azure. È possibile usare i comandi preinstallati di Cloud Shell per eseguire il codice contenuto in questo articolo senza dover installare strumenti nell'ambiente locale.

Per avviare Azure Cloud Shell:

Opzione	Esempio/Collegamento
Selezionare Prova nell'angolo superiore destro di un blocco di codice o di comando. Quando si seleziona Prova, il codice o il comando non viene copiato automaticamente in Cloud Shell.
Passare a https://shell.azure.com o selezionare il pulsante Avvia Cloud Shell per aprire Cloud Shell nel browser.
Selezionare il pulsante Cloud Shell nella barra dei menu nell'angolo in alto a destra del portale di Azure.

Per usare Azure Cloud Shell:

1. Avviare Cloud Shell.

2. Selezionare il pulsante Copia in un blocco di codice (o in un blocco di comando) per copiare il codice o il comando.

3. Incollare il codice o il comando nella sessione di Cloud Shell selezionando CTRL+MAIUSC+V in Windows e Linux o selezionando CMD+MAIUSC+V in macOS.

4. Selezionare INVIO per eseguire il codice o il comando.

Configurazione

Questa sezione illustra come creare un’API per l’account Gremlin e configurare un progetto .NET per usare la libreria per connettersi all'account.

Creare un'API per l'account Gremlin

L'API per l'account Gremlin deve essere creata prima di usare la libreria .NET. Inoltre, è utile disporre anche del database e del grafo.

1. Creare variabili della shell per accountName, resourceGroupName e location.

   # Variable for resource group name
   resourceGroupName="msdocs-cosmos-gremlin-quickstart"
   location="westus"
   
   # Variable for account name with a randomly generated suffix
   
   let suffix=$RANDOM*$RANDOM
   accountName="msdocs-gremlin-$suffix"
   

2. Se non è già stato fatto, accedere all'interfaccia della riga di comando di Azure usando az login.

3. Usare az group create per creare un nuovo gruppo di risorse nella propria sottoscrizione.

   az group create \
       --name $resourceGroupName \
       --location $location
   

4. Usare az cosmosdb create per creare una nuova API per l'account Gremlin con le impostazioni predefinite.

   az cosmosdb create \
       --resource-group $resourceGroupName \
       --name $accountName \
       --capabilities "EnableGremlin" \
       --locations regionName=$location \
       --enable-free-tier true
   

   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 questo comando non riesce ad applicare lo sconto per il livello gratuito, significa che un altro account nella sottoscrizione è già stato abilitato per il livello gratuito.

5. Ottenere l’API per il NOME dell’endpoint Gremlin dell’account usando az cosmosdb show.

   az cosmosdb show \
       --resource-group $resourceGroupName \
       --name $accountName \
       --query "name"
   

6. Trovare la CHIAVE dall'elenco di chiavi per l'account con az-cosmosdb-keys-list.

   az cosmosdb keys list \
       --resource-group $resourceGroupName \
       --name $accountName \
       --type "keys" \
       --query "primaryMasterKey"
   

7. Registrare i valori NOME e CHIAVE. Queste credenziali saranno necessarie più avanti.

8. Creare un database denominato cosmicworks usando az cosmosdb gremlin database create.

   az cosmosdb gremlin database create \
       --resource-group $resourceGroupName \
       --account-name $accountName \
       --name "cosmicworks"
   

9. Creare un grafo usando az cosmosdb gremlin graph create. Assegnare al grafo il nome products, quindi impostare la velocità effettiva su 400 e infine impostare il percorso della chiave di partizione su /category.

   az cosmosdb gremlin graph create \
       --resource-group $resourceGroupName \
       --account-name $accountName \
       --database-name "cosmicworks" \
       --name "products" \
       --partition-key-path "/category" \
       --throughput 400
   

Creare una nuova applicazione console .NET

Creare una nuova applicazione console .NET in una cartella vuota usando il terminale preferito.

1. Aprire il terminale in una cartella vuota.

2. Usare il comando dotnet new che specifica il modello di console.

   dotnet new console
   

Installare il pacchetto NuGet

Aggiungere il pacchetto NuGet Gremlin.NET al progetto .NET.

1. Usare il comando dotnet add package che specifica il nome del pacchetto NuGet Gremlin.Net.

   dotnet add package Gremlin.Net
   

2. Compilare il progetto .NET usando dotnet build.

   dotnet build
   

   Assicurarsi che la compilazione abbia avuto esito positivo e sia priva di errori. L'output previsto al termine della creazione dovrebbe essere simile al seguente:

   Determining projects to restore...
     All projects are up-to-date for restore.
     dslkajfjlksd -> \dslkajfjlksd\bin\Debug\net6.0\dslkajfjlksd.dll
   
   Build succeeded.
       0 Warning(s)
       0 Error(s)
   

Configurare le variabili di ambiente

Per usare i valori NOME e URI ottenuti in precedenza in questo avvio rapido, mantenerli in nuove variabili di ambiente nel computer locale che esegue l'applicazione.

1. Per impostare la variabile di ambiente, usare il terminale per mantenere i valori rispettivamente come COSMOS_ENDPOINT e COSMOS_KEY.

   export COSMOS_GREMLIN_ENDPOINT="<account-name>"
   export COSMOS_GREMLIN_KEY="<account-key>"
   

2. Verificare che le variabili di ambiente siano state impostate correttamente.

   printenv COSMOS_GREMLIN_ENDPOINT
   printenv COSMOS_GREMLIN_KEY
   

Esempi di codice

• Autenticare il client
• Creare vertici
• Creare contorni
• Eseguire query su vertici e contorni

Il codice di questo articolo si connette a un database denominato cosmicworks e a un grafo denominato products. Il codice aggiunge quindi vertici e contorni al grafico prima di attraversare gli elementi aggiunti.

Autenticare il client

Le richieste dell'applicazione per la maggior parte dei servizi di Azure devono essere autorizzate. Per l'API per Gremlin, usare i valori NOME e URI ottenuti in precedenza in questo avvio rapido.

1. Aprire il file Program.cs.

2. Eliminare qualsiasi contenuto esistente all'interno del file.

3. Aggiungere un blocco Using per lo spazio dei nomi Gremlin.Net.Driver.

   using Gremlin.Net.Driver;
   

4. Creare variabili stringa di tipo accountName e accountKey. Archiviare le variabili di ambiente COSMOS_GREMLIN_ENDPOINT e COSMOS_GREMLIN_KEY come valori per ogni variabile corrispondente.

   string accountName = Environment.GetEnvironmentVariable("COSMOS_GREMLIN_ENDPOINT")!;
   string accountKey = Environment.GetEnvironmentVariable("COSMOS_GREMLIN_KEY")!;
   

5. Creare una nuova istanza di GremlinServer usando le credenziali dell'account.

   var server = new GremlinServer(
       hostname: $"{accountName}.gremlin.cosmos.azure.com",
       port: 443,
       username: "/dbs/cosmicworks/colls/products",
       password: $"{accountKey}",
       enableSsl: true
   );
   

6. Creare una nuova istanza di GremlinClient usando le credenziali del server remoto e il serializzatore GraphSON 2.0.

   using var client = new GremlinClient(
       gremlinServer: server,
       messageSerializer: new Gremlin.Net.Structure.IO.GraphSON.GraphSON2MessageSerializer()
   );
   

Creare vertici

Ora che l'applicazione è connessa all'account, usare la sintassi Gremlin standard per creare vertici.

1. Usare SubmitAsync per eseguire un comando lato server nell'API per l'account Gremlin. Creare un vertice prodotto con le proprietà seguenti:

   	Valore
   label	product
   id	68719518371
   name	Kiama classic surfboard
   price	285.55
   category	surfboards

   await client.SubmitAsync(
       requestScript: "g.addV('product').property('id', '68719518371').property('name', 'Kiama classic surfboard').property('price', 285.55).property('category', 'surfboards')"
   );
   

2. Creare un secondo vertice prodotto con queste proprietà:

   	Valore
   label	product
   id	68719518403
   name	Montau Turtle Surfboard
   price	600.00
   category	surfboards

   await client.SubmitAsync(
       requestScript: "g.addV('product').property('id', '68719518403').property('name', 'Montau Turtle Surfboard').property('price', 600.00).property('category', 'surfboards')"
   );
   

3. Creare un terzo vertice prodotto con queste proprietà:

   	Valore
   label	product
   id	68719518409
   name	Bondi Twin Surfboard
   price	585.50
   category	surfboards

   await client.SubmitAsync(
       requestScript: "g.addV('product').property('id', '68719518409').property('name', 'Bondi Twin Surfboard').property('price', 585.50).property('category', 'surfboards')"
   );
   

Creare contorni

Creare contorni usando la sintassi Gremlin per definire relazioni tra i vertici.

1. Creare un contorno dal prodotto Montau Turtle Surfboard denominato sostituisce al Kiama classic surfboard prodotto.

   await client.SubmitAsync(
       requestScript: "g.V(['surfboards', '68719518403']).addE('replaces').to(g.V(['surfboards', '68719518371']))"
   );
   

   Suggerimento

   Questa definizione dei contorni usa la sintassi g.V(['<partition-key>', '<id>']). In alternativa, è possibile usare g.V('<id>').has('category', '<partition-key>').

2. Creare un altro contorno sostituisce dallo stesso prodotto all'oggetto Bondi Twin Surfboard.

   await client.SubmitAsync(
       requestScript: "g.V(['surfboards', '68719518403']).addE('replaces').to(g.V(['surfboards', '68719518409']))"
   );
   

Eseguire query su vertici e contorni

Usare la sintassi Gremlin per attraversare il grafo e individuare le relazioni tra vertici.

1. Attraversare il grafo e trovare tutti i vertici che Montau Turtle Surfboard sostituisce.

   var results = await client.SubmitAsync<Dictionary<string, object>>(
       requestScript: "g.V().hasLabel('product').has('category', 'surfboards').has('name', 'Montau Turtle Surfboard').outE('replaces').inV()"
   );
   

2. Scrivere nella console la stringa statica [CREATED PRODUCT]\t68719518403. Eseguire quindi l'iterazione su ogni vertice corrispondente usando un ciclo foreach e scrivere nella console un messaggio che inizia con [REPLACES PRODUCT] e include il campo prodotto corrispondente id come suffisso.

   Console.WriteLine($"[CREATED PRODUCT]\t68719518403");
   foreach (var result in results ?? Enumerable.Empty<Dictionary<string, object>>())
   {
       Console.WriteLine($"[REPLACES PRODUCT]\t{result["id"]}");
   }
   

Eseguire il codice

Verificare che l'applicazione funzioni come previsto eseguendo l'applicazione. L'applicazione deve essere eseguita senza errori o avvisi. L'output dell'applicazione include i dati sugli elementi creati e sottoposti a query.

1. Aprire il terminale nella cartella del progetto .NET.

2. Usare dotnet run per eseguire l'applicazione.

   dotnet run
   

3. Osservare l'output dell'applicazione.

   [CREATED PRODUCT]       68719518403
   [REPLACES PRODUCT]      68719518371
   [REPLACES PRODUCT]      68719518409
   

Pulire le risorse

Quando l'API per l'account Gremlin non è più necessaria, eliminare il gruppo di risorse corrispondente.

1. Creare una variabile shell per resourceGroupName, se non esiste già.

   # Variable for resource group name
   resourceGroupName="msdocs-cosmos-gremlin-quickstart"
   

2. Usare az group delete per eliminare il gruppo di risorse.

   az group delete \
       --name $resourceGroupName
   

Passaggio successivo

Creare ed eseguire query sui dati usando Azure Cosmos DB for Apache Gremlin