Démarrage rapide : Créer une base de données de graphe avec le SDK Java et l’API Azure Cosmos DB GremlinQuickstart: Build a graph database with the Java SDK and the Azure Cosmos DB Gremlin API

Dans ce guide de démarrage rapide, vous allez créer et gérer un compte d’API Azure Cosmos DB Gremlin (graphe) à partir du portail Azure et ajouter des données à l’aide d’une application Java clonée à partir de GitHub.In this quickstart, you create and manage an Azure Cosmos DB Gremlin (graph) API account from the Azure portal, and add data by using a Java app cloned from GitHub. Azure Cosmos DB est un service de base de données multimodèle qui vous permet de créer et d’interroger rapidement des bases de données de documents, de tables, de paires clé/valeur et de graphes avec des capacités de distribution mondiale et de mise à l’échelle horizontale.Azure Cosmos DB is a multi-model database service that lets you quickly create and query document, table, key-value, and graph databases with global distribution and horizontal scale capabilities.

Conditions préalables requisesPrerequisites

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

Pour être en mesure de créer une base de données de graphes, vous devez avoir préalablement créé un compte de base de données Gremlin (Graphe) avec Azure Cosmos DB.Before you can create a graph database, you need to create a Gremlin (Graph) database account with Azure Cosmos DB.

  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. Dans le menu de gauche, sélectionnez Créer une ressource.In the left menu, select Create a resource.

    Créer une ressource dans le portail Azure

  3. Dans la page Nouveau, sélectionnez Bases de données > Azure Cosmos DB.On the New page, select Databases > Azure Cosmos DB.

    Volet Bases de données du portail Azure

  4. Dans la page Créer un compte Azure Cosmos DB, entrez les paramètres du nouveau compte Azure Cosmos DB.On 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 que le nom du compteThen enter the same name as Account Name
    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 nom de votre compte Azure Cosmos DB.For simplicity, use the same name as your Azure Cosmos DB account name.
    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. L’URI de votre compte sera gremlin.azure.com apposé à votre nom de compte unique.Your account URI will be gremlin.azure.com appended to your unique account name.

    Le nom peut contenir uniquement des lettres minuscules, des chiffres et des traits d’union (-), et doit comporter entre 3 et 31 caractères.The account name can use only lowercase letters, numbers, and hyphens (-), and must be between 3 and 31 characters long.
    APIAPI Gremlin (graphe)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 de documents, Gremlin pour les bases de données de graphes, MongoDB pour les bases de données de documents, 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. Vous devez créer un compte distinct pour chaque API.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 Gremlin.Learn more about the Gremlin 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.

    Page de nouveau compte pour Azure Cosmos DB

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

    Page Compte Azure Cosmos DB créé

Ajout d’un grapheAdd 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, travaillons sur le code.Now let's switch to working with code. Nous allons cloner une application API Gremlin à partir de GitHub, configurer la chaîne de connexion et l’exécuter.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 à un 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 a 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-java-getting-started.git
    

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 sont tirés du fichier C:\git-samples\azure-cosmos-db-graph-java-getting-started\src\GetStarted\Program.java.The following snippets are all taken from the C:\git-samples\azure-cosmos-db-graph-java-getting-started\src\GetStarted\Program.java file.

Cette application console Java utilise une base de données d’API Gremlin avec le pilote OSS Apache TinkerPop.This Java console app uses a Gremlin API database with the OSS Apache TinkerPop driver.

  • Le Client Gremlin est initialisé à partir de la configuration dans le fichier C:\git-samples\azure-cosmos-db-graph-java-getting-started\src\remote.yaml.The Gremlin Client is initialized from the configuration in the C:\git-samples\azure-cosmos-db-graph-java-getting-started\src\remote.yaml file.

    cluster = Cluster.build(new File("src/remote.yaml")).create();
    ...
    client = cluster.connect();
    
  • Une série d’étapes Gremlin sont exécutées à l’aide de la méthode client.submit.Series of Gremlin steps are executed using the client.submit method.

    ResultSet results = client.submit(gremlin);
    
    CompletableFuture<List<Result>> completableFutureResults = results.all();
    List<Result> resultList = completableFutureResults.get();
    
    for (Result result : resultList) {
        System.out.println(result.toString());
    }
    

