Inicio rápido: Creación de una base de datos de grafos en Azure Cosmos DB mediante PHP y Azure PortalQuickstart: Create a graph database in Azure Cosmos DB using PHP and the Azure portal

En esta guía de inicio rápido se muestra cómo se usa PHP y Gremlin API de Azure Cosmos DB para crear una aplicación de consola mediante la clonación de un ejemplo de GitHub.This quickstart shows how to use PHP and the Azure Cosmos DB Gremlin API to build a console app by cloning an example from GitHub. Esta guía de inicio rápido también le guía a través de la creación de una cuenta de Azure Cosmos DB a través de Azure Portal en la web.This quickstart also walks you through the creation of an Azure Cosmos DB account by using the web-based Azure portal.

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, tablas, 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, 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.

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. También puede probar gratis Azure Cosmos DB sin suscripción de Azure, sin cargos y sin compromiso.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. Alternatively, you can Try Azure Cosmos DB for free without an Azure subscription, free of charge and commitments.

Además:In addition:

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-php-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. Todos los fragmentos de código se toman del archivo connect.php en la carpeta C:\git-samples\azure-cosmos-db-graph-php-getting-started.The snippets are all taken from the connect.php file in the C:\git-samples\azure-cosmos-db-graph-php-getting-started\ folder. 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.

  • El Gremlin connection se inicializa al principio del archivo connect.php utilizando el objeto $db.The Gremlin connection is initialized in the beginning of the connect.php file using the $db object.

    $db = new Connection([
        'host' => '<your_server_address>.graphs.azure.com',
        'username' => '/dbs/<db>/colls/<coll>',
        'password' => 'your_primary_key'
        ,'port' => '443'
    
        // Required parameter
        ,'ssl' => TRUE
    ]);
    
  • Se ejecuta una serie de pasos de Gremlin mediante el método $db->send($query);.A series of Gremlin steps are executed using the $db->send($query); method.

    $query = "g.V().drop()";
    ...
    $result = $db->send($query);
    $errors = array_filter($result);
    }
    

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, haga clic en Claves.In the Azure portal, click 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 connect.php y, en línea 8, pegue el valor del URI sobre your_server_address.Open the connect.php file and in line 8 paste the URI value over your_server_address.

    La inicialización del objeto Connection ahora debería ser similar al siguiente código:The connection object initialization should now look similar to the following code:

    $db = new Connection([
        'host' => 'testgraphacct.gremlin.cosmosdb.azure.com',
        'username' => '/dbs/<db>/colls/<coll>',
        'password' => 'your_primary_key'
        ,'port' => '443'
    
        // Required parameter
        ,'ssl' => TRUE
    ]);
    
  3. Cambie el parámetro username del objeto Connection por el nombre de base de datos y el grafo+.Change username parameter in the Connection object with your database and graph name. Si usó los valores recomendados de sample-database y sample-graph, debería ser similar al siguiente código:If you used the recommended values of sample-database and sample-graph, it should look like the following code:

    'username' => '/dbs/sample-database/colls/sample-graph'

    Todo el objeto Connection debería ser similar el siguiente fragmento de código en este momento:The entire Connection object should look like the following code snippet at this time:

    $db = new Connection([
        'host' => 'testgraphacct.gremlin.cosmosdb.azure.com',
        'username' => '/dbs/sample-database/colls/sample-graph',
        'password' => 'your_primary_key',
        'port' => '443'
    
        // Required parameter
        ,'ssl' => TRUE
    ]);
    
  4. En Azure Portal, use el botón Copiar para copiar la clave principal y péguela sobre your_primary_key en el parámetro password.In the Azure portal, use the copy button to copy the PRIMARY KEY and paste it over your_primary_key in the password parameter.

    La inicialización del objeto Connection ahora debería ser similar al siguiente código:The Connection object initialization should now look like the following code:

    $db = new Connection([
        'host' => 'testgraphacct.graphs.azure.com',
        'username' => '/dbs/sample-database/colls/sample-graph',
        'password' => '2Ggkr662ifxz2Mg==',
        'port' => '443'
    
        // Required parameter
        ,'ssl' => TRUE
    ]);
    
  5. Guarde el archivo connect.php.Save the connect.php 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-php-getting-started.In the git terminal window, cd to the azure-cosmos-db-graph-php-getting-started folder.

    cd "C:\git-samples\azure-cosmos-db-graph-php-getting-started"
    
  2. En la ventana del terminal de Git, use el comando siguiente para instalar los as dependencias PHP necesarias.In the git terminal window, use the following command to install the required PHP dependencies.

    composer install
    
  3. En la ventana de terminal de Git, use el siguiente comando para iniciar la aplicación de PHP.In the git terminal window, use the following command to start the PHP application.

    php connect.php
    

    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, presione ENTRAR y, después, vuelva a cambiar a Azure Portal en el Explorador de Internet.Once the program stops, press 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. Haga clic en el Explorador de datos, expanda sample-graph, haga clic en Gráfico y luego haga clic en Aplicar filtro.Click Data Explorer, expand sample-graph, click Graph, and then click 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 se ha conectado a robin.Select ben and notice that they're 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. Haga clic en el botón Nuevo vértice para agregar datos al grafo.Click the New Vertex button to add data to your graph.

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

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

  5. Haga clic en Agregar propiedad para agregar cada una de las siguientes propiedades.Click 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.

    ClaveKey ValorValue 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.
    sexogender mujerfemale
    tecnologíatech 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. Haga clic en OK.Click 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. Haga clic en Nuevo vértice de nuevo y agregue otro usuario.Click New Vertex again and add an additional new user.

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

  9. Haga clic en Agregar propiedad para agregar cada una de las siguientes propiedades:Click Add property to add each of the following properties:

    ClaveKey ValorValue 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.
    sexogender hombremale
    centro educativoschool MITMIT
  10. Haga clic en OK.Click OK.

  11. Haga clic en el botón Aplicar filtro con el filtro g.V() predeterminado para mostrar todos los valores en el gráfico.Click 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 haga clic en Aplicar filtro para volver a mostrar todos los resultados.If you changed the filter, change the filter back to g.V() and click 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 Resultados y, a continuación, haga clic en el botón para editar junto a Destinos en la parte inferior derecha.Ensure ashley is selected in the Results list, then click the edit button next to Targets on lower right side. Puede que tenga que ampliar la ventana para ver el área Propiedades.You may need to widen your window to see the Properties area.

    Cambio del destino de un vértice en un grafo

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

    Adicion de una conexión entre ashley y rakesh en el Explorador de datos

  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

    Esto completa la parte de la creación de recursos de esta guía de inicio rápido.That completes the resource creation part of this quickstart. 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.