Inicio rápido: Compilación de una aplicación de Node.js mediante una cuenta de Gremlin API con Azure Cosmos DBQuickstart: Build a Node.js application by using Azure Cosmos DB Gremlin API account

Azure Cosmos DB es el servicio de base de datos con varios modelos y de distribución global de Microsoft.Azure Cosmos DB is the globally distributed multimodel database service from Microsoft. Puede crear rápidamente bases de datos de documentos, clave-valor y grafos, y realizar consultas en ellas. Todas las bases de datos se beneficiarán de las funcionalidades de distribución global y escala horizontal en 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.

En este inicio rápido se muestra cómo crear una cuenta de Gremlin API, una base de datos y un grafo de Azure Cosmos DB mediante Azure Portal.This quickstart demonstrates how to create an Azure Cosmos DB Gremlin API account, database, and graph using the Azure portal. Después, compilará y ejecutará una aplicación de consola con el controlador Node.js de Gremlin de código abierto.You then build and run a console app by using the open-source Gremlin Node.js driver.

Requisitos previosPrerequisites

Antes de ejecutar este ejemplo, debe cumplir los siguientes requisitos previos:Before you can run this sample, you must have the following prerequisites:

Si no tiene una suscripción a Azure, cree una cuenta gratuita antes de empezar.If you don't have an Azure subscription, create a free account before you begin.

Creación de una cuenta de base de datosCreate a database account

  1. En una nueva ventana del explorador, inicie sesión en Azure Portal.In a new browser window, sign in to the Azure portal.

  2. Haga clic en Crear un recurso > Bases de datos > Azure Cosmos DB.Click Create a resource > Databases > Azure Cosmos DB.

    Panel "Bases de datos" de Azure Portal

  3. En la página Crear una cuenta de Azure Cosmos DB, especifique la configuración de la nueva cuenta de Azure Cosmos DB.In the Create Azure Cosmos DB Account page, enter the settings for the new Azure Cosmos DB account.

    ConfiguraciónSetting ValorValue DESCRIPCIÓNDescription
    SubscriptionSubscription Su suscripciónYour subscription Seleccione la suscripción de Azure que quiere usar para esta cuenta de Azure Cosmos DB.Select the Azure subscription that you want to use for this Azure Cosmos DB account.
    Grupo de recursosResource Group Crear nuevoCreate new

    A continuación, escriba el mismo nombre único que se proporcionó en el identificadorThen enter the same unique name as provided in ID
    Seleccione Crear nuevo.Select Create new. A continuación, escriba un nombre nuevo de grupo de recursos para la cuenta.Then enter a new resource-group name for your account. Para simplificar, utilice el mismo nombre del identificador.For simplicity, use the same name as your ID.
    Nombre de cuentaAccount Name Escriba un nombre único.Enter a unique name Escriba un nombre único para identificar la cuenta de Azure Cosmos DB.Enter a unique name to identify your Azure Cosmos DB account. Dado que documents.azure.com se anexa al identificador que se proporciona para crear el identificador URI, debe usar un identificador único.Because documents.azure.com is appended to the ID that you provide to create your URI, use a unique ID.

    El identificador solo debe contener letras minúsculas, números y el carácter de guion (-).The ID can use only lowercase letters, numbers, and the hyphen (-) character. Debe tener una longitud de entre 3 y 31 caracteres.It must be between 3 and 31 characters in length.
    APIAPI Gremlin (graph)Gremlin (graph) La API determina el tipo de cuenta que se va a crear.The API determines the type of account to create. Azure Cosmos DB proporciona cinco API: Core(SQL) para bases de datos de documentos, Gremlin para bases de datos de grafos, MongoDB para bases de datos de documentos, Azure Table y Cassandra.Azure Cosmos DB provides five APIs: Core(SQL) for document databases, Gremlin for graph databases, MongoDB for document databases, Azure Table, and Cassandra. Actualmente, debe crear una cuenta independiente para cada API.Currently, you must create a separate account for each API.

    Seleccione Gremlin (grafo) , ya que en esta guía de inicio rápido va a crear una tabla que funciona con la API de Gremlin.Select Gremlin (graph) because in this quickstart you are creating a table that works with the Gremlin API.

    Más información sobre Graph APILearn more about the Graph API.
    LocationLocation Seleccionar la región más cercana a los usuariosSelect the region closest to your users Seleccione una ubicación geográfica para hospedar la cuenta de Azure Cosmos DB.Select a geographic location to host your Azure Cosmos DB account. Use la ubicación más cercana a los usuarios para proporcionarles el acceso más rápido a los datos.Use the location that's closest to your users to give them the fastest access to the data.

    Seleccione Revisar y crear.Select Review+Create. Puede omitir las secciones Red y Etiquetas.You can skip the Network and Tags section.

    Sección de la nueva cuenta de Azure Cosmos DB

  4. La cuenta tarda unos minutos en crearse.The account creation takes a few minutes. Espere a que el portal muestre la página ¡Enhorabuena! Se ha creado su cuenta de Azure Cosmos DB.Wait for the portal to display the Congratulations! Your Azure Cosmos DB account was created page.

    El panel de las notificaciones de Azure Portal

