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

  • Artículo

SE APLICA A: Gremlin

Azure Cosmos DB for Apache Gremlin es un servicio de base de datos de grafos totalmente administrado que implementa el conocido Apache Tinkerpop, un marco informático de grafos mediante el lenguaje de consulta Gremlin. La API para Gremlin ofrece una forma sencilla de empezar a usar Gremlin con un servicio que puede aumentar y escalar horizontalmente tanto como necesite con una administración mínima.

En este inicio rápido, usará la biblioteca gremlinpython para conectarse a una cuenta de Azure Cosmos DB for Gremlin recién creada.

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

Requisitos previos

Azure Cloud Shell

En Azure se hospeda Azure Cloud Shell, un entorno de shell interactivo que puede utilizar mediante el explorador. Puede usar Bash o PowerShell con Cloud Shell para trabajar con los servicios de Azure. Puede usar los comandos preinstalados de Cloud Shell para ejecutar el código de este artículo sin tener que instalar nada en su entorno local.

Para iniciar Azure Cloud Shell:

Opción Ejemplo o vínculo
Seleccione Pruébelo en la esquina superior derecha de un bloque de código o de comandos. Solo con seleccionar Pruébelo no se copia automáticamente el código o comando en Cloud Shell. Captura de pantalla que muestra un ejemplo de la opción Pruébelo para Azure Cloud Shell.
Vaya a https://shell.azure.com o seleccione el botón Iniciar Cloud Shell para abrir Cloud Shell en el explorador. Botón para iniciar Azure Cloud Shell.
Seleccione el botón Cloud Shell en la barra de menús de la esquina superior derecha de Azure Portal. Captura de pantalla que muestra el botón de Cloud Shell en Azure Portal

Para usar Azure Cloud Shell:

  1. Inicie Cloud Shell.

  2. Seleccione el botón Copiar en un bloque de código (o bloque de comandos) para copiar el código o comando.

  3. Pegue el código o comando en la sesión de Cloud Shell. Para ello, seleccione Ctrl+Mayús+V en Windows y Linux, o bien seleccione Cmd+Mayús+V en macOS.

  4. Seleccione Intro para ejecutar el código o comando.

Instalación

Esta sección le guía a través de la creación de una cuenta de API para Gremlin y la configuración de un proyecto de Python para usar la biblioteca para conectarse a la cuenta.

Creación de una API para una cuenta de Gremlin

La cuenta de API para Gremlin debe crearse antes de usar la biblioteca de Python. Además, ayuda a tener la base de datos y el grafo en su lugar.

  1. Cree variables de shell para accountName, resourceGroupName y location.

    # Variable for resource group name
resourceGroupName="msdocs-cosmos-gremlin-quickstart"
location="westus"

# Variable for account name with a randomly generated suffix

let suffix=$RANDOM*$RANDOM
accountName="msdocs-gremlin-$suffix"

  2. Si aún no lo ha hecho, inicie sesión en la CLI de Azure con az login.

  3. Use az group create para crear un nuevo grupo de recursos en la suscripción.

    az group create \
    --name $resourceGroupName \
    --location $location

  4. Use az cosmosdb create para crear una nueva cuenta de API para Gremlin con la configuración predeterminada.

    az cosmosdb create \
    --resource-group $resourceGroupName \
    --name $accountName \
    --capabilities "EnableGremlin" \
    --locations regionName=$location \
    --enable-free-tier true

    Nota:

    Puede tener una cuenta de Azure Cosmos DB de nivel Gratis por cada suscripción de Azure y debe optar por tenerla al crear la cuenta. Si este comando no consigue aplicar el descuento por nivel gratuito, significa que el nivel Gratis ya se habilitó en otra cuenta de la suscripción.

  5. Obtenga la API para el punto de conexión de Gremlin NAME para la cuenta con az cosmosdb show.

    az cosmosdb show \
    --resource-group $resourceGroupName \
    --name $accountName \
    --query "name"

  6. Busque KEY en la lista de claves de la cuenta con az-cosmosdb-keys-list.

    az cosmosdb keys list \
    --resource-group $resourceGroupName \
    --name $accountName \
    --type "keys" \
    --query "primaryMasterKey"

  7. Registre los valores NAME y KEY. Necesitará estas credenciales más adelante.

  8. Cree una base de datos denominada cosmicworks con az cosmosdb gremlin database create.

    az cosmosdb gremlin database create \
    --resource-group $resourceGroupName \
    --account-name $accountName \
    --name "cosmicworks"

  9. Cree un grafo mediante az cosmosdb gremlin graph create. Asigne un nombre al grafo products, establezca el rendimiento en 400 y, por último, establezca la ruta de acceso de la clave de partición en /category.

    az cosmosdb gremlin graph create \
    --resource-group $resourceGroupName \
    --account-name $accountName \
    --database-name "cosmicworks" \
    --name "products" \
    --partition-key-path "/category" \
    --throughput 400