Mise à jour de vos informations de connexionUpdate your connection information

Maintenant, retournez dans le portail Azure afin d’obtenir vos informations de connexion et de les copier dans l’application.Now go back to the Azure portal to get your connection information and copy it into the app. Ces paramètres permettent à votre application de communiquer avec votre base de données hébergée.These settings enable your app to communicate with your hosted database.

  1. Dans votre compte Azure Cosmos DB, sur le portail Azure, sélectionnez Clés.In your Azure Cosmos DB account in the Azure portal, select Keys.

    Copiez la première partie de la valeur de l’URI.Copy the first portion of the URI value.

    Affichage et copie d’une clé d’accès rapide dans le portail Azure, page Clés

  2. Ouvrez le fichier src/remote.yaml et collez la valeur d’ID unique sur $name$ dans hosts: [$name$.graphs.azure.com].Open the src/remote.yaml file and paste the unique ID value over $name$ in hosts: [$name$.graphs.azure.com].

    La ligne 1 du fichier remote.yaml doit maintenant ressembler à la ligne suivante :Line 1 of remote.yaml should now look similar to

    hosts: [test-graph.graphs.azure.com]

  3. Remplacez graphs par gremlin.cosmosdb dans la valeur endpoint.Change graphs to gremlin.cosmosdb in the endpoint value. (Si vous avez créé votre compte de base de données de graphes avant le 20 décembre 2017, n’apportez aucune modification à la valeur de point de terminaison et passez à l’étape suivante.)(If you created your graph database account before December 20, 2017, make no changes to the endpoint value and continue to the next step.)

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

    "endpoint": "https://testgraphacct.gremlin.cosmosdb.azure.com:443/"

  4. Dans le portail Azure, utilisez le bouton de copie pour copier la CLÉ PRIMAIRE, puis collez-la sur $masterKey$ dans password: $masterKey$.In the Azure portal, use the copy button to copy the PRIMARY KEY and paste it over $masterKey$ in password: $masterKey$.

    La ligne 4 du fichier remote.yaml doit maintenant ressembler à la ligne suivante :Line 4 of remote.yaml should now look similar to

    password: 2Ggkr662ifxz2Mg==

  5. Modifiez la ligne 3 du fichier remote.yaml en remplaçantChange line 3 of remote.yaml from

    username: /dbs/$database$/colls/$collection$

    toto

    username: /dbs/sample-database/colls/sample-graph

    Si vous avez utilisé un nom unique pour votre exemple de base de données ou de graphe, mettez à jour les valeurs comme nécessaire.If you used a unique name for your sample database or graph, update the values as appropriate.

  6. Enregistrez le fichier remote.yaml.Save the remote.yaml file.

Exécution de l’application consoleRun the console app

  1. Dans la fenêtre de terminal git, exécutez la commande cd pour accéder au dossier azure-cosmos-db-graph-java-getting-started.In the git terminal window, cd to the azure-cosmos-db-graph-java-getting-started folder.

    cd "C:\git-samples\azure-cosmos-db-graph-java-getting-started"
    
  2. Dans la fenêtre de terminal git, utilisez la commande suivante pour installer les packages Java requis.In the git terminal window, use the following command to install the required Java packages.

    mvn package
    
  3. Dans la fenêtre de terminal git, utilisez la commande suivante pour démarrer l’application Java.In the git terminal window, use the following command to start the Java application.

    mvn exec:java -D exec.mainClass=GetStarted.Program
    

    La fenêtre de terminal affiche les sommets ajoutés au graphe.The terminal window displays the vertices being added to the graph.

    Si vous rencontrez des erreurs de délai d’expiration, vérifiez que vous avez correctement mis à jour les informations de connexion dans Mise à jour de vos informations de connexion et essayez également de réexécuter la dernière commande.If you experience timeout errors, check that you updated the connection information correctly in Update your connection information, and also try running the last command again.

    Une fois le programme terminé, sélectionnez Entrée, puis rebasculez vers le portail Azure dans votre navigateur Internet.Once the program stops, select Enter, then switch back to the Azure portal in your internet browser.

