Guida introduttiva: Libreria Azure Cosmos DB per 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 popolare Apache Tinkerpopframework di calcolo a grafo usando il linguaggio di query Gremlin. L'API per Gremlin offre un modo a basso attrito per iniziare a usare Gremlin con un servizio che può aumentare e aumentare il numero di istanze in base alle esigenze di gestione minima.

In questa guida introduttiva si usa la Gremlin.Net libreria 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.
  • Nessuna sottoscrizione di Azure? Iscriversi per ottenere un account Azure gratuito.
  • Non si vuole una sottoscrizione di Azure? È possibile provare Gratuitamente Azure Cosmos DB senza richiedere alcuna sottoscrizione.
• .NET (LTS)
  • .NET non è installato? Provare questa guida introduttiva 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 in questo articolo, senza dover installare alcun elemento nell'ambiente locale.

Per avviare Azure Cloud Shell:

Opzione	Esempio/Collegamento
Selezionare Prova nell'angolo superiore destro di un codice o di un blocco di comandi. Selezionando Prova non viene copiato automaticamente il codice o il comando 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 blocco di comandi) 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 oppure selezionando CMD+MAIUSC+V in macOS.

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

Configurazione

Questa sezione illustra come creare un account API per 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, consente anche di avere il database e il grafico sul posto.

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 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 applica lo sconto del livello gratuito, significa che un altro account nella sottoscrizione è già stato abilitato con il livello gratuito.

5. Ottenere l'API per gremlin endpoint NAME per l'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 NAME e KEY . Queste credenziali verranno usate in un secondo momento.

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 productsil nome , quindi impostare la velocità effettiva su 400e 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 un'applicazione console .NET in una cartella vuota usando il terminale preferito.

1. Aprire il terminale in una cartella vuota.

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

   dotnet new console
   

Installare il pacchetto NuGet

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

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

   dotnet add package Gremlin.Net
   

2. Compilare il progetto .NET usando dotnet build.

   dotnet build
   

   Assicurarsi che la compilazione abbia avuto esito positivo senza 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 NAME e URI ottenuti in precedenza in questa guida introduttiva, renderli persistenti in nuove variabili di ambiente nel computer locale che esegue l'applicazione.

1. Per impostare la variabile di ambiente, usare il terminale per rendere persistenti 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 bordi
• Eseguire query su vertici e archi

Il codice in questo articolo si connette a un database denominato cosmicworks e a un grafo denominato products. Il codice aggiunge quindi vertici e archi 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 NAME e URI ottenuti in precedenza in questa guida introduttiva.

1. Aprire il file Program.cs.

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

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

   using Gremlin.Net.Driver;
   

4. Creare variabili di tipo stringa e accountKey .accountName Archiviare le COSMOS_GREMLIN_ENDPOINT variabili di ambiente 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 lato server di comando nell'API per l'account Gremlin. Creare un vertice del 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 del 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 bordi

Creare archi usando la sintassi Gremlin per definire le relazioni tra vertici.

1. Creare un bordo dal Montau Turtle Surfboard prodotto 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 bordi usa la g.V(['<partition-key>', '<id>']) sintassi . In alternativa, è possibile usare g.V('<id>').has('category', '<partition-key>').

2. Creare un altro sostituisce edge 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 archi

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

1. Attraversare il grafico e trovare tutti i vertici che Montau Turtle Surfboard sostituiscono.

   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 [CREATED PRODUCT]\t68719518403statica . Eseguire quindi l'iterazione su ogni vertice corrispondente usando un foreach ciclo e scrivere nella console un messaggio che inizia con [REPLACES PRODUCT] e include il campo prodotto id corrispondente 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 per Apache Gremlin