Creación de una nueva aplicación de consola de Python

Cree una aplicación de consola de Python en una carpeta vacía con su terminal preferido.

  1. Abra el terminal en una carpeta vacía.

  2. Abra el archivo app.py.

    touch app.py

Instalación del paquete PyPI

Agregue el paquete PyPI gremlinpython al proyecto de Python.

  1. Cree el archivo requirements.txt.

    touch requirements.txt

  2. Agregue el paquete gremlinpython desde el índice de paquetes de Python al archivo de requisitos.

    gremlinpython==3.7.0

  3. Instale todos los requisitos en el proyecto.

    python install -r requirements.txt

Configurar variables de entorno

Para usar los valores NAME y URI obtenidos anteriormente en este inicio rápido, consérvelos en nuevas variables de entorno del equipo local que ejecuta la aplicación.

  1. Para establecer la variable de entorno, use el terminal para conservar los valores como COSMOS_ENDPOINT y COSMOS_KEY, respectivamente.

    export COSMOS_GREMLIN_ENDPOINT="<account-name>"
export COSMOS_GREMLIN_KEY="<account-key>"

  2. Compruebe que las variables de entorno se hayan establecido correctamente.

    printenv COSMOS_GREMLIN_ENDPOINT
printenv COSMOS_GREMLIN_KEY

Ejemplos de código

El código de este artículo se conecta a una base de datos denominada cosmicworks y a un grafo denominado products. A continuación, el código agrega vértices y bordes al gráfico antes de atravesar los elementos agregados.

Autenticar el cliente

Deben autorizarse las solicitudes de aplicación a la mayor parte de servicios de Azure. En el caso de la API para Gremlin, use los valores NAME y URI obtenidos anteriormente en este inicio rápido.

  1. Abra el archivo app.py.

  2. Importe client y serializer desde el módulo gremlin_python.driver.

    import os
from gremlin_python.driver import client, serializer

    Advertencia

    En función de la versión de Python, es posible que también tenga que importar asyncio e invalidar la directiva de bucle de eventos:

    import asyncio
import sys

if sys.platform == "win32":
    asyncio.set_event_loop_policy(asyncio.WindowsSelectorEventLoopPolicy())

  3. Cree variables ACCOUNT_NAME y ACCOUNT_KEY. Almacene las variables de entorno COSMOS_GREMLIN_ENDPOINT y COSMOS_GREMLIN_KEY como los valores de cada variable respectiva.

    ACCOUNT_NAME = os.environ["COSMOS_GREMLIN_ENDPOINT"]
ACCOUNT_KEY = os.environ["COSMOS_GREMLIN_KEY"]

  4. Use Client para conectarse mediante las credenciales de la cuenta y el serializador GraphSON 2.0.

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

Creación de vértices

