Partager via

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

  • Article

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

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

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 .NET 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 .NET. 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éez une application console .NET

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

  1. Ouvrez votre terminal dans un dossier vide.

  2. Utilisez la commande dotnet new spécifiant le modèle de console.

    dotnet new console

Installez le package NuGet

Ajoutez le package NuGet Gremlin.NET au projet .NET.

  1. Utilisez la commande dotnet add package en spécifiant le package NuGet Gremlin.Net.

    dotnet add package Gremlin.Net

  2. Générez le projet .NET en utilisant dotnet build.

    dotnet build

    Assurez-vous que le build a réussi sans erreur. La sortie attendue de la build doit ressembler à ceci :

    Determining projects to restore...
  All projects are up-to-date for restore.
  dslkajfjlksd -> \dslkajfjlksd\bin\Debug\net6.0\dslkajfjlksd.dll

Build succeeded.
    0 Warning(s)
    0 Error(s)

Configuration des 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 Program.cs.

  2. Supprimez tout contenu existant dans le fichier.

  3. Ajouter un bloc d'utilisation pour l'espace de noms Gremlin.Net.Driver.

    using Gremlin.Net.Driver;

  4. Créez les variables de chaîne accountName et accountKey. Stockez les variables d’environnement COSMOS_GREMLIN_ENDPOINT et COSMOS_GREMLIN_KEY en tant que valeurs pour chaque variable respective.

    string accountName = Environment.GetEnvironmentVariable("COSMOS_GREMLIN_ENDPOINT")!;
string accountKey = Environment.GetEnvironmentVariable("COSMOS_GREMLIN_KEY")!;

  5. Créez une instance de GremlinServer en utilisant les informations d’identification du compte.

    var server = new GremlinServer(
    hostname: $"{accountName}.gremlin.cosmos.azure.com",
    port: 443,
    username: "/dbs/cosmicworks/colls/products",
    password: $"{accountKey}",
    enableSsl: true
);

  6. Créez une instance de GremlinClient en utilisant les informations d’identification du serveur distant et du sérialiseur GraphSON 2.0.

    using var client = new GremlinClient(
    gremlinServer: server,
    messageSerializer: new Gremlin.Net.Structure.IO.GraphSON.GraphSON2MessageSerializer()
);

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 SubmitAsync 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.SubmitAsync(
    requestScript: "g.addV('product').property('id', '68719518371').property('name', 'Kiama classic surfboard').property('price', 285.55).property('category', '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 
    await client.SubmitAsync(
    requestScript: "g.addV('product').property('id', '68719518403').property('name', 'Montau Turtle Surfboard').property('price', 600.00).property('category', '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 
    await client.SubmitAsync(
    requestScript: "g.addV('product').property('id', '68719518409').property('name', 'Bondi Twin Surfboard').property('price', 585.50).property('category', '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.

    await client.SubmitAsync(
    requestScript: "g.V(['surfboards', '68719518403']).addE('replaces').to(g.V(['surfboards', '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.

    await client.SubmitAsync(
    requestScript: "g.V(['surfboards', '68719518403']).addE('replaces').to(g.V(['surfboards', '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 graphe et recherchez tous les sommets que Montau Turtle Surfboard remplace.

    var results = await client.SubmitAsync<Dictionary<string, object>>(
    requestScript: "g.V().hasLabel('product').has('category', 'surfboards').has('name', 'Montau Turtle Surfboard').outE('replaces').inV()"
);

  2. Écrivez dans la console la chaîne [CREATED PRODUCT]\t68719518403 statique. Ensuite, effectuez une itération sur chaque sommet correspondant en utilisant une boucle foreach, et écrivez dans la console un message qui commence par [REPLACES PRODUCT] et contient le champ id de produit correspondant comme suffixe.

    Console.WriteLine($"[CREATED PRODUCT]\t68719518403");
foreach (var result in results ?? Enumerable.Empty<Dictionary<string, object>>())
{
    Console.WriteLine($"[REPLACES PRODUCT]\t{result["id"]}");
}

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

  2. Utilisez dotnet run pour exécuter l’application.

    dotnet run

  3. Observez la sortie de l’application.

    [CREATED PRODUCT]       68719518403
[REPLACES PRODUCT]      68719518371
[REPLACES PRODUCT]      68719518409

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

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