Inicio rápido: Compilación de una aplicación .NET Framework o Core mediante la cuenta de Gremlin API de Azure Cosmos DBQuickstart: Build a .NET Framework or Core application using the Azure Cosmos DB Gremlin API account

Azure Cosmos DB es un servicio de base de datos con varios modelos y de distribución global de Microsoft.Azure Cosmos DB is Microsoft's globally distributed multi-model database service. 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 (contenedor) de Azure Cosmos DB mediante Azure Portal.This quickstart demonstrates how to create an Azure Cosmos DB Gremlin API account, database, and graph (container) using the Azure portal. Después, compile y ejecute una aplicación de consola compilada con el controlador Gremlin.Net de código abierto.You then build and run a console app built using the open-source driver Gremlin.Net.

Requisitos previosPrerequisites

Si aún no tiene instalado Visual Studio 2019, puede descargar y usar la versión gratuita de Visual Studio 2019 Community.If you don't already have Visual Studio 2019 installed, you can download and use the free Visual Studio 2019 Community Edition. Asegúrese de que habilita Desarrollo de Azure durante la instalación de Visual Studio.Make sure that you enable Azure development during the Visual Studio setup.

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-gremlindotnet-getting-started.git
    
  4. A continuación, abra Visual Studio y el archivo de solución.Then open Visual Studio and open the solution file.

  5. Restaure los paquetes de NuGet en el proyecto.Restore the NuGet packages in the project. Debe incluir el controlador Gremlin.Net, así como el paquete Newtonsoft.Json.This should include the Gremlin.Net driver, as well as the Newtonsoft.Json package.

  6. También puede instalar manualmente el controlador Gremlin.Net mediante el administrador de paquetes NuGet o la utilidad de línea de comandos de 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
    

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

  • Establezca los parámetros de conexión en función de la cuenta creada anteriormente (línea 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";
    
  • Se muestran los comandos de Gremlin que se van a ejecutar en un diccionario (línea 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()" },
    };
    
  • Cree un objeto de conexión GremlinServer con los parámetros proporcionados anteriormente (línea 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);
    
  • Cree un nuevo objeto GremlinClient (línea 56):Create a new GremlinClient object (Line 56):

    var gremlinClient = new GremlinClient(gremlinServer, new GraphSON2Reader(), new GraphSON2Writer(), GremlinClient.GraphSON2MimeType);
    
  • Ejecute cada consulta de Gremlin con el objeto GremlinClient con una tarea asincrónica (línea 63).Execute each Gremlin query using the GremlinClient object with an async task (Line 63). Leerá las consultas de Gremlin desde el diccionario definido anteriormente (línea 26):This will read the Gremlin queries from the dictionary defined above (Line 26):

    var results = await gremlinClient.SubmitAsync<dynamic>(query.Value);
    
  • Recupere el resultado y lea los valores, que tienen un formato de diccionario, usando la clase 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));
    }
    

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

Ahora vuelva a Azure Portal para obtener la información de la cadena de conexión y cópiela en la aplicación.Now go back to the Azure portal to get your connection string information and copy it into the app.

  1. En Azure Portal, vaya a la cuenta de base de datos de grafos.From the Azure portal, navigate to your graph database account. En la pestaña Información general, puede ver dos puntos de conexión.In the Overview tab, you can see two endpoints-

    URI del SDK de .NET: este valor se usa al conectarse a la cuenta de grafos mediante la biblioteca de Microsoft.Azure.Graphs..NET SDK URI - This value is used when you connect to the graph account by using Microsoft.Azure.Graphs library.

    Punto de conexión de Gremlin: este valor se usa cuando se conecta a la cuenta de grafos mediante la biblioteca Gremlin.Net.Gremlin Endpoint - This value is used when you connect to the graph account by using Gremlin.Net library.

    Copiar el punto de conexión

    Para ejecutar este ejemplo, copie el valor de Punto de conexión de Gremlin y elimine el número de puerto del final con lo que el identificador URI se convertirá en https://<your cosmos db account name>.gremlin.cosmosdb.azure.com.To 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. En Program.cs, pegue el valor por encima de your-endpoint en la variable hostname en la línea 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";

    El valor del punto de conexión debe tener el siguiente aspecto:The endpoint value should now look like this:

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

  3. A continuación, vaya a la pestaña Claves y copie el valor PRIMARY KEY del portal y péguelo en la variable authkey, reemplazando el marcador de posición "your-authentication-key" de la línea 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. Con la información de la base de datos que se ha creado anteriormente, pegue el nombre de la base de datos dentro de la variable database en la línea 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 forma similar, con la información del contenedor que se ha creado anteriormente, pegue la colección (que también incluye el nombre del grafo) en la variable collection de la línea 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. Guarde el archivo Program.cs.Save the Program.cs file.

Ya ha actualizado la aplicación con toda la información que necesita para comunicarse con Azure Cosmos DB.You've now updated your app with all the info it needs to communicate with Azure Cosmos DB.

Ejecutar la aplicación de consolaRun the console app

Haga clic en CTRL + F5 para ejecutar la aplicación.Click CTRL + F5 to run the application. La aplicación imprimirá los resultados de la consola y los comandos de consulta de Gremlin.The application will print both the Gremlin query commands and results in the console.

En la ventana de la consola se muestran los vértices y los bordes que se agregan al grafo.The console window displays the vertexes and edges being added to the graph. Cuando se complete el script, presione ENTRAR para cerrar la ventana de la consola.When the script completes, press ENTER to close the console window.

Examinar mediante el Explorador de datosBrowse using the Data Explorer

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

  1. 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 los nodos del contenedor y de la base de datos y, a continuación, haga clic en Grafo.Expand the database and container nodes, and then click Graph.

  2. Haga clic en el botón Aplicar filtro para usar la consulta predeterminada para visualizar todos los vértices del grafo.Click the Apply Filter button to use the default query to view all the vertices in the graph. Los datos generados por la aplicación de ejemplo se muestran en el panel grafos.The data generated by the sample app is displayed in the Graphs pane.

    Puede acercar o alejar el grafo, expandir el espacio de visualización del grafo, agregar vértices adicionales y mover los vértices sobre la superficie de visualización.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.

    Visualización del grafo en el Explorador de datos en Azure Portal

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.

Limpieza de recursosClean up 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 esta guía de inicio rápido, ha obtenido información sobre cómo crear una cuenta de Azure Cosmos DB, crear un grafo mediante el Explorador de datos y ejecutar una aplicación.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. Ahora puede crear consultas más complejas e implementar con Gremlin una lógica eficaz de recorrido del grafo.You can now build more complex queries and implement powerful graph traversal logic using Gremlin.