Ahora que la aplicación está conectada a la cuenta, use la sintaxis estándar de Gremlin para crear vértices.

  1. Use submit para ejecutar un servidor de comandos en la cuenta de la API para Gremlin. Cree un vértice de producto con las siguientes propiedades:

    Valor
    label product
    id 68719518371
    name Kiama classic surfboard
    price 285.55
    category surfboards 
    client.submit(
    message=(
        "g.addV('product')"
        ".property('id', prop_id)"
        ".property('name', prop_name)"
        ".property('price', prop_price)"
        ".property('category', prop_partition_key)"
    ),
    bindings={
        "prop_id": "68719518371",
        "prop_name": "Kiama classic surfboard",
        "prop_price": 285.55,
        "prop_partition_key": "surfboards",
    },
)

  2. Cree un segundo vértice de producto con estas propiedades:

    Valor
    label product
    id 68719518403
    name Montau Turtle Surfboard
    price 600.00
    category surfboards 
    client.submit(
    message=(
        "g.addV('product')"
        ".property('id', prop_id)"
        ".property('name', prop_name)"
        ".property('price', prop_price)"
        ".property('category', prop_partition_key)"
    ),
    bindings={
        "prop_id": "68719518403",
        "prop_name": "Montau Turtle Surfboard",
        "prop_price": 600.00,
        "prop_partition_key": "surfboards",
    },
)

  3. Cree un tercer vértice de producto con estas propiedades:

    Valor
    label product
    id 68719518409
    name Bondi Twin Surfboard
    price 585.50
    category surfboards 
    client.submit(
    message=(
        "g.addV('product')"
        ".property('id', prop_id)"
        ".property('name', prop_name)"
        ".property('price', prop_price)"
        ".property('category', prop_partition_key)"
    ),
    bindings={
        "prop_id": "68719518409",
        "prop_name": "Bondi Twin Surfboard",
        "prop_price": 585.50,
        "prop_partition_key": "surfboards",
    },
)

Creación de bordes

Cree bordes mediante la sintaxis de Gremlin para definir relaciones entre vértices.

  1. Cree un perímetro desde el producto Montau Turtle Surfboard denominado replaces hasta el producto Kiama classic surfboard.

    client.submit(
    message=(
        "g.V([prop_partition_key, prop_source_id])"
        ".addE('replaces')"
        ".to(g.V([prop_partition_key, prop_target_id]))"
    ),
    bindings={
        "prop_partition_key": "surfboards",
        "prop_source_id": "68719518403",
        "prop_target_id": "68719518371",
    },
)

    Sugerencia

    Esta definición de borde usa la sintaxis g.V(['<partition-key>', '<id>']). Como alternativa, puede usar g.V('<id>').has('category', '<partition-key>').

  2. Crear otro reemplaza el borde desde el mismo producto hasta Bondi Twin Surfboard.

    client.submit(
    message=(
        "g.V([prop_partition_key, prop_source_id])"
        ".addE('replaces')"
        ".to(g.V([prop_partition_key, prop_target_id]))"
    ),
    bindings={
        "prop_partition_key": "surfboards",
        "prop_source_id": "68719518403",
        "prop_target_id": "68719518409",
    },
)

Consulta de vértices y bordes

Use la sintaxis de Gremlin para recorrer el grafo y detectar relaciones entre vértices.

  1. Recorra el grafo y busque todos los vértices que Montau Turtle Surfboard reemplaza.

    result = client.submit(
    message=(
        "g.V().hasLabel('product')"
        ".has('category', prop_partition_key)"
        ".has('name', prop_name)"
        ".outE('replaces').inV()"
    ),
    bindings={
        "prop_partition_key": "surfboards",
        "prop_name": "Montau Turtle Surfboard",
    },
)

  2. Escriba en la consola el resultado de este recorrido.

    print(result)

Ejecución del código

Compruebe que la aplicación funcione según lo previsto mediante la ejecución de la aplicación. La aplicación debe ejecutarse sin errores ni advertencias. La salida de la aplicación incluye datos sobre los elementos creados y consultados.

  1. Abra el terminal en la carpeta del proyecto de Python.

  2. Use python <filename> para ejecutar la aplicación. Observe la salida de la aplicación.

    python app.py

Limpieza de recursos

Cuando ya no necesite la cuenta de la API para Gremlin, podrá eliminar el grupo de recursos correspondiente.

  1. Cree una variable de shell para resourceGroupName si aún no existe.

    # Variable for resource group name
resourceGroupName="msdocs-cosmos-gremlin-quickstart"

  2. Use az group delete para eliminar el grupo de recursos.

    az group delete \
    --name $resourceGroupName

Paso siguiente

Creación y consulta de datos mediante Azure Cosmos DB for Apache Gremlin