Examiner et ajouter des exemples de donnéesReview and add sample data

Vous pouvez à présent revenir à l’Explorateur de données et voir les sommets ajoutés au graphe, ainsi qu’ajouter des points de données supplémentaires.You can now go back to Data Explorer and see the vertices added to the graph, and add additional data points.

  1. Dans votre compte Azure Cosmos DB, dans le portail Azure, sélectionnez Explorateur de données, développez sample-graph, sélectionnez Graphe, puis sélectionnez Appliquer un filtre.In your Azure Cosmos DB account in the Azure portal, select Data Explorer, expand sample-graph, select Graph, and then select Apply Filter.

    Créer des documents dans l’Explorateur de données, dans le Portail Azure

  2. Dans la liste Résultats, observez les nouveaux utilisateurs ajoutés au graphe.In the Results list, notice the new users added to the graph. Sélectionnez ben et notez que l’utilisateur est connecté à robin.Select ben and notice that the user is connected to robin. Vous pouvez glisser-déplacez les sommets, effectuer un zoom avant et arrière à l’aide de la roulette de la souris et augmenter la taille du graphe avec la double flèche.You can move the vertices around by dragging and dropping, zoom in and out by scrolling the wheel of your mouse, and expand the size of the graph with the double-arrow.

    Nouveaux sommets dans le graphe de l’Explorateur de données du portail Azure

  3. Nous allons à présent ajouter quelques nouveaux utilisateurs.Let's add a few new users. Sélectionnez Nouveau sommet pour ajouter des données à votre graphe.Select New Vertex to add data to your graph.

    Créer des documents dans l’Explorateur de données, dans le Portail Azure

  4. Dans la zone d’étiquette, entrez personne.In the label box, enter person.

  5. Sélectionnez Ajouter une propriété pour ajouter chacune des propriétés suivantes.Select Add property to add each of the following properties. Notez que vous pouvez créer des propriétés uniques pour chaque personne dans votre graphe.Notice that you can create unique properties for each person in your graph. Seule la clé id est obligatoire.Only the id key is required.

    keykey valuevalue NotesNotes
    idid ashleyashley Identificateur unique du sommet.The unique identifier for the vertex. Si vous ne spécifiez aucun id, le système en génère un pour vous.If you don't specify an id, one is generated for you.
    gendergender femalefemale
    techtech javajava

    Notes

    Dans ce Démarrage rapide, vous créez une collection non partitionnée.In this quickstart you create a non-partitioned collection. Toutefois, si vous créez une collection partitionnée en spécifiant une clé de partition lors de la création de la collection, vous devez inclure la clé de partition en tant que clé dans chaque nouveau sommet.However, if you create a partitioned collection by specifying a partition key during the collection creation, then you need to include the partition key as a key in each new vertex.

  6. Sélectionnez OK.Select OK. Vous pouvez avoir besoin d’agrandir votre écran pour voir apparaître le bouton OK au bas de l’écran.You may need to expand your screen to see OK on the bottom of the screen.

  7. Sélectionnez de nouveau Nouveau sommet et ajoutez un nouvel utilisateur supplémentaire.Select New Vertex again and add an additional new user.

  8. Entrez l’étiquette person.Enter a label of person.

  9. Sélectionnez Ajouter une propriété pour ajouter chacune des propriétés suivantes :Select Add property to add each of the following properties:

    keykey valuevalue NotesNotes
    idid rakeshrakesh Identificateur unique du sommet.The unique identifier for the vertex. Si vous ne spécifiez aucun id, le système en génère un pour vous.If you don't specify an id, one is generated for you.
    gendergender malemale
    schoolschool MITMIT
  10. Sélectionnez OK.Select OK.

  11. Sélectionnez le bouton Appliquer un filtre avec le filtre par défaut g.V() pour afficher toutes les valeurs dans le graphe.Select the Apply Filter button with the default g.V() filter to display all the values in the graph. Tous les utilisateurs apparaissent désormais dans la liste Résultats.All of the users now show in the Results list.

    À mesure que vous ajoutez d’autres données, vous pouvez utiliser des filtres pour limiter les résultats renvoyés.As you add more data, you can use filters to limit your results. Par défaut, l’Explorateur de données utilise g.V() pour récupérer tous les sommets d’un graphe.By default, Data Explorer uses g.V() to retrieve all vertices in a graph. Vous pouvez choisir une autre requête de graphe comme g.V().count() pour retourner le nombre total de sommets du graphe au format JSON.You can change it to a different graph query, such as g.V().count(), to return a count of all the vertices in the graph in JSON format. Si vous avez modifié le filtre, choisissez de nouveau le filtre g.V() et sélectionnez Appliquer un filtre pour afficher de nouveau l’ensemble des résultats.If you changed the filter, change the filter back to g.V() and select Apply Filter to display all the results again.

  12. À présent, vous pouvez connecter rakesh et ashley.Now you can connect rakesh, and ashley. Vérifiez que ashley est bien sélectionné dans la liste Résultats, puis sélectionnez Modifier la cible d’un sommet dans un graphe en regard de Cibles dans la partie inférieure droite de l’écran.Ensure ashley is selected in the Results list, then select Change the target of a vertex in a graph next to Targets on lower right side. Vous devrez peut-être élargir la fenêtre pour voir le bouton.You may need to widen your window to see the button.

    Changer la cible d’un sommet dans un graphe - Azure Cosmos DB

  13. Dans la zone Cible, entrez rakesh, et dans la zone Edge label (Étiquette de relation) , entrez knows, puis cochez la case.In the Target box enter rakesh, and in the Edge label box enter knows, and then select the check box.

    Ajouter une connexion dans l’Explorateur de données - Azure Cosmos DB

  14. À présent, sélectionnez rakesh dans la liste des résultats et vérifiez qu’ashley et rakesh sont connectés.Now select rakesh from the results list and see that ashley and rakesh are connected.

    Deux sommets connectés dans l’Explorateur de données - Azure Cosmos DB

