Inicio rápido: Biblioteca de Azure Cosmos DB for Apache Gremlin para Node.js

Artículo
10/07/2023

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 gremlin para conectarse a una cuenta de Azure Cosmos DB for Gremlin recién creada.

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

Requisitos previos

Una cuenta de Azure con una suscripción activa.
- ¿No tiene una suscripción de Azure? Regístrese para obtener una cuenta de Azure gratuita.
- ¿No quiere una suscripción de Azure? Puede probar Azure Cosmos DB gratis sin necesidad de suscripción.
Node.js (LTS)
- ¿No tiene Node.js instalado? Pruebe este inicio rápido en GitHub Codespaces.codespaces.new/github/codespaces-blank?quickstart=1)
Interfaz de la línea de comandos (CLI) de Azure

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.
Vaya a https://shell.azure.com o seleccione el botón Iniciar Cloud Shell para abrir Cloud Shell en el explorador.
Seleccione el botón Cloud Shell en la barra de menús de la esquina superior derecha de Azure Portal.

Para usar Azure Cloud Shell:

Inicie Cloud Shell.
Seleccione el botón Copiar en un bloque de código (o bloque de comandos) para copiar el código o comando.
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.
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 Node.js 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 Node.js. Además, ayuda a tener la base de datos y el grafo en su lugar.

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"

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

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

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

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.

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"

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"

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

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"

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 aplicación de consola de Node.js

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

Abra el terminal en una carpeta vacía.
Inicialice un nuevo módulo.
```
npm init es6 --yes
```
Cree el archivo app.js.
```
touch app.js
```

Instalación del paquete npm

Agregue el paquete de npm gremlin al proyecto de Node.js.

Abra el archivo package.json y reemplace el contenido por esta configuración JSON.

{
  "main": "app.js",
  "type": "module",
  "scripts": {
    "start": "node app.js"
  },
  "dependencies": {
    "gremlin": "^3.*"
  }
}

Use el comando npm install para instalar todos los paquetes especificados en el archivo package.json.
```
npm install
```

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.

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>"
```
Compruebe que las variables de entorno se hayan establecido correctamente.
```
printenv COSMOS_GREMLIN_ENDPOINT
printenv COSMOS_GREMLIN_KEY
```

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.

Abra el archivo app.js.
Importe el módulo gremlin.
```
import gremlin from 'gremlin'
```
Cree variables accountName y accountKey. Almacene las variables de entorno COSMOS_GREMLIN_ENDPOINT y COSMOS_GREMLIN_KEY como los valores de cada variable respectiva.
```
const accountName = process.env.COSMOS_GREMLIN_ENDPOINT
const accountKey = process.env.COSMOS_GREMLIN_KEY
```

Cree un nuevo objeto para las credenciales de la cuenta mediante PlainTextSaslAuthenticator.

const credentials = new gremlin.driver.auth.PlainTextSaslAuthenticator(
  '/dbs/cosmicworks/colls/products',
  `${accountKey}`
)

Use Client para conectarse mediante las credenciales del servidor remoto y el serializador GraphSON 2.0. A continuación, use Open para crear una nueva conexión al servidor.

const client = new gremlin.driver.Client(
  `wss://${accountName}.gremlin.cosmos.azure.com:443/`,
  {
    credentials,
    traversalsource: 'g',
    rejectUnauthorized: true,
    mimeType: 'application/vnd.gremlin-v2.0+json'
  }
)

client.open()

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.

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`

await client.submit(
  'g.addV(\'product\').property(\'id\', prop_id).property(\'name\', prop_name).property(\'price\', prop_price).property(\'category\', prop_partition_key)', {
    prop_id: '68719518371',
    prop_name: 'Kiama classic surfboard',
    prop_price: 285.55,
    prop_partition_key: 'surfboards'
  }
)

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

	Valor
label	`product`
id	`68719518403`
`name`	`Montau Turtle Surfboard`
`price`	`600.00`
`category`	`surfboards`

await client.submit(
  'g.addV(\'product\').property(\'id\', prop_id).property(\'name\', prop_name).property(\'price\', prop_price).property(\'category\', prop_partition_key)', {
    prop_id: '68719518403',
    prop_name: 'Montau Turtle Surfboard',
    prop_price: 600.00,
    prop_partition_key: 'surfboards'
  }
)

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

	Valor
label	`product`
id	`68719518409`
`name`	`Bondi Twin Surfboard`
`price`	`585.50`
`category`	`surfboards`

await client.submit(
  'g.addV(\'product\').property(\'id\', prop_id).property(\'name\', prop_name).property(\'price\', prop_price).property(\'category\', prop_partition_key)', {
    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.

Cree un perímetro desde el producto Montau Turtle Surfboard denominado replaces hasta el producto Kiama classic surfboard.
```
await client.submit(
  'g.V([prop_partition_key, prop_source_id]).addE(\'replaces\').to(g.V([prop_partition_key, prop_target_id]))', {
    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>').

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

await client.submit(
  'g.V([prop_partition_key, prop_source_id]).addE(\'replaces\').to(g.V([prop_partition_key, prop_target_id]))', {
    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.

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

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

Escriba en la consola el resultado de este recorrido.
```
console.dir(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.

Abra el terminal en la carpeta del proyecto de Node.js.
Use npm <script> para ejecutar la aplicación. Observe la salida de la aplicación.
```
npm start
```

Limpieza de recursos

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

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

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

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