Démarrage rapide : Créer une application Node.js à l’aide du compte de l’API Gremlin Azure Cosmos DBQuickstart: Build a Node.js application by using Azure Cosmos DB Gremlin API account

Azure Cosmos DB est le service de base de données multi-modèle distribué mondialement de Microsoft.Azure Cosmos DB is the globally distributed multimodel database service from Microsoft. 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 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 using the Azure portal. Par la suite, vous allez créer et exécuter une application console en utilisant le pilote Gremlin Node.js open-source.You then build and run a console app by using the open-source Gremlin Node.js driver.

PrérequisPrerequisites

Avant de pouvoir exécuter cet exemple, vous devez posséder les composants requis suivants :Before you can run this sample, you must have the following prerequisites:

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-nodejs-getting-started.git
    
  4. Ouvrez le fichier de solution dans Visual Studio.Open the solution file in Visual Studio.

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 app.js.The following snippets are all taken from the app.js file.

  • Le client Gremlin est créé.The Gremlin client is created.

    const authenticator = new Gremlin.driver.auth.PlainTextSaslAuthenticator(
        `/dbs/${config.database}/colls/${config.collection}`, 
        config.primaryKey
    )
    
    
    const client = new Gremlin.driver.Client(
        config.endpoint, 
        { 
            authenticator,
            traversalsource : "g",
            rejectUnauthorized : true,
            mimeType : "application/vnd.gremlin-v2.0+json"
        }
    );
    
    

    Les configurations sont toutes dans config.js, que nous allons modifier dans la section suivante.The configurations are all in config.js, which we edit in the following section.

  • Plusieurs fonctions sont définies pour exécuter différentes opérations Gremlin.A series of functions are defined to execute different Gremlin operations. Voici l’une d’entre elles :This is one of them:

    function addVertex1()
    {
        console.log('Running Add Vertex1'); 
        return client.submit("g.addV(label).property('id', id).property('firstName', firstName).property('age', age).property('userid', userid).property('pk', 'pk')", {
                label:"person",
                id:"thomas",
                firstName:"Thomas",
                age:44, userid: 1
            }).then(function (result) {
                    console.log("Result: %s\n", JSON.stringify(result));
            });
    }
    
  • Chaque fonction exécute une méthode client.execute avec un paramètre de chaîne de requête Gremlin.Each function executes a client.execute method with a Gremlin query string parameter. Voici un exemple d’exécution de g.V().count() :Here is an example of how g.V().count() is executed:

    function countVertices()
    {
        console.log('Running Count');
        return client.submit("g.V().count()", { }).then(function (result) {
            console.log("Result: %s\n", JSON.stringify(result));
        });
    }
    
  • À la fin du fichier, toutes les méthodes sont appelées.At the end of the file, all methods are then invoked. Le code suivant va les exécuter les unes après les autres :This will execute them one after the other:

    client.open()
    .then(dropGraph)
    .then(addVertex1)
    .then(addVertex2)
    .then(addEdge)
    .then(countVertices)
    .catch((err) => {
        console.error("Error running query...");
        console.error(err)
    }).then((res) => {
        client.close();
        finish();
    }).catch((err) => 
        console.error("Fatal error:", err)
    );
    

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

  1. Ouvrez le fichier config.js.Open the config.js file.

  2. Dans le fichier config.js, renseignez la clé config.endpoint avec la valeur URI Gremlin dans la page Vue d’ensemble du portail Azure.In config.js, fill in the config.endpoint key with the Gremlin URI value from the Overview page of the Azure portal.

    config.endpoint = "https://<your_Gremlin_account_name>.gremlin.cosmosdb.azure.com:443/";

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

  3. Dans le fichier config.js, renseignez la valeur config.primaryKey avec la valeur de la Clé primaire à partir de la page Clés du portail Azure.In config.js, fill in the config.primaryKey value with the Primary Key value from the Keys page of the Azure portal.

    config.primaryKey = "PRIMARYKEY";

    Panneau « Clés » du portail Azure

  4. Entrez le nom de la base de données et le nom du graphique (conteneur) pour la valeur de config.database et de config.collection.Enter the database name, and graph (container) name for the value of config.database and config.collection.

Voici un exemple de ce à quoi votre fichier config.js terminé doit ressembler :Here's an example of what your completed config.js file should look like:

var config = {}

// Note that this must not have HTTPS or the port number
config.endpoint = "https://testgraphacct.gremlin.cosmosdb.azure.com:443/"; 
config.primaryKey = "Pams6e7LEUS7LJ2Qk0fjZf3eGo65JdMWHmyn65i52w8ozPX2oxY3iP0yu05t9v1WymAHNcMwPIqNAEv3XDFsEg==";
config.database = "graphdb"
config.collection = "Persons"

module.exports = config;

Exécution de l’application consoleRun the console app

  1. Ouvrez une fenêtre de terminal et remplacez l’élément par le répertoire d’installation pour le fichier package.json inclus dans le projet (via la commande cd).Open a terminal window and change (via cd command) to the installation directory for the package.json file that's included in the project.

  2. Exécutez npm install pour installer les modules npm requis, y compris gremlin.Run npm install to install the required npm modules, including gremlin.

  3. Exécutez node app.js sur un terminal pour démarrer votre application Node.Run node app.js in a terminal to start your node application.

Navigation avec l’Explorateur de donnéesBrowse with Data Explorer

Vous pouvez maintenant revenir à l’Explorateur de données, dans le portail Azure, pour afficher, modifier, interroger et manipuler vos nouvelles données graphiques.You can now go back to Data Explorer in the Azure portal to view, query, modify, and work with your new graph data.

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 la base de données, suivie du conteneur, puis sélectionnez Graphe.Expand the database, followed by the container, and then select Graph.

Les données générées par l’exemple d’application s’affichent dans le volet suivant de l’onglet Graphe lorsque vous sélectionnez Appliquer un filtre.The data generated by the sample app is displayed in the next pane within the Graph tab when you select Apply Filter.

Essayez de renseigner g.V() avec .has('firstName', 'Thomas') pour tester le filtre.Try completing g.V() with .has('firstName', 'Thomas') to test the filter. Notez que la valeur respecte la casse.Note that the value is case sensitive.

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.

Nettoyage des ressourcesClean up your 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 cet article, 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.In this article, you learned how to create an Azure Cosmos DB account, create a graph by using 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 by using Gremlin.