Démarrage rapide : Créer une application .NET Framework ou Core à l’aide du compte d’API Gremlin Azure Cosmos DBQuickstart: Build a .NET Framework or Core application using the Azure Cosmos DB Gremlin API account

Azure Cosmos DB est le service de base de données multi-modèle de Microsoft distribué à l’échelle mondiale.Azure Cosmos DB is Microsoft's globally distributed multi-model database service. Rapidement, vous avez la possibilité de créer et d’interroger des documents, des paires clé/valeur, et des bases de données orientées graphe, profitant tous de la distribution à l’échelle mondiale et des capacités de mise à l’échelle horizontale au cœur d’Azure Cosmos DB.You can quickly create and query document, key/value, and graph databases, all of which benefit from the global distribution and horizontal scale capabilities at the core of Azure Cosmos DB.

Ce guide de démarrage rapide explique comment créer un compte, une base de données et un graphe (conteneur) API Gremlin Azure Cosmos DB à l’aide du portail Azure.This quickstart demonstrates how to create an Azure Cosmos DB Gremlin API account, database, and graph (container) using the Azure portal. Par la suite, vous allez créer et exécuter une application console en utilisant le pilote Gremlin.Net open-source.You then build and run a console app built using the open-source driver Gremlin.Net.

Conditions préalables requisesPrerequisites

Si vous n’avez pas encore installé Visual Studio 2019, vous pouvez télécharger et utiliser la version gratuite Visual Studio 2019 Community Edition.If you don't already have Visual Studio 2019 installed, you can download and use the free Visual Studio 2019 Community Edition. Veillez à activer le développement Azure lors de l’installation de Visual Studio.Make sure that you enable Azure development during the Visual Studio setup.

Si vous n’avez pas d’abonnement Azure, créez un compte gratuit avant de commencer.If you don't have an Azure subscription, create a free account before you begin.

Création d’un compte de base de donnéesCreate a database account

  1. Dans une nouvelle fenêtre du navigateur, connectez-vous au portail Azure.In a new browser window, sign in to the Azure portal.

  2. Cliquez sur Créer une ressource > Bases de données > Azure Cosmos DB.Click Create a resource > Databases > Azure Cosmos DB.

    Volet « Bases de données » du portail Azure

  3. Dans la page Créer un compte Azure Cosmos DB, entrez les paramètres du nouveau compte Azure Cosmos DB.In the Create Azure Cosmos DB Account page, enter the settings for the new Azure Cosmos DB account.

    ParamètreSetting ValeurValue DescriptionDescription
    SubscriptionSubscription Votre abonnementYour subscription Sélectionnez l’abonnement Azure que vous souhaitez utiliser pour ce compte Azure Cosmos DB.Select the Azure subscription that you want to use for this Azure Cosmos DB account.
    Groupe de ressourcesResource Group CréationCreate new

    Entrez ensuite le même nom unique que celui fourni dans l’IDThen enter the same unique name as provided in ID
    Sélectionnez Créer nouveau.Select Create new. Entrez ensuite le nom du nouveau groupe de ressources pour votre compte.Then enter a new resource-group name for your account. Pour rester simple, utilisez le même nom que celui de votre ID.For simplicity, use the same name as your ID.
    Nom du compteAccount Name Entrez un nom uniqueEnter a unique name Entrez un nom unique pour identifier votre compte Azure Cosmos DB.Enter a unique name to identify your Azure Cosmos DB account. Étant donné que documents.azure.com est ajouté à l’ID que vous fournissez pour créer votre URI, utilisez un ID unique.Because documents.azure.com is appended to the ID that you provide to create your URI, use a unique ID.

    L’ID peut uniquement utiliser des lettres minuscules, des chiffres et le caractère de trait d’union (-).The ID can use only lowercase letters, numbers, and the hyphen (-) character. Il doit comprendre entre 3 et 31 caractères.It must be between 3 and 31 characters in length.
    APIAPI Gremlin (graphique)Gremlin (graph) L’API détermine le type de compte à créer.The API determines the type of account to create. Azure Cosmos DB fournit cinq API : Core(SQL) pour les bases de données orientées document, Gremlin pour les bases de données de graphe, MongoDB pour les bases de données de document, Table Azure et Cassandra.Azure Cosmos DB provides five APIs: Core(SQL) for document databases, Gremlin for graph databases, MongoDB for document databases, Azure Table, and Cassandra. Actuellement, vous devez créer un compte distinct pour chaque API.Currently, you must create a separate account for each API.

    Sélectionnez Gremlin (graphe) , car dans ce guide de démarrage rapide, vous créez une table qui fonctionne avec l’API Gremlin.Select Gremlin (graph) because in this quickstart you are creating a table that works with the Gremlin API.

    Découvrez plus d’informations sur l’API Graph.Learn more about the Graph API.
    LocationLocation Sélectionner la région la plus proche de vos utilisateursSelect the region closest to your users Sélectionnez la zone géographique dans laquelle héberger votre compte Azure Cosmos DB.Select a geographic location to host your Azure Cosmos DB account. Utilisez l’emplacement le plus proche de vos utilisateurs, pour leur donner l’accès le plus rapide possible aux données.Use the location that's closest to your users to give them the fastest access to the data.

    Sélectionnez Vérifier + créer.Select Review+Create. Vous pouvez ignorer les sections Réseau et Balises.You can skip the Network and Tags section.

    La section Nouveau compte pour Azure Cosmos DB

  4. La création du compte prend quelques minutes.The account creation takes a few minutes. Attendez que le portail affiche la page Félicitations ! Votre compte Azure Cosmos DB a été créé.Wait for the portal to display the Congratulations! Your Azure Cosmos DB account was created page.

    Volet Notifications du portail Azure

