Guida introduttiva: Libreria Azure Cosmos DB per Apache Gremlin per Node.js

Articolo
10/18/2023

SI APPLICA A: Gremlin

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 libreria per connettersi a un account Azure Cosmos DB per Gremlin appena creato.

Pacchetto del codice | sorgente della libreria (npm)

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.
Node.js (LTS)
- Non è installato Node.js? Provare questa guida introduttiva in GitHub Codespaces.codespaces.new/github/codespaces-blank?quickstart=1)
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:

Avviare Cloud Shell.
Selezionare il pulsante Copia in un blocco di codice (o blocco di comandi) per copiare il codice o il comando.
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.
Selezionare INVIO per eseguire il codice o il comando.

Configurazione

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

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"

Se non è già stato fatto, accedere all'interfaccia della riga di comando di Azure usando az login.
Usare az group create per creare un nuovo gruppo di risorse nella sottoscrizione.
```
az group create \
    --name $resourceGroupName \
    --location $location
```
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.

Ottenere l'API per gremlin endpoint NAME per l'account usando az cosmosdb show.

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

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"

Registrare i valori NAME e KEY . Queste credenziali verranno usate in un secondo momento.

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

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

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 Node.js

Creare un'applicazione console Node.js in una cartella vuota usando il terminale preferito.

Aprire il terminale in una cartella vuota.
Inizializzare un nuovo modulo
```
npm init es6 --yes
```
Creare il file app.js
```
touch app.js
```

Installare il pacchetto npm

Aggiungere il gremlin pacchetto npm al progetto Node.js.

Aprire il file package.json e sostituire il contenuto con questa configurazione JSON.

{
  "main": "app.js",
  "type": "module",
  "scripts": {
    "start": "node app.js"
  },
  "dependencies": {
    "gremlin": "^3.*"
  }
}

Usare il npm install comando per installare tutti i pacchetti specificati nel file package.json .
```
npm install
```

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.

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>"
```
Verificare che le variabili di ambiente siano state impostate correttamente.
```
printenv COSMOS_GREMLIN_ENDPOINT
printenv COSMOS_GREMLIN_KEY
```

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.

Aprire il file app.js .
Importare il gremlin modulo.
```
import gremlin from 'gremlin'
```
Creare accountName e accountKey variabili. Archiviare le COSMOS_GREMLIN_ENDPOINT variabili di ambiente e COSMOS_GREMLIN_KEY come valori per ogni variabile corrispondente.
```
const accountName = process.env.COSMOS_GREMLIN_ENDPOINT
const accountKey = process.env.COSMOS_GREMLIN_KEY
```

Usare PlainTextSaslAuthenticator per creare un nuovo oggetto per le credenziali dell'account.

const credentials = new gremlin.driver.auth.PlainTextSaslAuthenticator(
  '/dbs/cosmicworks/colls/products',
  `${accountKey}`
)

Usare Client per connettersi usando le credenziali del server remoto e il serializzatore GraphSON 2.0 . Usare Open quindi per creare una nuova connessione al server.

const client = new gremlin.driver.Client(
  `wss://${accountName}.gremlin.cosmos.azure.com:443/`,
  {
    credentials,
    traversalsource: 'g',
    rejectUnauthorized: true,
    mimeType: 'application/vnd.gremlin-v2.0+json'
  }
)

client.open()

Creare vertici

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

Usare submit 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.submit(
  'g.addV(\'product\').property(\'id\', prop_id).property(\'name\', prop_name).property(\'price\', prop_price).property(\'category\', prop_partition_key)', {
    prop_id: '68719518371',
    prop_name: 'Kiama classic surfboard',
    prop_price: 285.55,
    prop_partition_key: 'surfboards'
  }
)

Creare un secondo vertice prodotto con queste proprietà:

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

await client.submit(
  'g.addV(\'product\').property(\'id\', prop_id).property(\'name\', prop_name).property(\'price\', prop_price).property(\'category\', prop_partition_key)', {
    prop_id: '68719518403',
    prop_name: 'Montau Turtle Surfboard',
    prop_price: 600.00,
    prop_partition_key: 'surfboards'
  }
)

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.submit(
  'g.addV(\'product\').property(\'id\', prop_id).property(\'name\', prop_name).property(\'price\', prop_price).property(\'category\', prop_partition_key)', {
    prop_id: '68719518409',
    prop_name: 'Bondi Twin Surfboard',
    prop_price: 585.50,
    prop_partition_key: 'surfboards'
  }
)

Creare bordi

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

Creare un bordo dal Montau Turtle Surfboard prodotto denominato sostituisce al Kiama classic surfboard prodotto.
```
await client.submit(
  'g.V([prop_partition_key, prop_source_id]).addE(\'replaces\').to(g.V([prop_partition_key, prop_target_id]))', {
    prop_partition_key: 'surfboards',
    prop_source_id: '68719518403',
    prop_target_id: '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>').

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

await client.submit(
  'g.V([prop_partition_key, prop_source_id]).addE(\'replaces\').to(g.V([prop_partition_key, prop_target_id]))', {
    prop_partition_key: 'surfboards',
    prop_source_id: '68719518403',
    prop_target_id: '68719518409'
  }
)

Eseguire query su vertici e archi

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

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

const result = await client.submit(
  'g.V().hasLabel(\'product\').has(\'category\', prop_partition_key).has(\'name\', prop_name).outE(\'replaces\').inV()', {
    prop_partition_key: 'surfboards',
    prop_name: 'Montau Turtle Surfboard'
  }
)

Scrivere nella console il risultato di questo attraversamento.
```
console.dir(result)
```

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.

Aprire il terminale nella cartella del progetto Node.js.
Usare npm <script> per eseguire l'applicazione. Osservare l'output dell'applicazione.
```
npm start
```

Pulire le risorse

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

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

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

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