Partager via


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

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

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. Capture d’écran présentant un exemple d’essai pour Azure Cloud Shell.
Accédez à https://shell.azure.com ou sélectionnez le bouton Lancer Cloud Shell pour ouvrir Cloud Shell dans votre navigateur. Bouton permettant de lancer Azure Cloud Shell.
Sélectionnez le bouton Cloud Shell dans la barre de menus en haut à droite du portail Azure. Capture d’écran présentant le bouton Cloud Shell dans le portail Azure.

Pour utiliser Azure Cloud Shell :

  1. Démarrez Cloud Shell.

  2. Sélectionnez le bouton Copier sur un bloc de codes (ou un bloc de commandes) pour copier le code ou la commande.

  3. 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.

  4. 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.

  1. 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"
    
  2. Si vous ne l’avez pas déjà fait, connectez-vous à Azure CLI avec az login.

  3. Utilisez az group create pour créer un groupe de ressources dans votre abonnement.

    az group create \
        --name $resourceGroupName \
        --location $location
    
  4. 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.

  5. 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"
    
  6. 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"
    
  7. Enregistrez les valeurs de NOM et CLÉ. Vous utilisez ces informations d’identification par la suite.

  8. 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"
    
  9. 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.

  1. Ouvrez votre terminal dans un dossier vide.

  2. Ouvrez le fichier app.py.

    touch app.py
    

Installer le package PyPI

Ajoutez le package PyPI gremlinpython au projet Python.

  1. Créez le fichier requirements.txt.

    touch requirements.txt
    
  2. Ajoutez le package gremlinpython à partir de l’index du package Python au fichier de spécifications.

    gremlinpython==3.7.0
    
  3. 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.

  1. 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>"
    
  2. Vérifiez que les variables d’environnement ont été correctement définies.

    printenv COSMOS_GREMLIN_ENDPOINT
    printenv COSMOS_GREMLIN_KEY
    

Exemples de code

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.

  1. Ouvrez le fichier app.py.

  2. 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())
    
  3. 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"]
    
  4. 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.

  1. 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",
        },
    )
    
  2. 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",
        },
    )
    
  3. 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.

  1. 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>').

  2. 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.

  1. 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",
        },
    )
    
  2. É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.

  1. Ouvrez le terminal dans le dossier projet Python.

  2. 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.

  1. 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"
    
  2. Utilisez az group delete pour supprimer le groupe de ressources.

    az group delete \
        --name $resourceGroupName
    

Étape suivante