Ajout d’un graphiqueAdd a graph

Vous pouvez désormais utiliser l’outil Explorateur de données dans le portail Azure pour créer une base de données de graphiques.You can now use the Data Explorer tool in the Azure portal to create a graph database.

  1. Sélectionnez Data Explorer > Nouveau graphique.Select Data Explorer > New Graph.

    La zone Ajouter un graphique est affichée à l’extrême droite. Il peut donc être nécessaire de faire défiler à droite pour l’afficher.The Add Graph area is displayed on the far right, you may need to scroll right to see it.

    Explorateur de données du portail Azure, page Ajouter un graphique

  2. Dans la page Ajouter un graphique, entrez les paramètres relatifs au nouveau graphique.In the Add graph page, enter the settings for the new graph.

    ParamètreSetting Valeur suggéréeSuggested value DescriptionDescription
    ID de base de donnéesDatabase ID sample-databasesample-database Entrez le nom sample-database pour la nouvelle base de données.Enter sample-database as the name for the new database. Les noms de base de données doivent inclure entre 1 et 255 caractères et ne peuvent pas contenir / \ # ? ni d’espace de fin.Database names must be between 1 and 255 characters, and cannot contain / \ # ? or a trailing space.
    DébitThroughput 400 unités de requête400 RUs Changez le débit en indiquant 400 unités de requête par seconde (RU/s).Change the throughput to 400 request units per second (RU/s). Si vous souhaitez réduire la latence, vous pourrez augmenter le débit par la suite.If you want to reduce latency, you can scale up the throughput later.
    ID du graphiqueGraph ID sample-graphsample-graph Entrez le nom sample-graph pour votre nouvelle collection.Enter sample-graph as the name for your new collection. Les noms de graphiques sont soumis aux mêmes exigences de nombre de caractères que les ID de bases de données.Graph names have the same character requirements as database IDs.
    Partition KeyPartition Key /pk/pk Tous les comptes Cosmos DB ont besoin d’une clé de partition se mettre à l’échelle horizontalement.All Cosmos DB accounts need a partition key to horizontally scale. Découvrez comment sélectionner une clé de partition appropriée dans l'article sur le partitionnement des données graphiques.Learn how to select an appropriate partition key in the Graph Data Partitioning article.
  3. Une fois le formulaire rempli, sélectionnez OK.Once the form is filled out, select OK.

Clonage de l’exemple d’applicationClone the sample application

À présent, nous allons cloner une application API Gremlin à partir de GitHub, configurer la chaîne de connexion et l’exécuter.Now let's clone a Gremlin API app from GitHub, set the connection string, and run it. Vous verrez combien il est facile de travailler par programmation avec des données.You'll see how easy it is to work with data programmatically.

  1. Ouvrez une invite de commandes, créez un nouveau dossier nommé git-samples, puis fermez l’invite de commandes.Open a command prompt, create a new folder named git-samples, then close the command prompt.

    md "C:\git-samples"
    
  2. Ouvrez une fenêtre de terminal git comme Git Bash et utilisez la commande cd pour accéder au nouveau dossier d’installation pour l’exemple d’application.Open a git terminal window, such as git bash, and use the cd command to change to the new folder to install the sample app.

    cd "C:\git-samples"
    
  3. Exécutez la commande suivante pour cloner l’exemple de référentiel :Run the following command to clone the sample repository. Cette commande crée une copie de l’exemple d’application sur votre ordinateur.This command creates a copy of the sample app on your computer.

    git clone https://github.com/Azure-Samples/azure-cosmos-db-graph-gremlindotnet-getting-started.git
    
  4. Ouvrez ensuite Visual Studio et le fichier de solution.Then open Visual Studio and open the solution file.

  5. Restaurez les packages NuGet dans le projet.Restore the NuGet packages in the project. Sont concernés ici le pilote Gremlin.Net et le package Newtonsoft.Json.This should include the Gremlin.Net driver, as well as the Newtonsoft.Json package.

  6. Vous pouvez également installer le pilote Gremlin.Net manuellement à l’aide du gestionnaire de package Nuget ou de l’utilitaire de ligne de commande nuget :You can also install the Gremlin.Net driver manually using the Nuget package manager, or the nuget command-line utility:

    nuget install Gremlin.Net
    

