Inicio rápido: Biblioteca cliente de Azure Cosmos DB for Apache Gremlin para Python

• Python
• Node.js
• C#

Importante

¿Busca una solución de base de datos para escenarios a gran escala con un contrato de nivel de servicio (SLA) de disponibilidad de 99,999%, escalabilidad automática instantánea y conmutación automática por error en varias regiones? Considere la posibilidad de usar Azure Cosmos DB para NoSQL.

¿Desea implementar un grafo de procesamiento analítico en línea (OLAP) o migrar una aplicación de Apache Gremlin existente? Considere el uso de Graph en Microsoft Fabric.

Introducción a la biblioteca cliente de Azure Cosmos DB para Apache Gremlin para Python para almacenar, administrar y consultar datos no estructurados. Siga los pasos de esta guía para crear una nueva cuenta, instalar una biblioteca cliente de Python, conectarse a la cuenta, realizar operaciones comunes y consultar los datos de ejemplo finales.

Código fuente de la biblioteca | Paquete (PyPi)

Requisitos previos

• Una suscripción de Azure

  • Si no tiene una suscripción a Azure, cree una cuenta gratuita antes de empezar.

• La versión más reciente de Azure CLI en Azure Cloud Shell.

  • Si prefiere ejecutar comandos de referencia de la CLI localmente, inicie sesión en la CLI de Azure mediante el az login comando .

• Python 3.12 o posterior

Instalación

Primero, configure la cuenta y el entorno de desarrollo para esta guía. En esta sección se explica el proceso de creación de una cuenta, la obtención de sus credenciales y la preparación del entorno de desarrollo.

Crear una cuenta

Empiece por crear una API para una cuenta de Apache Gremlin. Una vez creada la cuenta, cree la base de datos y los recursos del grafo.

Azure CLI

1. Si aún no tiene un grupo de recursos de destino, use el az group create comando para crear un nuevo grupo de recursos en la suscripción.

   az group create \
       --name "<resource-group-name>" \
       --location "<location>"
   

2. Use el az cosmosdb create comando para crear una nueva cuenta de Azure Cosmos DB para Apache Gremlin con la configuración predeterminada.

   az cosmosdb create \
       --resource-group "<resource-group-name>" \
       --name "<account-name>" \
       --locations "regionName=<location>" \
       --capabilities "EnableGremlin"
   

3. Cree una nueva base de datos con el nombre az cosmosdb gremlin database create utilizando cosmicworks.

   az cosmosdb gremlin database create \
       --resource-group "<resource-group-name>" \
       --account-name "<account-name>" \
       --name "cosmicworks"
   

4. Use el az cosmosdb gremlin graph create comando para crear un grafo denominado products.

   az cosmosdb gremlin graph create \
       --resource-group "<resource-group-name>" \
       --account-name "<account-name>" \
       --database-name "cosmicworks" \
       --name "products" \
       --partition-key-path "/category"
   

Azure Portal