Agregar un grafoAdd a graph

Ahora puede usar la herramienta Explorador de datos en Azure Portal para crear una base de datos de grafos.You can now use the Data Explorer tool in the Azure portal to create a graph database.

  1. Seleccione Explorador de datos > New Graph (Nuevo grafo).Select Data Explorer > New Graph.

    El área Agregar gráfico se muestra en el extremo derecho, pero es posible que haya que desplazarse hacia la derecha para verlo.The Add Graph area is displayed on the far right, you may need to scroll right to see it.

    Explorador de datos en Azure Portal, página Agregar gráfico

  2. En la página Agregar gráfico, especifique la configuración del nuevo gráfico.In the Add graph page, enter the settings for the new graph.

    ConfiguraciónSetting Valor sugeridoSuggested value DESCRIPCIÓNDescription
    Identificador de base de datosDatabase ID sample-databasesample-database Escriba sample-database como nombre de la nueva base de datos.Enter sample-database as the name for the new database. Los nombres de bases de datos deben tener entre 1 y 255 caracteres y no pueden contener / \ # ? o un espacio al final.Database names must be between 1 and 255 characters, and cannot contain / \ # ? or a trailing space.
    ThroughputThroughput 400 RU400 RUs Cambie el rendimiento a 400 unidades de solicitud por segundo (RU/s).Change the throughput to 400 request units per second (RU/s). Si quiere reducir la latencia, puede escalar verticalmente el rendimiento más adelante.If you want to reduce latency, you can scale up the throughput later.
    Identificador de grafoGraph ID sample-graphsample-graph Escriba sample-graph como nombre de la nueva colección.Enter sample-graph as the name for your new collection. Los nombres de grafo tienen los mismos requisitos de caracteres que los identificadores de base de datos.Graph names have the same character requirements as database IDs.
    Partition KeyPartition Key /pk/pk Todas las cuentas de Cosmos DB necesitan una clave de partición para escalar horizontalmente.All Cosmos DB accounts need a partition key to horizontally scale. Aprenda a seleccionar una clave de partición adecuada en el artículo de creación de particiones de datos de Graph.Learn how to select an appropriate partition key in the Graph Data Partitioning article.
  3. Una vez que haya rellenado el formulario, seleccione Aceptar.Once the form is filled out, select OK.

Clonación de la aplicación de ejemploClone the sample application

Ahora, vamos a clonar una aplicación de Gremlin API desde GitHub, establecer la cadena de conexión y ejecutarla.Now let's clone a Gremlin API app from GitHub, set the connection string, and run it. Verá lo fácil que es trabajar con datos mediante programación.You'll see how easy it is to work with data programmatically.

  1. Abra un símbolo del sistema, cree una carpeta nueva denominada ejemplos de GIT y, después, cierre el símbolo del sistema.Open a command prompt, create a new folder named git-samples, then close the command prompt.

    md "C:\git-samples"
    
  2. Abra una ventana de terminal de Git, como git bash y utilice el comando cd para cambiar a la nueva carpeta para instalar la aplicación de ejemplo.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. Ejecute el comando siguiente para clonar el repositorio de ejemplo.Run the following command to clone the sample repository. Este comando crea una copia de la aplicación de ejemplo en el equipo.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. Abra el archivo de solución en Visual Studio.Open the solution file in Visual Studio.

Revisión del códigoReview the code

Este paso es opcional.This step is optional. Si está interesado en aprender cómo se crean los recursos de base de datos en el código, puede revisar los siguientes fragmentos de código.If you're interested in learning how the database resources are created in the code, you can review the following snippets. En caso contrario, puede ir directamente a Actualización de la cadena de conexión.Otherwise, you can skip ahead to Update your connection string.

Los fragmentos de código siguientes se han tomado del archivo app.js.The following snippets are all taken from the app.js file.

  • Se crea el cliente Gremlin.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"
        }
    );
    
    

    Las configuraciones están todas en config.js, que podemos editar en la sección siguiente.The configurations are all in config.js, which we edit in the following section.

  • Se definen una serie de funciones para ejecutar distintas operaciones de Gremlin.A series of functions are defined to execute different Gremlin operations. Este es una de ellas: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));
            });
    }
    
  • Cada función ejecuta un método client.execute con un parámetro de cadena de consulta de Gremlin.Each function executes a client.execute method with a Gremlin query string parameter. Este es un ejemplo de cómo se ejecuta 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));
        });
    }
    
  • Al final del archivo, todos los métodos se invocan.At the end of the file, all methods are then invoked. Se ejecutarán sucesivamente: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)
    );
    