Vérifier le codeReview the code

Cette étape est facultative.This step is optional. Pour savoir comment les ressources de base de données sont créées dans le code, vous pouvez examiner les extraits de code suivants.If you're interested in learning how the database resources are created in the code, you can review the following snippets. Sinon, vous pouvez passer à l’étape Mise à jour de votre chaîne de connexion.Otherwise, you can skip ahead to Update your connection string.

Tous les extraits de code suivants proviennent du fichier Program.cs.The following snippets are all taken from the Program.cs file.

  • Définissez vos paramètres de connexion en fonction du compte créé ci-dessus (ligne 19) :Set your connection parameters based on the account created above (Line 19):

    private static string hostname = "your-endpoint.gremlin.cosmosdb.azure.com";
    private static int port = 443;
    private static string authKey = "your-authentication-key";
    private static string database = "your-database";
    private static string collection = "your-graph-container";
    
  • Les commandes Gremlin à exécuter sont répertoriées dans un dictionnaire (ligne 26) :The Gremlin commands to be executed are listed in a Dictionary (Line 26):

    private static Dictionary<string, string> gremlinQueries = new Dictionary<string, string>
    {
        { "Cleanup",        "g.V().drop()" },
        { "AddVertex 1",    "g.addV('person').property('id', 'thomas').property('firstName', 'Thomas').property('age', 44).property('pk', 'pk')" },
        { "AddVertex 2",    "g.addV('person').property('id', 'mary').property('firstName', 'Mary').property('lastName', 'Andersen').property('age', 39).property('pk', 'pk')" },
        { "AddVertex 3",    "g.addV('person').property('id', 'ben').property('firstName', 'Ben').property('lastName', 'Miller').property('pk', 'pk')" },
        { "AddVertex 4",    "g.addV('person').property('id', 'robin').property('firstName', 'Robin').property('lastName', 'Wakefield').property('pk', 'pk')" },
        { "AddEdge 1",      "g.V('thomas').addE('knows').to(g.V('mary'))" },
        { "AddEdge 2",      "g.V('thomas').addE('knows').to(g.V('ben'))" },
        { "AddEdge 3",      "g.V('ben').addE('knows').to(g.V('robin'))" },
        { "UpdateVertex",   "g.V('thomas').property('age', 44)" },
        { "CountVertices",  "g.V().count()" },
        { "Filter Range",   "g.V().hasLabel('person').has('age', gt(40))" },
        { "Project",        "g.V().hasLabel('person').values('firstName')" },
        { "Sort",           "g.V().hasLabel('person').order().by('firstName', decr)" },
        { "Traverse",       "g.V('thomas').out('knows').hasLabel('person')" },
        { "Traverse 2x",    "g.V('thomas').out('knows').hasLabel('person').out('knows').hasLabel('person')" },
        { "Loop",           "g.V('thomas').repeat(out()).until(has('id', 'robin')).path()" },
        { "DropEdge",       "g.V('thomas').outE('knows').where(inV().has('id', 'mary')).drop()" },
        { "CountEdges",     "g.E().count()" },
        { "DropVertex",     "g.V('thomas').drop()" },
    };
    
  • Créez un objet de connexion GremlinServer à l’aide des paramètres fournis ci-dessus (ligne 52) :Create a GremlinServer connection object using the parameters provided above (Line 52):

    var gremlinServer = new GremlinServer(hostname, port, enableSsl: true, 
                                                    username: "/dbs/" + database + "/colls/" + collection, 
                                                    password: authKey);
    
  • Créez un nouvel objet GremlinClient (ligne 56) :Create a new GremlinClient object (Line 56):

    var gremlinClient = new GremlinClient(gremlinServer, new GraphSON2Reader(), new GraphSON2Writer(), GremlinClient.GraphSON2MimeType);
    
  • Exécutez chaque requête Gremlin à l’aide de l’objet GremlinClient avec une tâche asynchrone (ligne 63).Execute each Gremlin query using the GremlinClient object with an async task (Line 63). Les requêtes Gremlin seront lues à partir du dictionnaire défini ci-dessus (ligne 26) :This will read the Gremlin queries from the dictionary defined above (Line 26):

    var results = await gremlinClient.SubmitAsync<dynamic>(query.Value);
    
  • Récupérez le résultat et lisez les valeurs, qui sont formatées sous forme de dictionnaire, à l’aide de la classe JsonSerializer de Newtonsoft.Json :Retrieve the result and read the values, which are formatted as a dictionary, using the JsonSerializer class from Newtonsoft.Json:

    foreach (var result in results)
    {
        // The vertex results are formed as dictionaries with a nested dictionary for their properties
        string output = JsonConvert.SerializeObject(result);
        Console.WriteLine(String.Format("\tResult:\n\t{0}", output));
    }
    

