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

Prise en main de la bibliothèque cliente Azure Cosmos DB pour Apache Gremlin pour .NET pour stocker, gérer et interroger des données non structurées. Suivez les étapes décrites dans ce guide pour créer un compte, installer une bibliothèque cliente .NET, vous connecter au compte, effectuer des opérations courantes et interroger vos exemples de données finaux.

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

Prérequis

• Un abonnement Azure

  • Si vous n’avez pas d’abonnement Azure, créez un compte gratuit avant de commencer.

• Dernière version d’Azure CLI dans Azure Cloud Shell.

  • Si vous préférez exécuter des commandes de référence CLI localement, connectez-vous à Azure CLI à l’aide de la az login commande.

• Kit sdk .NET 9.0 ou version ultérieure

Configuration

Tout d’abord, configurez l’environnement de compte et de développement pour ce guide. Cette section vous guide tout au long du processus de création d’un compte, de l’obtention de ses informations d’identification, puis de la préparation de votre environnement de développement.

Créer un compte

Commencez par créer une API pour un compte Apache Gremlin. Une fois le compte créé, créez les ressources de base de données et de graphique.

Obtenir les informations d’identification

À présent, obtenez le mot de passe de la bibliothèque cliente à utiliser pour créer une connexion au compte récemment créé.

Préparer l’environnement de développement

Ensuite, configurez votre environnement de développement avec un nouveau projet et la bibliothèque cliente. Cette étape est la dernière condition requise avant de passer au reste de ce guide.

1. Démarrez dans un dossier vide.

2. Créer une application console .NET

   dotnet new console
   

3. Importez le Gremlin.Net package à partir de NuGet.

   dotnet add package Gremlin.Net
   

4. Construisez le projet.

   dotnet build
   

Modèle d'objet

Exemples de code

• Authentifier le client
• Insérer des données
• Lire les données
• Rechercher des données

Authentifier le client

Commencez par authentifier le client à l’aide des informations d’identification collectées précédemment dans ce guide.

1. Ouvrez le fichier Program.cs dans votre environnement de développement intégré (IDE).

2. Supprimez tout contenu existant dans le fichier.

3. Ajoutez des directives using pour les espaces de noms suivants :

   • Gremlin.Net.Driver
   • Gremlin.Net.Structure.IO.GraphSON

   using Gremlin.Net.Driver;
   using Gremlin.Net.Structure.IO.GraphSON;
   

4. Créez des variables de chaîne pour les informations d’identification collectées précédemment dans ce guide. Nommez les variables hostname et primaryKey.

   string hostname = "<host>";
   string primaryKey = "<key>";
   

5. Créez une GremlinServer à l’aide des informations d’identification et des variables de configuration créées au cours des étapes précédentes. Nommez la variable server.

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

6. À présent, créez une GremlinClient variable à l’aide de la server variable et de la GraphSON2MessageSerializer configuration.

   GremlinClient client = new(
       server,
       new GraphSON2MessageSerializer()
   );
   

Insertion des données

Ensuite, insérez de nouvelles données de vertex et de périphérie dans le graphique. Avant de créer les nouvelles données, effacez le graphique des données existantes.

1. Exécutez la g.V().drop() requête pour effacer tous les sommets et bords du graphique.

   await client.SubmitAsync("g.V().drop()");
   

2. Créez une requête Gremlin qui ajoute un sommet.

   string insertVertexQuery = """
       g.addV('product')
           .property('id', prop_id)
           .property('name', prop_name)
           .property('category', prop_category)
           .property('quantity', prop_quantity)
           .property('price', prop_price)
           .property('clearance', prop_clearance)
   """;
   

3. Ajoutez un sommet pour un seul produit.

   await client.SubmitAsync(insertVertexQuery, new Dictionary<string, object>
   {
       ["prop_id"] = "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb",
       ["prop_name"] = "Yamba Surfboard",
       ["prop_category"] = "gear-surf-surfboards",
       ["prop_quantity"] = 12,
       ["prop_price"] = 850.00,
       ["prop_clearance"] = false
   });
   