Ainsi s’achève la portion de ce didacticiel consacrée à la création de ressources.That completes the resource creation part of this tutorial. Vous pouvez continuer à ajouter des sommets à votre graphe, modifier les sommets existants ou changer les requêtes.You can continue to add vertexes to your graph, modify the existing vertexes, or change the queries. Nous allons à présent examiner les métriques fournies par Azure Cosmos DB et nettoyer les ressources.Now let's review the metrics Azure Cosmos DB provides, and then clean up the resources.

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 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 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. Depuis la barre de recherche du portail Azure, recherchez et sélectionnez Groupes de ressources.In the Azure portal Search bar, search for and select Resource groups.

  2. Dans la liste, sélectionnez le groupe de ressources créé pour ce guide de démarrage rapide.From the list, select the resource group you created for this quickstart.

    Sélectionner le groupe de ressources à supprimer

  3. Dans la page Vue d’ensemble du groupe de ressources, sélectionnez Supprimer un groupe de ressources.On the resource group Overview page, 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 DB, à créer un graphe à l’aide de l’Explorateur de données et à exécuter une application Java qui ajoute des données au graphe.In this quickstart, you learned how to create an Azure Cosmos DB account, create a graph using the Data Explorer, and run a Java app that adds data to the graph. Vous pouvez maintenant générer des requêtes plus complexes et implémenter une logique de traversée de graphe puissante en utilisant Gremlin.You can now build more complex queries and implement powerful graph traversal logic using Gremlin.