Mise à jour de votre chaîne de connexionUpdate your connection string

Maintenant, retournez dans le portail Azure afin d’obtenir les informations de votre chaîne de connexion et de les copier dans l’application.Now go back to the Azure portal to get your connection string information and copy it into the app.

  1. À partir du Portail Azure, accédez à votre compte de base de données de graphiques.From the Azure portal, navigate to your graph database account. Dans l’onglet Vue d’ensemble, vous pouvez voir deux points de terminaison :In the Overview tab, you can see two endpoints-

    URI du SDK .NET : cette valeur est utilisée quand vous vous connectez au compte de graphiques à l’aide de la bibliothèque Microsoft.Azure.Graphs..NET SDK URI - This value is used when you connect to the graph account by using Microsoft.Azure.Graphs library.

    Point de terminaison Gremlin : cette valeur est utilisée lorsque vous vous connectez au compte de graphiques à l’aide de la bibliothèque Gremlin.Net.Gremlin Endpoint - This value is used when you connect to the graph account by using Gremlin.Net library.

    Copier le point de terminaison

    Pour exécuter cet exemple, copiez la valeur Point de terminaison Gremlin, supprimez le numéro de port à la fin, et l’URI devient https://<your cosmos db account name>.gremlin.cosmosdb.azure.comTo run this sample, copy the Gremlin Endpoint value, delete the port number at the end, that is the URI becomes https://<your cosmos db account name>.gremlin.cosmosdb.azure.com

  2. Dans Program.cs, collez les valeurs sur your-endpoint dans la variable hostname de la ligne 19.In Program.cs paste the value over your-endpoint in the hostname variable in line 19.

    "private static string hostname = "<your cosmos db account name>.gremlin.cosmosdb.azure.com";

    La valeur de point de terminaison doit maintenant ressembler à ceci :The endpoint value should now look like this:

    "private static string hostname = "testgraphacct.gremlin.cosmosdb.azure.com";

  3. Ensuite, accédez à l’onglet Clés et copiez votre valeur de CLÉ PRIMAIRE à partir du portail, puis collez-la dans la variable authkey, en remplaçant l’espace réservé "your-authentication-key" dans la ligne 21.Next, navigate to the Keys tab and copy PRIMARY KEY value from the portal, and paste it in the authkey variable, replacing the "your-authentication-key" placeholder in line 21.

    private static string authKey = "your-authentication-key";

  4. En vous appuyant sur les informations de la base de données créée ci-dessus, collez le nom de la base de données dans la variable database de la ligne 22.Using the information of the database created above, paste the database name inside of the database variable in line 22.

    private static string database = "your-database";

  5. De la même manière, en vous appuyant sur les informations du conteneur créé ci-dessus, collez la collection (qui est également le nom du graphique) dans la variable collection de la ligne 23.Similarly, using the information of the container created above, paste the collection (which is also the graph name) inside of the collection variable in line 23.

    private static string collection = "your-collection-or-graph";

  6. Enregistrez le fichier Program.cs.Save the Program.cs file.

Vous venez de mettre à jour votre application avec toutes les informations nécessaires pour communiquer avec Azure Cosmos DB.You've now updated your app with all the info it needs to communicate with Azure Cosmos DB.

Exécution de l’application consoleRun the console app

Appuyez sur Ctrl + F5 pour exécuter l’application.Click CTRL + F5 to run the application. L’application imprime les commandes de requête Gremlin et les résultats dans la console.The application will print both the Gremlin query commands and results in the console.