4. Ajoutez deux sommets supplémentaires pour deux produits supplémentaires.

   await client.SubmitAsync(insertVertexQuery, new Dictionary<string, object>
   {
       ["prop_id"] = "bbbbbbbb-1111-2222-3333-cccccccccccc",
       ["prop_name"] = "Montau Turtle Surfboard",
       ["prop_category"] = "gear-surf-surfboards",
       ["prop_quantity"] = 5,
       ["prop_price"] = 600.00,
       ["prop_clearance"] = true
   });
   
   await client.SubmitAsync(insertVertexQuery, new Dictionary<string, object>
   {
       ["prop_id"] = "cccccccc-2222-3333-4444-dddddddddddd",
       ["prop_name"] = "Noosa Surfboard",
       ["prop_category"] = "gear-surf-surfboards",
       ["prop_quantity"] = 31,
       ["prop_price"] = 1100.00,
       ["prop_clearance"] = false
   });
   

5. Créez une autre requête Gremlin qui ajoute un bord.

   string insertEdgeQuery = """
       g.V([prop_partition_key, prop_source_id])
           .addE('replaces')
           .to(g.V([prop_partition_key, prop_target_id]))
   """;
   

6. Ajoutez deux bords.

   await client.SubmitAsync(insertEdgeQuery, new Dictionary<string, object>
   {
       ["prop_partition_key"] = "gear-surf-surfboards",
       ["prop_source_id"] = "bbbbbbbb-1111-2222-3333-cccccccccccc",
       ["prop_target_id"] = "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb"
   });
   
   await client.SubmitAsync(insertEdgeQuery, new Dictionary<string, object>
   {
       ["prop_partition_key"] = "gear-surf-surfboards",
       ["prop_source_id"] = "bbbbbbbb-1111-2222-3333-cccccccccccc",
       ["prop_target_id"] = "cccccccc-2222-3333-4444-dddddddddddd"
   });
   

Lire les données

Ensuite, lisez les données qui ont été insérées précédemment dans le graphique.

1. Créez une requête qui lit un vertex à l’aide de l’identificateur unique et de la valeur de clé de partition.

   string readVertexQuery = "g.V([prop_partition_key, prop_id])";
   

2. Ensuite, lisez un vertex en fournissant les paramètres requis.

   ResultSet<Dictionary<string, object>> readResults = await client.SubmitAsync<Dictionary<string, object>>(readVertexQuery, new Dictionary<string, object>
   {
       ["prop_partition_key"] = "gear-surf-surfboards",
       ["prop_id"] = "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb"
   });
   
   Dictionary<string, object> matchedItem = readResults.Single();
   

Rechercher des données

Enfin, utilisez une requête pour rechercher toutes les données qui correspondent à une traversée ou un filtre spécifique dans le graphique.

1. Créez une requête qui recherche tous les sommets qui partent d’un sommet spécifique.

   string findVerticesQuery = """
       g.V().hasLabel('product')
           .has('category', prop_partition_key)
           .has('name', prop_name)
           .outE('replaces').inV()
   """;
   

2. Exécutez la requête spécifiant le Montau Turtle Surfboard produit.

   ResultSet<Dictionary<string, object>> findResults = await client.SubmitAsync<Dictionary<string, object>>(findVerticesQuery, new Dictionary<string, object>
   {
       ["prop_partition_key"] = "gear-surf-surfboards",
       ["prop_name"] = "Montau Turtle Surfboard"
   });
   

3. Itérer sur les résultats de la requête.

   foreach (Dictionary<string, object> result in findResults)
   {
       // Do something here with each result
   }
   

Exécuter le code

Exécutez l’application nouvellement créée à l’aide d’un terminal dans votre répertoire d’application.

dotnet run

Nettoyer les ressources

Lorsque vous n’avez plus besoin du compte, supprimez le compte de votre abonnement Azure en supprimant la ressource.

az cosmosdb delete \
    --resource-group "<resource-group-name>" \
    --name "<account-name>"