Démarrage rapide : Créer une base de données de graphe dans Azure Cosmos DB à l’aide de Python et du portail AzureQuickstart: Create a graph database in Azure Cosmos DB using Python and the Azure portal

Ce guide de démarrage rapide montre comment utiliser Python et l’API Gremlin d’Azure Cosmos DB pour créer une application console en clonant un exemple à partir de GitHub.This quickstart shows how to use Python and the Azure Cosmos DB Gremlin API to build a console app by cloning an example from GitHub. Ce guide de démarrage rapide vous montre également comment créer un compte Azure Cosmos DB en utilisant le portail web Azure.This quickstart also walks you through the creation of an Azure Cosmos DB account by using the web-based Azure portal.

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. Vous pouvez rapidement créer et interroger des bases de données de documents, de tables, de paires clé/valeur et de graphes, lesquelles bénéficient toutes des fonctionnalités de distribution mondiale et de mise à l’échelle horizontale d’Azure Cosmos DB.You can quickly create and query document, table, key-value, and graph databases, all of which benefit from the global distribution and horizontal scale capabilities at the core of Azure Cosmos DB.

Notes

Ce démarrage rapide nécessite un compte de base de données de graphiques créé après le 20 décembre 2017.This quickstart requires a graph database account created after December 20th, 2017. Les comptes existants prendront en charge Python une fois la migration vers la disponibilité générale effectuée.Existing accounts will support Python once they’re migrated to general availability.

PrérequisPrerequisites

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. Vous pouvez également essayer Azure Cosmos DB gratuitement sans abonnement Azure, ni frais ni engagement.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. Alternatively, you can Try Azure Cosmos DB for free without an Azure subscription, free of charge and commitments.

Par ailleurs :In addition:

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 graphiques, vous devez avoir préalablement créé un compte de base de données (Graphique) Gremlin 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. 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, 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-python-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. Tous les extraits de code sont tirés du fichier connect.py dans le dossier C:\git-samples\azure-cosmos-db-graph-python-getting-started.The snippets are all taken from the connect.py file in the C:\git-samples\azure-cosmos-db-graph-python-getting-started\ folder. Sinon, vous pouvez passer à l’étape Mise à jour de votre chaîne de connexion.Otherwise, you can skip ahead to Update your connection string.

  • La console Gremlin client est initialisée à la ligne 104 de connect.py :The Gremlin client is initialized in line 104 in connect.py:

    ...
    client = client.Client('wss://<YOUR_ENDPOINT>.gremlin.cosmosdb.azure.com:443/','g', 
        username="/dbs/<YOUR_DATABASE>/colls/<YOUR_COLLECTION_OR_GRAPH>", 
        password="<YOUR_PASSWORD>")
    ...
    
  • Une série d’étapes Gremlin est déclarée au début du fichier connect.py.A series of Gremlin steps are declared at the beginning of the connect.py file. Elles sont ensuite exécutées à l’aide de la méthode client.submitAsync() :They are then executed using the client.submitAsync() method:

    client.submitAsync(_gremlin_cleanup_graph)
    

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 le portail Azure, cliquez sur Clés.In the Azure portal, click 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 connect.py et, sur la ligne 104, collez la valeur de l’URI sur <YOUR_ENDPOINT>, ici :Open the connect.py file and in line 104 paste the URI value over <YOUR_ENDPOINT> in here:

    client = client.Client('wss://<YOUR_ENDPOINT>.gremlin.cosmosdb.azure.com:443/','g', 
        username="/dbs/<YOUR_DATABASE>/colls/<YOUR_COLLECTION_OR_GRAPH>", 
        password="<YOUR_PASSWORD>")
    

    La portion d’URI de l’objet client doit être similaire au code suivant :The URI portion of the client object should now look similar to this code:

    client = client.Client('wss://test.gremlin.cosmosdb.azure.com:443/','g', 
        username="/dbs/<YOUR_DATABASE>/colls/<YOUR_COLLECTION_OR_GRAPH>", 
        password="<YOUR_PASSWORD>")
    
  3. Modifiez le second paramètre de l’objet client afin de remplacer les chaînes <YOUR_DATABASE> et <YOUR_COLLECTION_OR_GRAPH>.Change the second parameter of the client object to replace the <YOUR_DATABASE> and <YOUR_COLLECTION_OR_GRAPH> strings. Si vous avez utilisé les valeurs suggérées, le paramètre doit ressembler au code suivant :If you used the suggested values, the parameter should look like this code:

    username="/dbs/sample-database/colls/sample-graph"

    L’ensemble de l’objet client doit désormais ressembler à ce code :The entire client object should now look like this code:

    client = client.Client('wss://test.gremlin.cosmosdb.azure.com:443/','g', 
        username="/dbs/sample-database/colls/sample-graph", 
        password="<YOUR_PASSWORD>")
    
  4. Dans le portail Azure, utilisez le bouton de copie pour copier la CLÉ PRIMAIRE, puis collez-la sur <YOUR_PASSWORD> dans le paramètre password=<YOUR_PASSWORD>.In the Azure portal, use the copy button to copy the PRIMARY KEY and paste it over <YOUR_PASSWORD> in the password=<YOUR_PASSWORD> parameter.

    L’ensemble de définition de l’objet client doit désormais ressembler à ce code :The entire client object definition should now look like this code:

    client = client.Client('wss://test.gremlin.cosmosdb.azure.com:443/','g', 
        username="/dbs/sample-database/colls/sample-graph", 
        password="asdb13Fadsf14FASc22Ggkr662ifxz2Mg==")
    
  5. Enregistrez le fichier connect.py.Save the connect.py file.

