Inicio rápido: Creación de una base de datos de grafos con el SDK de Java y la Table API de Azure Cosmos DBQuickstart: Build a graph database with the Java SDK and the Azure Cosmos DB Table API

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. Utilice Azure Cosmos DB para crear y consultar rápidamente las bases de datos de gráficos, tablas y documentos administradas.Using Azure Cosmos DB, you can quickly create and query managed document, table, and graph databases.

Este tutorial rápido crea una base de datos de gráficos simple mediante las herramientas de Azure Portal para Azure Cosmos DB.This quickstart creates a simple graph database using the Azure portal tools for Azure Cosmos DB. En esta guía de inicio rápido también se muestra cómo crear rápidamente una aplicación de consola Java con una base de datos de Gremlin API mediante el controlador Apache TinkerPop de OSS.This quickstart also shows you how to quickly create a Java console app using a Gremlin API database using the OSS Apache TinkerPop driver. Las instrucciones que se indican en este tutorial rápido se pueden seguir en cualquier sistema operativo que sea capaz de ejecutar Java.The instructions in this quickstart can be followed on any operating system that is capable of running Java. Con esta guía de inicio rápido se familiarizará con la creación y modificación de los gráficos en la interfaz de usuario o mediante programación, lo que prefiera.This quickstart familiarizes you with creating and modifying graphs in either the UI or programmatically, whichever is your preference.

Requisitos previosPrerequisites

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.

Además:In addition:

  • Kit de desarrollo de Java (JDK), versión 8Java Development Kit (JDK) version 8
    • Asegúrese de establecer la variable de entorno JAVA_HOME para que apunte a la carpeta donde está instalado el JDK.Be sure to set the JAVA_HOME environment variable to point to the folder where the JDK is installed.
  • Descargar e instalar un archivo binario de MavenDownload and install a Maven binary archive
    • En Ubuntu, puede ejecutar apt-get install maven para instalar Maven.On Ubuntu, you can run apt-get install maven to install Maven.
  • GitGit
    • En Ubuntu, puede ejecutar sudo apt-get install git para instalar Git.On Ubuntu, you can run sudo apt-get install git to install Git.

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

Para poder crear una base de datos de grafos, debe crear una cuenta de base de datos de Gremlin (Graph) con Azure Cosmos DB.Before you can create a graph database, you need to create a Gremlin (Graph) database account with Azure Cosmos DB.

  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 empezar a trabajar con el código.Now let's switch to working with code. Vamos a clonar una aplicación de Gremlin API desde GitHub, establecer la cadena de conexión y ejecutarla.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 una 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 a 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-java-getting-started.git
    

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 siguientes fragmentos de código se toman del archivo 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.

  • El elemento Client de Gremlin se inicializa a partir de la configuración del archivo 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();
    
  • Se ejecuta una serie de pasos de Gremlin mediante el método 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());
    }
    

Actualización de la información de conexiónUpdate your connection information

Ahora vuelva a Azure Portal para obtener la información de conexión y cópiela en la aplicación.Now go back to the Azure portal to get your connection information and copy it into the app. Esta configuración permitirá que la aplicación se comunique con la base de datos hospedada.These settings enable your app to communicate with your hosted database.

  1. En Azure Portal, seleccione Claves.In the Azure portal, select Keys.

    Copie la primera parte del valor URI.Copy the first portion of the URI value.

    Visualización y copia de una clave de acceso en Azure Portal, página Claves

  2. Abra el archivo src/remote.yaml y pegue el valor del identificador único sobre $name$ en 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 línea 1 de remote.yaml debe tener un aspecto similar aLine 1 of remote.yaml should now look similar to

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

  3. Cambio graphs a gremlin.cosmosdb en el valor endpoint.Change graphs to gremlin.cosmosdb in the endpoint value. (Si creó su cuenta de base de datos de grafos antes del 20 de diciembre de 2017, no realice cambios en el valor del punto de conexión y continúe al siguiente paso).(If you created your graph database account before December 20, 2017, make no changes to the endpoint value and continue to the next step.)

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

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

  4. En Azure Portal, use el botón Copiar para copiar la clave principal y péguela sobre $masterKey$ en password: $masterKey$.In the Azure portal, use the copy button to copy the PRIMARY KEY and paste it over $masterKey$ in password: $masterKey$.

    La línea 4 de remote.yaml debe tener ahora un aspecto similar aLine 4 of remote.yaml should now look similar to

    password: 2Ggkr662ifxz2Mg==

  5. Cambio de la línea 3 de remote.yaml deChange line 3 of remote.yaml from

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

    toto

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

    Si ha utilizado un nombre único para el gráfico o la base de datos de ejemplo, actualice los valores según corresponda.If you used a unique name for your sample database or graph, update the values as appropriate.

  6. Guarde el archivo remote.yaml.Save the remote.yaml file.

Ejecutar la aplicación de consolaRun the console app

  1. En la ventana del terminal de git, use cd para cambiar a la carpeta 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. En la ventana del terminal de GIT, use el comando siguiente para instalar los paquetes Java necesarios.In the git terminal window, use the following command to install the required Java packages.

    mvn package
    
  3. En la ventana de terminal de GIT, use el siguiente comando para iniciar la aplicación de Java.In the git terminal window, use the following command to start the Java application.

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

    En la ventana del terminal se muestran los vértices y los bordes que se agregan al grafo.The terminal window displays the vertices being added to the graph.

    Si se producen errores de tiempo de espera, compruebe que actualizó la información de conexión correctamente en Actualización de la información de conexión e intente ejecutar de nuevo el último comando.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.

    Una vez que el programa se detenga, seleccione ENTRAR y, después, vuelva a cambiar a Azure Portal en el explorador de Internet.Once the program stops, select Enter, then switch back to the Azure portal in your internet browser.

