Démarrage rapide : bibliothèque Azure Cosmos DB for Apache Gremlin pour Node.js

Article
10/26/2023

S’APPLIQUE À : Gremlin

Azure Cosmos DB for Apache Gremlin est un service de base de données de graphe entièrement managé qui implémente le célèbre Apache Tinkerpop, un framework de calcul de graphe utilisant le langage de requête Gremlin. L’API pour Gremlin vous offre un moyen relativement facile de commencer à utiliser Gremlin avec un service qui peut grandir et effectuer un scale-out tant que vous voulez avec une gestion minimale.

Dans ce guide de démarrage rapide, vous utilisez la bibliothèque gremlin pour vous connecter à un compte Azure Cosmos DB for Gremlin nouvellement créé.

Code source de la bibliothèque | Package (npm)

Prérequis

Compte Azure avec un abonnement actif.
- Vous ne possédez pas d’abonnement Azure ? Ouvrez gratuitement un compte Azure.
- Vous ne voulez pas d’abonnement Azure ? Vous pouvez essayer Azure Cosmos DB gratuitement sans abonnement.
Node.js (LTS)
- Vous n’avez pas installé Node.js ? Essayez ce guide de démarrage rapide dans GitHub Codespaces.codespaces.new/github/codespaces-blank?quickstart=1)
Azure CLI

Azure Cloud Shell

Azure héberge Azure Cloud Shell, un environnement d’interpréteur de commandes interactif que vous pouvez utiliser dans votre navigateur. Vous pouvez utiliser Bash ou PowerShell avec Cloud Shell pour utiliser les services Azure. Vous pouvez utiliser les commandes préinstallées Cloud Shell pour exécuter le code de cet article sans avoir à installer quoi que ce soit dans votre environnement local.

Pour démarrer Azure Cloud Shell :

Option	Exemple/Lien
Sélectionnez Essayer dans le coin supérieur droite d’un bloc de codes ou de commandes. La sélection de Essayer ne copie pas automatiquement le code ni la commande dans Cloud Shell.
Accédez à https://shell.azure.com ou sélectionnez le bouton Lancer Cloud Shell pour ouvrir Cloud Shell dans votre navigateur.
Sélectionnez le bouton Cloud Shell dans la barre de menus en haut à droite du portail Azure.

Pour utiliser Azure Cloud Shell :

Démarrez Cloud Shell.
Sélectionnez le bouton Copier sur un bloc de codes (ou un bloc de commandes) pour copier le code ou la commande.
Collez le code ou la commande dans la session Cloud Shell en sélectionnant Ctrl+Maj+V sur Windows et Linux ou en sélectionnant Cmd+Maj+V sur macOS.
Sélectionnez Entrée pour exécuter le code ou la commande.

Configuration

Cette section vous guide tout au long de la création d’un compte d’API pour Gremlin et de la configuration d’un projet Node.js pour utiliser la bibliothèque pour vous connecter au compte.

Créer un compte d’API pour Gremlin

Le compte d’API pour Gremlin doit être créé avant d’utiliser la bibliothèque Node.js. En outre, il est également utile d’avoir la base de données et le graphique en place.

Créez des variables d’interpréteur de commandes pour accountName, resourceGroupName et 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"

Si vous ne l’avez pas déjà fait, connectez-vous à Azure CLI avec az login.
Utilisez az group create pour créer un groupe de ressources dans votre abonnement.
```
az group create \
    --name $resourceGroupName \
    --location $location
```
Utilisez az cosmosdb create pour créer un nouveau compte API pour Gremlin avec les paramètres par défaut.
```
az cosmosdb create \
    --resource-group $resourceGroupName \
    --name $accountName \
    --capabilities "EnableGremlin" \
    --locations regionName=$location \
    --enable-free-tier true
```
Remarque

Vous pouvez avoir un seul compte Azure Cosmos DB de niveau gratuit par abonnement Azure et vous devez vous inscrire lors de la création du compte. Si la commande n’applique pas la remise du niveau gratuit, cela signifie qu’un autre compte dans l’abonnement a déjà été activé avec le niveau gratuit.

Obtenez le NOM du point de terminaison de l’API pour Gremlin pour le compte en utilisant az cosmosdb show.

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

Recherchez la CLÉ dans la liste des clés du compte avec az-cosmosdb-keys-list.

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

Enregistrez les valeurs de NOM et CLÉ. Vous utilisez ces informations d’identification par la suite.

Créez une base de données nommée cosmicworks en utilisant az cosmosdb gremlin database create.

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

Créez un graphe en utilisantaz cosmosdb gremlin graph create. Nommez le graphique products, définissez le débit sur 400, puis définissez le chemin de la clé de partition sur /category.

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

Créer une application console Node.js