1. Inicie sesión en Azure Portal (https://portal.azure.com).

2. Introduzca Azure Cosmos DB en la barra de búsqueda global.

3. En Servicios, seleccione Azure Cosmos DB.

4. En el panel Azure Cosmos DB , seleccione Crear y, después, Azure Cosmos DB para Apache Gremlin en la pestaña Otros .

5. En el panel Aspectos básicos, configure las siguientes opciones y, a continuación, seleccione Revisar y crear:

   	Value
   Tipo de carga de trabajo	Aprendizaje
   Suscripción	Seleccione su suscripción a Azure.
   Grupo de recursos	Cree un grupo de recursos nuevo o seleccione uno existente
   Nombre de cuenta	Proporcione un nombre único global.
   Zonas de disponibilidad	Deshabilitar
   Ubicación	Seleccione una región de Azure compatible para su suscripción

   Sugerencia

   Puede dejar cualquier opción no especificada con sus valores predeterminados. También puede configurar la cuenta para limitar el rendimiento total de la cuenta a 1000 unidades de solicitud por segundo (RU/s) o habilitar el nivel gratis para minimizar los costos.

6. En el panel Revisar y crear, espere a que la validación de la cuenta finalice correctamente y seleccione Crear.

7. El portal navega automáticamente al panel Implementación. Espere a que la implementación se complete.

8. Una vez completada la implementación, seleccione Ir al recurso para ir a la nueva API para la cuenta de Apache Gremlin.

9. En el menú de recursos, seleccione la opción Explorador de datos .

10. En el Explorador de datos, seleccione + Nuevo grafo.

11. En el cuadro de diálogo Agregar grafo , configure las siguientes opciones y, a continuación, seleccione Aceptar:

    	Value
    Base de datos	Crear nuevo
    Nombre de la base de datos	cosmicworks
    Nombre del grafo	products
    Clave de partición	/category

    Sugerencia

    Puede dejar cualquier opción no especificada con sus valores predeterminados.

Obtener credenciales

Ahora, obtenga la contraseña de la biblioteca cliente que se usará para crear una conexión a la cuenta creada recientemente.

Azure CLI

1. Use az cosmosdb show para obtener el host de la cuenta.

   az cosmosdb show \
       --resource-group "<resource-group-name>" \
       --name "<account-name>" \
       --query "{host:name}"
   

2. Registre el valor de la propiedad host de la salida de los comandos anteriores. El valor de esta propiedad es el host que se usa más adelante en esta guía para conectarse a la cuenta con la biblioteca.

3. Use az cosmosdb keys list para obtener las claves de la cuenta.

   az cosmosdb keys list \
       --resource-group "<resource-group-name>" \
       --name "<account-name>" \
       --type "keys"
   

4. Registre el valor de la propiedad primaryMasterKey de la salida de los comandos anteriores. El valor de esta propiedad es la clave que se usa más adelante en esta guía para conectarse a la cuenta con la biblioteca.

Azure Portal

1. En el menú de recursos de la cuenta, seleccione la opción Información general .

2. Registre el valor del nombre de la cuenta. El valor de esta propiedad es el host que se usa más adelante en esta guía para conectarse a la cuenta con la biblioteca.

3. En el menú de recursos de la cuenta de nuevo, seleccione la opción Cadenas de conexión en la sección Configuración .

4. Exponga y registre el valor del campo PRIMARY KEY en esta página. El valor de esta propiedad es la clave que se usa más adelante en esta guía para conectarse a la cuenta con la biblioteca.

Preparación del entorno de desarrollo

A continuación, configure el entorno de desarrollo con un nuevo proyecto y la biblioteca cliente. Este paso es el último requisito previo necesario antes de pasar al resto de esta guía.

1. Inicie en una carpeta vacía.

2. Importe el paquete desde el gremlinpython índice de paquetes de Python (PyPI).

   pip install gremlinpython
   

3. Abra el archivo app.py.

Modelo de objetos

	Descripción
GremlinClient	Representa el cliente usado para conectarse e interactuar con el servidor de Gremlin.
GraphTraversalSource	Se usa para construir y ejecutar recorridos de Gremlin

Ejemplos de código

• Autenticar cliente
• Inserción de datos
• Leer datos
• Consultar datos

Autenticar cliente

Empiece por autenticar al cliente con las credenciales recopiladas anteriormente en esta guía.

1. Abra el archivo app.py en el entorno de desarrollo integrado (IDE).

2. Importe los siguientes tipos desde la gremlin_python.driver biblioteca:

   • gremlin_python.driver.client
   • gremlin_python.driver.serializer

   from gremlin_python.driver import client, serializer
   

3. Cree variables de cadena para las credenciales recopiladas anteriormente en esta guía. Asigne un nombre a las variables hostname y primary_key.

   hostname = "<host>"
   primary_key = "<key>"
   

4. Cree un Client objeto con las credenciales y las variables de configuración creadas en los pasos anteriores. Asigne un nombre a la variable client.

   client = client.Client(
       url=f"wss://{hostname}.gremlin.cosmos.azure.com:443/",
       traversal_source="g",
       username="/dbs/cosmicworks/colls/products",
       password=f"{primary_key}",
       message_serializer=serializer.GraphSONSerializersV2d0()
   )
   

Insertar datos

A continuación, inserte nuevos datos de vértices y bordes en el gráfico. Antes de crear los nuevos datos, borre el gráfico de los datos existentes.

1. Ejecute la g.V().drop() consulta para borrar todos los vértices y bordes del grafo.

   client.submit("g.V().drop()").all().result()
   

2. Cree una consulta de Gremlin que agregue un vértice.

   insert_vertex_query = (
       "g.addV('product')"
       ".property('id', prop_id)"
       ".property('name', prop_name)"
       ".property('category', prop_category)"
       ".property('quantity', prop_quantity)"
       ".property('price', prop_price)"
       ".property('clearance', prop_clearance)"
   )
   

3. Agregue un vértice para un único producto.

   client.submit(
       message=insert_vertex_query,
       bindings={
           "prop_id": "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb",
           "prop_name": "Yamba Surfboard",
           "prop_category": "gear-surf-surfboards",
           "prop_quantity": 12,
           "prop_price": 850.00,
           "prop_clearance": False,
       },
   ).all().result()
   

4. Agregue dos vértices más para dos productos adicionales.

   client.submit(
       message=insert_vertex_query,
       bindings={
           "prop_id": "bbbbbbbb-1111-2222-3333-cccccccccccc",
           "prop_name": "Montau Turtle Surfboard",
           "prop_category": "gear-surf-surfboards",
           "prop_quantity": 5,
           "prop_price": 600.00,
           "prop_clearance": True,
       },
   ).all().result()
   
   client.submit(
       message=insert_vertex_query,
       bindings={
           "prop_id": "cccccccc-2222-3333-4444-dddddddddddd",
           "prop_name": "Noosa Surfboard",
           "prop_category": "gear-surf-surfboards",
           "prop_quantity": 31,
           "prop_price": 1100.00,
           "prop_clearance": False,
       },
   ).all().result()
   

5. Cree otra consulta de Gremlin que agregue un borde.

   insert_edge_query = (
       "g.V([prop_partition_key, prop_source_id])"
       ".addE('replaces')"
       ".to(g.V([prop_partition_key, prop_target_id]))"
   )
   

6. Agregue dos bordes.

   client.submit(
       message=insert_edge_query,
       bindings={
           "prop_partition_key": "gear-surf-surfboards",
           "prop_source_id": "bbbbbbbb-1111-2222-3333-cccccccccccc",
           "prop_target_id": "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb",
       },
   ).all().result()
   
   client.submit(
       message=insert_edge_query,
       bindings={
           "prop_partition_key": "gear-surf-surfboards",
           "prop_source_id": "bbbbbbbb-1111-2222-3333-cccccccccccc",
           "prop_target_id": "cccccccc-2222-3333-4444-dddddddddddd",
       },
   ).all().result()
   

Leer datos

A continuación, lea los datos que se insertaron anteriormente en el gráfico.

1. Cree una consulta que lea un vértice usando el identificador único y el valor de clave de partición.

   read_vertex_query = "g.V([prop_partition_key, prop_id])"
   

2. A continuación, lea un vértice proporcionando los parámetros necesarios.

   matched_item = client.submit(
       message=read_vertex_query,
       bindings={
           "prop_partition_key": "gear-surf-surfboards",
           "prop_id": "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb"
       }
   ).one()
   

Consultar datos

Por último, use una consulta para buscar todos los datos que coincidan con un recorrido o filtro específicos en el gráfico.

1. Cree una consulta que encuentre todos los vértices que parten desde un vértice específico.

   find_vertices_query = (
       "g.V().hasLabel('product')"
       ".has('category', prop_partition_key)"
       ".has('name', prop_name)"
       ".outE('replaces').inV()"
   )
   

2. Ejecute la consulta que especifica el Montau Turtle Surfboard producto.

   find_results = client.submit(
       message=find_vertices_query,
       bindings={
           "prop_partition_key": "gear-surf-surfboards",
           "prop_name": "Montau Turtle Surfboard",
       },
   ).all().result()
   

3. Recorre en iteración los resultados de la consulta.

   for result in find_results:
       # Do something here with each result
   

Ejecución del código

Ejecute la aplicación recién creada mediante un terminal en el directorio de la aplicación.

python app.py

Limpieza de recursos

Cuando ya no necesite la cuenta, quite la cuenta de la suscripción de Azure mediante la eliminación del recurso.

Azure CLI

az cosmosdb delete \
    --resource-group "<resource-group-name>" \
    --name "<account-name>"

Azure Portal

1. Vaya al recurso existente de Azure Cosmos DB for Apache Gremlin que creó anteriormente en esta guía.

2. En la página del recurso, seleccione Eliminar en la barra de menús.

3. Siga las instrucciones del cuadro de diálogo de confirmación.