Exécution de l’application consoleRun the console app

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

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

    pip install -r requirements.txt
    
  3. Dans la fenêtre de terminal git, utilisez la commande suivante pour démarrer l’application Python.In the git terminal window, use the following command to start the Python application.

    python connect.py
    

    La fenêtre de terminal affiche les vertex et les bords ajoutés au graphique.The terminal window displays the vertices and edges 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é, appuyez sur Entrée, puis rebasculez vers le portail Azure dans votre navigateur Internet.Once the program stops, press Enter, then switch back to the Azure portal in your internet browser.

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

Après insertion des sommets et arêtes, vous pouvez revenir à l’Explorateur de données et voir les sommets ajoutés au graphe. Vous pouvez également ajouter des points de données supplémentaires.After the vertices and edges are inserted, you can now go back to Data Explorer and see the vertices added to the graph, and add additional data points.

  1. Cliquez sur Explorateur de données, développez sample-graph, cliquez sur Graphique, puis cliquez sur Appliquer un filtre.Click Data Explorer, expand sample-graph, click Graph, and then click Apply Filter.

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

  2. Dans la liste Résultats, vous voyez que trois nouveaux utilisateurs ont été ajoutés au graphe.In the Results list, notice three new users are added to the graph. Vous pouvez glisser-déplacez les vertex, effectuer un zoom avant et arrière à l’aide de la roulette de la souris et augmenter la taille du graphique 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 vertex dans le graphique 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. Cliquez sur le bouton New Vertex (Nouveau vertex) pour ajouter des données à votre graphique.Click the New Vertex button to add data to your graph.

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

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

  5. Cliquez sur Ajouter une propriété pour ajouter chacune des propriétés suivantes.Click 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 graphique.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
    pkpk /pk/pk
    idid ashleyashley Identificateur unique du vertex.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 guide de démarrage rapide, nous créons une collection non partitionnée.In this quickstart 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 vertex.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. Cliquez sur OK.Click 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. Cliquez de nouveau sur New Vertex (Nouveau vertex) et ajoutez un nouvel utilisateur supplémentaire.Click New Vertex again and add an additional new user.

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

  9. Cliquez sur Ajouter une propriété pour ajouter chacune des propriétés suivantes :Click Add property to add each of the following properties:

    keykey valuevalue NotesNotes
    pkpk /pk/pk
    idid rakeshrakesh Identificateur unique du vertex.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. Cliquez sur OK.Click OK.

  11. Cliquez sur le bouton Appliquer un filtre avec le filtre par défaut g.V() pour afficher toutes les valeurs dans le graphique.Click 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 vertex dans un graphique.By default, Data Explorer uses g.V() to retrieve all vertices in a graph. Vous pouvez choisir une autre requête de graphique comme g.V().count() pour retourner le nombre total de vertex dans le graphique 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 cliquez sur 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 click Apply Filter to display all the results again.

  12. À présent, nous pouvons connecter rakesh et ashley.Now we can connect rakesh and ashley. Vérifiez que ashley est bien sélectionné dans la liste Résultats, puis cliquez sur le bouton de modification en regard de Cibles dans la partie inférieure droite de l’écran.Ensure ashley is selected in the Results list, then click the edit button next to Targets on lower right side. Vous devrez peut-être élargir la fenêtre pour visualiser la zone Propriétés.You may need to widen your window to see the Properties area.

    Modifier la cible d’un vertex dans un graphique

  13. Dans la zone Cible, tapez rakesh. Dans la zone Edge label (Étiquette de relation), tapez knows, puis cochez la case.In the Target box type rakesh, and in the Edge label box type knows, and then click the check.

    Ajouter une connexion entre ashley et rakesh dans l’Explorateur de données

  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 vertex connectés dans l’Explorateur de données

    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 vertex à votre graphique, modifier les vertex existants ou modifier 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.

Supprimer des 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.