Démarrage rapide : Bibliothèque Azure Cosmos DB for Apache Gremlin pour Python

Article
08/15/2024

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 gremlinpython pour vous connecter au compte Azure Cosmos DB for Gremlin nouvellement créé.

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

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.
Python (dernière version)
- Python n’est pas installé ? Essayez ce guide de démarrage rapide dans GitHub Codespaces.
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 dans la création d’un compte API pour Gremlin et la configuration d’un projet Python afin d’utiliser la bibliothèque pour vous connecter au compte.

Créer un compte API pour Gremlin

Le compte API pour Gremlin doit être créé avant d’utiliser la bibliothèque Python. Par ailleurs, il est également utile d’avoir la base de données et le graphe 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 graphe 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 Python

Créez une application console Python dans un dossier vide en utilisant le terminal de votre choix.

Ouvrez votre terminal dans un dossier vide.
Ouvrez le fichier app.py.
```
touch app.py
```

Installer le package PyPI

Ajoutez le package PyPI gremlinpython au projet Python.

Créez le fichier requirements.txt.
```
touch requirements.txt
```
Ajoutez le package gremlinpython à partir de l’index du package Python au fichier de spécifications.
```
gremlinpython==3.7.0
```
Installez toutes les exigences de votre projet.
```
python install -r requirements.txt
```

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 de NOM et URI obtenues précédemment dans ce guide de démarrage rapide.

Ouvrez le fichier app.py.
Importez client et serializer à partir du module gremlin_python.driver.
```
import os
from gremlin_python.driver import client, serializer
```
Avertissement

Selon votre version de Python, vous devrez peut-être importer asyncio et remplacer la stratégie de boucle d’événements :
```
import asyncio
import sys

if sys.platform == "win32":
    asyncio.set_event_loop_policy(asyncio.WindowsSelectorEventLoopPolicy())
```
Créez des variables ACCOUNT_NAME et ACCOUNT_KEY. Stockez les variables d’environnement COSMOS_GREMLIN_ENDPOINT et COSMOS_GREMLIN_KEY en tant que valeurs pour chaque variable respective.
```
ACCOUNT_NAME = os.environ["COSMOS_GREMLIN_ENDPOINT"]
ACCOUNT_KEY = os.environ["COSMOS_GREMLIN_KEY"]
```

Utilisez Client pour vous connecter à l’aide des informations d’identification du compte et du sérialiseur GraphSON 2.0.

client = client.Client(
    url=f"wss://{ACCOUNT_NAME}.gremlin.cosmos.azure.com:443/",
    traversal_source="g",
    username="/dbs/cosmicworks/colls/products",
    password=f"{ACCOUNT_KEY}",
    message_serializer=serializer.GraphSONSerializersV2d0(),
)

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`

client.submit(
    message=(
        "g.addV('product')"
        ".property('id', prop_id)"
        ".property('name', prop_name)"
        ".property('price', prop_price)"
        ".property('category', prop_partition_key)"
    ),
    bindings={
        "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`

client.submit(
    message=(
        "g.addV('product')"
        ".property('id', prop_id)"
        ".property('name', prop_name)"
        ".property('price', prop_price)"
        ".property('category', prop_partition_key)"
    ),
    bindings={
        "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`

client.submit(
    message=(
        "g.addV('product')"
        ".property('id', prop_id)"
        ".property('name', prop_name)"
        ".property('price', prop_price)"
        ".property('category', prop_partition_key)"
    ),
    bindings={
        "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.

client.submit(
    message=(
        "g.V([prop_partition_key, prop_source_id])"
        ".addE('replaces')"
        ".to(g.V([prop_partition_key, prop_target_id]))"
    ),
    bindings={
        "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.

client.submit(
    message=(
        "g.V([prop_partition_key, prop_source_id])"
        ".addE('replaces')"
        ".to(g.V([prop_partition_key, prop_target_id]))"
    ),
    bindings={
        "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.

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

Écrivez dans la console le résultat de cette traversée.
```
print(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 contient des données sur les éléments créés et interrogés.

Ouvrez le terminal dans le dossier projet Python.
Utilisez python <filename> pour exécuter l’application. Observez la sortie de l’application.
```
python app.py
```

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

Partage via