La fenêtre de console affiche les sommets et les bords ajoutés au graphique.The console window displays the vertexes and edges being added to the graph. Lorsque le script se termine, appuyez sur ENTRÉE pour fermer la fenêtre de console.When the script completes, press ENTER to close the console window.

Navigation à l’aide de l’Explorateur de donnéesBrowse using the Data Explorer

Vous pouvez maintenant retourner à l’Explorateur de données dans le Portail Azure pour parcourir et interroger vos nouvelles données graphiques.You can now go back to Data Explorer in the Azure portal and browse and query your new graph data.

  1. Dans l’Explorateur de données, la nouvelle base de données apparaît dans le volet Graphique.In Data Explorer, the new database appears in the Graphs pane. Développez les nœuds de conteneur et de base de données, puis cliquez sur Graphique.Expand the database and container nodes, and then click Graph.

  2. Cliquez sur le bouton Appliquer un filtre pour utiliser la requête par défaut et afficher tous les vertex dans le graphique.Click the Apply Filter button to use the default query to view all the vertices in the graph. Les données générées par l’exemple d’application s’affichent dans le volet Graphiques.The data generated by the sample app is displayed in the Graphs pane.

    Vous pouvez agrandir et réduire le graphique, développer l’espace d’affichage du graphique, ajouter des vertex et déplacer des vertex sur la surface d’affichage.You can zoom in and out of the graph, you can expand the graph display space, add additional vertices, and move vertices on the display surface.

    Afficher le graphique dans l’Explorateur de données dans le portail Azure

Vérification des contrats SLA dans le portail AzureReview SLAs in the Azure portal

Le portail Azure supervise le débit, le stockage, la disponibilité, la latence et la cohérence de votre compte Cosmos DB.The Azure portal monitors your Cosmos DB account throughput, storage, availability, latency, and consistency. Des graphiques de métriques associées à un contrat de niveau Service (SLA) Azure Cosmos DB montrent la valeur des contrats SLA par rapport aux performances réelles.Charts for metrics associated with an Azure Cosmos DB Service Level Agreement (SLA) show the SLA value compared to actual performance. Cette suite de métriques vous permet de superviser vos contrats SLA de manière transparente.This suite of metrics makes monitoring your SLAs transparent.

Pour consulter les métriques et les contrats SLA :To review metrics and SLAs:

  1. Sélectionnez Métriques dans le menu de navigation de votre compte Cosmos DB.Select Metrics in your Cosmos DB account's navigation menu.

  2. Sélectionnez un onglet comme Latence, puis sélectionnez un intervalle de temps à droite.Select a tab such as Latency, and select a timeframe on the right. Comparez les lignes Réel et SLA des graphiques.Compare the Actual and SLA lines on the charts.

    Suite de métriques d’Azure Cosmos DB

  3. Consultez les métriques des autres onglets.Review the metrics on the other tabs.

Nettoyer les ressourcesClean up resources

Quand vous en avez terminé avec votre application web et votre compte Azure Cosmos DB, vous pouvez supprimer les ressources Azure que vous avez créées afin d’éviter des frais supplémentaires.When you're done with your web app and Azure Cosmos DB account, you can delete the Azure resources you created so you don't incur more charges. Pour supprimer les ressources :To delete the resources:

  1. Dans le portail Azure, sélectionnez Groupes de ressources tout à gauche.In the Azure portal, select Resource groups on the far left. Si le menu de gauche est réduit, sélectionnez le bouton Développer pour le développer.If the left menu is collapsed, select Expand button to expand it.

  2. Sélectionnez le groupe de ressources créé dans ce guide de démarrage rapide.Select the resource group you created for this quickstart.

    Sélectionner le groupe de ressources à supprimer

  3. Dans la nouvelle fenêtre, sélectionnez Supprimer le groupe de ressources.In the new window, select Delete resource group.

    Supprimer le groupe de ressources

  4. Dans la fenêtre suivante, entrez le nom du groupe de ressources à supprimer, puis sélectionnez Supprimer.In the next window, enter the name of the resource group to delete, and then select Delete.

Étapes suivantesNext steps

Dans ce guide de démarrage rapide, vous avez appris à créer un compte Azure Cosmos D, à créer un graphique à l’aide de l’Explorateur de données et à exécuter une application.In this quickstart, you've learned how to create an Azure Cosmos DB account, create a graph using the Data Explorer, and run an app. Vous pouvez maintenant générer des requêtes plus complexes et implémenter une logique de traversée de graphique puissante, à l’aide de Gremlin.You can now build more complex queries and implement powerful graph traversal logic using Gremlin.