Revise y agregue datos de ejemploReview and add sample data

Ahora puede volver al Explorador de datos y ver los vértices que se agregan al grafo, y agregar puntos de datos adicionales.You can now go back to Data Explorer and see the vertices added to the graph, and add additional data points.

  1. Seleccione Explorador de datos, expanda sample-graph, seleccione Gráfico y, por último, seleccione Aplicar filtro.Select Data Explorer, expand sample-graph, select Graph, and then select Apply Filter.

    Creación de documentos en el Explorador de datos en Azure Portal

  2. En la lista Resultados, observe los nuevos usuarios agregados al grafo.In the Results list, notice the new users added to the graph. Seleccione ben y observe que el usuario se ha conectado a robin.Select ben and notice that the user is connected to robin. Puede mover los vértices arrastrando y colocando, acercarse y alejarse desplazando la rueda del mouse y ampliar el tamaño del gráfico con la flecha doble.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.

    Nuevos vértices en el grafo del Explorador de datos de Azure Portal

  3. Vamos a agregar algunos usuarios nuevos.Let's add a few new users. Seleccione Nuevo vértice para agregar datos al grafo.Select New Vertex to add data to your graph.

    Creación de documentos en el Explorador de datos en Azure Portal

  4. En el cuadro de etiqueta, escriba person.In the label box, enter person.

  5. Seleccione Agregar propiedad para agregar cada una de las siguientes propiedades.Select Add property to add each of the following properties. Tenga en cuenta que puede crear propiedades únicas para cada persona en el grafo.Notice that you can create unique properties for each person in your graph. Solo se requiere la clave de identificador.Only the id key is required.

    keykey valuevalue NotasNotes
    idid ashleyashley Identificador único del vértice.The unique identifier for the vertex. Si no se especifica un identificador, se genera uno automáticamente.If you don't specify an id, one is generated for you.
    gendergender mujerfemale
    técnicotech Javajava

    Nota

    En esta guía de inicio rápido se crea una colección sin particiones.In this quickstart you create a non-partitioned collection. Sin embargo, si crea una colección con particiones especificando una clave de partición durante la creación de la colección, debe incluir la clave de partición como una clave en cada nuevo vértice.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. Seleccione Aceptar.Select OK. Puede que tenga que expandir la pantalla para ver Aceptar en la parte inferior de la pantalla.You may need to expand your screen to see OK on the bottom of the screen.

  7. Seleccione Nuevo vértice de nuevo y agregue otro usuario.Select New Vertex again and add an additional new user.

  8. Escriba una etiqueta de persona.Enter a label of person.

  9. Seleccione Agregar propiedad para agregar cada una de las siguientes propiedades:Select Add property to add each of the following properties:

    keykey valuevalue NotasNotes
    idid rakeshrakesh Identificador único del vértice.The unique identifier for the vertex. Si no se especifica un identificador, se genera uno automáticamente.If you don't specify an id, one is generated for you.
    gendergender hombremale
    centro educativoschool MITMIT
  10. Seleccione Aceptar.Select OK.

  11. Seleccione el botón Aplicar filtro con el filtro g.V() predeterminado para mostrar todos los valores en el grafo.ClSelectck the Apply Filter button with the default g.V() filter to display all the values in the graph. Todos los usuarios se muestran ahora en la lista Resultados.All of the users now show in the Results list.

    Si agrega más datos, puede usar filtros para limitar los resultados.As you add more data, you can use filters to limit your results. De forma predeterminada, el Explorador de datos usa g.V() para recuperar todos los vértices en un gráfico.By default, Data Explorer uses g.V() to retrieve all vertices in a graph. Se puede cambiar a otra consulta de gráfico, como g.V().count(), para devolver un recuento de todos los vértices en el gráfico en formato 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 ha cambiado el filtro, vuelva a cambiar el filtro a g.V() y seleccione Aplicar filtro para volver a mostrar todos los resultados.If you changed the filter, change the filter back to g.V() and select Apply Filter to display all the results again.

  12. Ahora puede conectar a rakesh y ashley.Now you can connect rakesh, and ashley. Asegúrese de que ashley está seleccionado en la lista Results (Resultados) y seleccione Change the target of a vertex in a graph (Cambiar el destino de un vértice de un grafo) al lado de Targets (Destinos) en la parte inferior derecha.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. Para ver el botón, es posible que tenga que ensanchar la ventana.You may need to widen your window to see the button.

    Cambio del destino de un vértice en un grafo: Azure Cosmos DB

  13. En el cuadro Destino, escriba rakesh, en el cuadro Edge label (Etiqueta de borde), escriba sabe y, a continuación, seleccione la casilla.In the Target box enter rakesh, and in the Edge label box enter knows, and then select the check box.

    Adición de una conexión en el Explorador de datos: Azure Cosmos DB

  14. Ahora seleccione rakesh en la lista de resultados y compruebe que ashley y rakesh están conectados.Now select rakesh from the results list and see that ashley and rakesh are connected.

    Dos vértices conectados en el Explorador de datos: Azure Cosmos DB

    Esto completa la parte de la creación de recursos de este tutorial.That completes the resource creation part of this tutorial. Puede seguir agregando vértices en el grafo, modificar los vértices existentes o cambiar las consultas.You can continue to add vertexes to your graph, modify the existing vertexes, or change the queries. Ahora vamos a revisar las métricas que proporciona Azure Cosmos DB y, a continuación, limpiaremos los recursos.Now let's review the metrics Azure Cosmos DB provides, and then clean up the resources.

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.