Créer une application console Node.js dans un dossier vide à l’aide de votre terminal préféré.

Ouvrez votre terminal dans un dossier vide.
Initialiser un nouveau module
```
npm init es6 --yes
```
Créer le fichier app.js
```
touch app.js
```

Installer le package npm

Ajoutez le package gremlin npm au projet Node.js.

Ouvrez le fichier package.json et remplacez le contenu par cette configuration JSON.

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

Utilisez la commande npm install pour installer tous les packages spécifiés dans le fichier package.json.
```
npm install
```

Configurer les variables d’environnement

Pour utiliser les valeurs de NOM et URI obtenues plus tôt dans ce guide de démarrage rapide, conservez-les dans de nouvelles variables d’environnement sur la machine locale exécutant l’application.

Pour définir la variable d’environnement, utilisez votre terminal pour conserver les valeurs en tant que COSMOS_ENDPOINT et COSMOS_KEY respectivement.
```
export COSMOS_GREMLIN_ENDPOINT="<account-name>"
export COSMOS_GREMLIN_KEY="<account-key>"
```
Vérifiez que les variables d’environnement ont été correctement définies.
```
printenv COSMOS_GREMLIN_ENDPOINT
printenv COSMOS_GREMLIN_KEY
```

Le code de cet article se connecte à une base de données nommée cosmicworks et un graphe nommé products. Le code ajoute ensuite des sommets et des arêtes au graphe avant de parcourir les éléments ajoutés.

Authentifier le client

Les requêtes d’application vers les Services Azure doivent être autorisées. Pour l’API pour Gremlin, utilisez les valeurs NOM et URI obtenues précédemment dans ce guide de démarrage rapide.

Ouvrez le fichier app.js.
Importez le module gremlin.
```
import gremlin from 'gremlin'
```
Créez des variables accountName et accountKey. Stockez les variables d’environnement COSMOS_GREMLIN_ENDPOINT et COSMOS_GREMLIN_KEY en tant que valeurs pour chaque variable respective.
```
const accountName = process.env.COSMOS_GREMLIN_ENDPOINT
const accountKey = process.env.COSMOS_GREMLIN_KEY
```

Utilisez PlainTextSaslAuthenticator pour créer un objet pour les informations d’identification du compte.

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

Utilisez Client pour vous connecter à l’aide des informations d’identification du serveur distant et du sérialiseur GraphSON 2.0. Ensuite, utilisez Open pour créer une connexion au serveur.

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()

Créer des sommets

Maintenant que l’application est connectée au compte, utilisez la syntaxe Gremlin standard pour créer des sommets.

Utilisez submit pour exécuter une commande côté serveur sur le compte API pour Gremlin. Créez un sommet de produit avec les propriétés suivantes :

	Valeur
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'
  }
)

Créez un deuxième sommet de produit avec ces propriétés :

	Valeur
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'
  }
)

Créez un troisième sommet de produit avec ces propriétés :

	Valeur
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'
  }
)

Créer des arêtes

Créez des arêtes en utilisant la syntaxe Gremlin pour définir les relations entre les sommets.

Créez une arête à partir du produit Montau Turtle Surfboard nommé replaces vers le produit Kiama classic 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: '68719518371'
  }
)
```
Conseil

Cette définition d’arête utilise la syntaxe g.V(['<partition-key>', '<id>']). Vous pouvez également utiliser g.V('<id>').has('category', '<partition-key>').

Créez une autre arête replaces à partir du même produit vers le 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'
  }
)

Interroger des sommets et des arêtes

Utilisez la syntaxe Gremlin pour parcourir le graphe et découvrir les relations entre les sommets.

Parcourez le graphique et recherchez tous les sommets que Montau Turtle Surfboard remplace.

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'
  }
)

Écrivez dans la console le résultat de cette traversée.
```
console.dir(result)
```

Exécuter le code

Vérifiez que votre application fonctionne comme prévu en exécutant l’application. L’application doit s’exécuter sans erreurs ni avertissements. La sortie de l’application inclut des données sur les éléments créés et interrogés.

Ouvrez le terminal dans le dossier projet Node.js.
Utilisez npm <script> pour exécuter l’application. Observez la sortie de l’application.
```
npm start
```

Nettoyer les ressources

Quand vous n’avez plus besoin du compte API pour Gremlin, supprimez le groupe de ressources correspondant.

Créez une variable d’interpréteur de commandes pour resourceGroupName si elle n’existe pas déjà.
```
# Variable for resource group name
resourceGroupName="msdocs-cosmos-gremlin-quickstart"
```
Utilisez az group delete pour supprimer le groupe de ressources.
```
az group delete \
    --name $resourceGroupName
```

Étape suivante

Créer et interroger des données en utilisant Azure Cosmos DB for Apache Gremlin