Avvio rapido: attraversare vertici e archi con la console Gremlin e Azure Cosmos DB for Apache Gremlin

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 argomento di avvio rapido si usa la console Gremlin per connettersi a un account Azure Cosmos DB per Gremlin appena creato.

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.
• Host Docker
  • Docker 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. Premere Invio per eseguire il codice o il comando.

Creare un'API per l'account Gremlin e le risorse pertinenti

L'API per l'account Gremlin deve essere creata prima di usare la console Gremlin. 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
   

Avviare e configurare la console Gremlin usando Docker

Per la console gremlin, questo avvio rapido utilizza l'immagine del contenitore tinkerpop/gremlin-console da Docker Hub. Questa immagine garantisce che si sta usando la versione appropriata della console (3.4) per la connessione con l'API per Gremlin. Dopo aver eseguito la console, connettersi dall'host Docker locale all'API remota per l'account Gremlin.

1. Eseguire il pull della versione 3.4 dell'immagine del contenitore tinkerpop/gremlin-console.

   docker pull tinkerpop/gremlin-console:3.4
   

2. Creare una cartella di lavoro vuota. Nella cartella vuota creare un file remote-secure.yaml. Aggiungere questa configurazione YAML al file.

   hosts: [<account-name>.gremlin.cosmos.azure.com]
   port: 443
   username: /dbs/cosmicworks/colls/products
   password: <account-key>
   connectionPool: {
     enableSsl: true,
     sslEnabledProtocols: [TLSv1.2]
   }
   serializer: {
     className: org.apache.tinkerpop.gremlin.driver.ser.GraphSONMessageSerializerV2d0,
     config: {
       serializeResultToString: true
     }
   }
   

   Nota

   Sostituire i segnaposto <account-name> e <account-key> con i valori NAME e KEY ottenuti in precedenza in questo argomento di avvio rapido.

3. Aprire un nuovo terminale nel contesto della cartella di lavoro che include il file remote-secure.yaml.

4. Eseguire l'immagine del contenitore Docker in modalità interattiva (--interactive --tty). Assicurarsi di montare la cartella di lavoro corrente nel percorso di /opt/gremlin-console/conf/ all'interno del contenitore.

   docker run -it --mount type=bind,source=.,target=/opt/gremlin-console/conf/ tinkerpop/gremlin-console:3.4
   

5. All'interno del contenitore della console Gremlin connettersi all'account remoto (API per Gremlin) usando il file di configurazione remote-secure.yaml.

   :remote connect tinkerpop.server conf/remote-secure.yaml
   

Creare e attraversare vertici e archi

Ora che la console è connessa all'account, usare la sintassi Gremlin standard per creare e attraversare sia vertici che archi.

1. Aggiungere un vertice per un prodotto con le proprietà seguenti:

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

   :> g.addV('product').property('id', '68719518371').property('name', 'Kiama classic surfboard').property('price', 285.55).property('category', 'surfboards')
   

   Importante

   Non dimenticare il prefisso :>. Il prefisso è necessario per eseguire il comando in modalità remota.

2. Aggiungere un altro prodotto vertice con queste proprietà:

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

   :> g.addV('product').property('id', '68719518403').property('name', 'Montau Turtle Surfboard').property('price', 600).property('category', 'surfboards')
   

3. Creare un arco denominato replaces per definire una relazione tra i due prodotti.

   :> g.V(['surfboards', '68719518403']).addE('replaces').to(g.V(['surfboards', '68719518371']))
   

4. Contare tutti i vertici all'interno del grafico.

   :> g.V().count()
   

5. Attraversare il grafico per trovare tutti i vertici che sostituiscono il Kiama classic surfboard.

   :> g.V().hasLabel('product').has('category', 'surfboards').has('name', 'Kiama classic surfboard').inE('replaces').outV()
   

6. Attraversare il grafico per trovare tutti i vertici che Montau Turtle Surfboard sostituisce.

   :> g.V().hasLabel('product').has('category', 'surfboards').has('name', 'Montau Turtle Surfboard').outE('replaces').inV()
   

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
   

Come abbiamo risolto il problema?

Azure Cosmos DB for Apache Gremlin ha risolto il problema offrendo Gremlin come servizio. Con questa offerta, non è necessario modificare le proprie istanze del server Gremlin o gestire la propria infrastruttura. Ancora di più, è possibile ridimensionare la soluzione man mano che le esigenze aumentano nel tempo.

Per connettersi all'API per l'account Gremlin, è stata usata l'immagine del contenitore tinkerpop/gremlin-console per eseguire la console gremlin in modo da non richiedere un'installazione locale. È stata quindi usata la configurazione archiviata nel file remote-secure.yaml per connettersi dal contenitore in esecuzione, l'API per l'account Gremlin. Da qui sono stati eseguiti più comandi Gremlin comuni.

Passaggio successivo

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