Actualización de la cadena de conexiónUpdate your connection string

  1. Abra el archivo config.js.Open the config.js file.

  2. En config.js, rellene la clave config.endpoint con el valor de URI de Gremlin de la página Información general de Azure Portal.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/";

    Visualización y copia de una clave de acceso en Azure Portal, hoja Claves

  3. En config.js, rellene el valor de config.primaryKey con el valor de la Clave principal de la página Claves de Azure Portal.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";

    Hoja "Claves" de Azure Portal

  4. Escriba el nombre de la base de datos y el nombre del grafo (contenedor) para el valor de config.database y config.collection.Enter the database name, and graph (container) name for the value of config.database and config.collection.

Este es un ejemplo del aspecto que debería tener el archivo config.js completado: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;

Ejecutar la aplicación de consolaRun the console app

  1. Abra una ventana del terminal y, con el comando cd, cambie al directorio de instalación del archivo package.json incluido en el proyecto.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. Ejecute npm install para instalar los módulos npm necesarios, incluido gremlin.Run npm install to install the required npm modules, including gremlin.

  3. Ejecute node app.js en un terminal para iniciar la aplicación de nodo.Run node app.js in a terminal to start your node application.

Examinar con el Explorador de datosBrowse with Data Explorer

Ahora puede volver al Explorador de datos en Azure Portal para examinar, consultar, modificar y trabajar con los datos del nuevo grafo.You can now go back to Data Explorer in the Azure portal to view, query, modify, and work with your new graph data.

En el Explorador de datos, la nueva base de datos aparece en el panel Grafos.In Data Explorer, the new database appears in the Graphs pane. Expanda la base de datos, luego el contenedor y, finalmente, seleccione Grafo.Expand the database, followed by the container, and then select Graph.

Los datos generados por la aplicación de ejemplo se muestran en el panel siguiente dentro de la pestaña Grafo al seleccionar Aplicar filtro.The data generated by the sample app is displayed in the next pane within the Graph tab when you select Apply Filter.

Intente completar g.V() con .has('firstName', 'Thomas') para probar el filtro.Try completing g.V() with .has('firstName', 'Thomas') to test the filter. Tenga en cuenta que el valor distingue mayúsculas de minúsculas.Note that the value is case sensitive.

Revisión de los SLA en Azure PortalReview SLAs in the Azure portal

Azure Portal supervisa el rendimiento, capacidad de almacenamiento, disponibilidad, latencia y coherencia de su cuenta de Cosmos DB.The Azure portal monitors your Cosmos DB account throughput, storage, availability, latency, and consistency. Los gráficos de las métricas asociadas con un Acuerdo de Nivel de Servicio (SLA) de Azure Cosmos DB muestran el rendimiento real en comparación con el valor de este acuerdo.Charts for metrics associated with an Azure Cosmos DB Service Level Agreement (SLA) show the SLA value compared to actual performance. Este conjunto de métricas hace que la supervisión de los Acuerdos de Nivel de Servicio sea transparente.This suite of metrics makes monitoring your SLAs transparent.

Para revisar las métricas y los Acuerdos de Nivel de Servicio:To review metrics and SLAs:

  1. Seleccione Métricas en el menú de navegación de la cuenta de Cosmos DB.Select Metrics in your Cosmos DB account's navigation menu.

  2. Seleccione una pestaña como Latencia y seleccione un período de tiempo a la derecha.Select a tab such as Latency, and select a timeframe on the right. Compare las líneas Real y SLA de los gráficos.Compare the Actual and SLA lines on the charts.

    Conjunto de métricas de Azure Cosmos DB

  3. Revise las métricas de las otras pestañas.Review the metrics on the other tabs.

Limpiar los recursosClean up your resources

Cuando haya terminado tanto con la aplicación web como con la cuenta de Azure Cosmos DB, puede eliminar los recursos de Azure que creó para no tener más gastos.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. Para eliminar los recursos:To delete the resources:

  1. En Azure Portal, seleccione Grupos de recursos a la izquierda del todo.In the Azure portal, select Resource groups on the far left. Si el menú de la izquierda está contraído, seleccione el botón Expandir para expandirlo.If the left menu is collapsed, select Expand button to expand it.

  2. Seleccione el grupo de recursos que creó para este inicio rápido.Select the resource group you created for this quickstart.

    Selección del grupo de recursos que se eliminará

  3. En la nueva ventana, seleccione Eliminar grupo de recursos.In the new window, select Delete resource group.

    Eliminar el grupo de recursos

  4. En la ventana siguiente, escriba el nombre del grupo de recursos que desea eliminar y, después, seleccione Eliminar.In the next window, enter the name of the resource group to delete, and then select Delete.

Pasos siguientesNext steps

En este artículo, ha aprendido crear una cuenta de Azure Cosmos DB, crear un grafo mediante el Explorador de datos y ejecutar una aplicación.In this article, you learned how to create an Azure Cosmos DB account, create a graph by using Data Explorer, and run an app. Ahora puede usar Gremlin para implementar una lógica de recorrido del grafo eficaz y crear consultas más complejas.You can now build more complex queries and implement powerful graph traversal logic by using Gremlin.