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

• 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 al uso de la biblioteca cliente Azure Cosmos DB for Apache Gremlin para Node.js con el fin de almacenar, administrar y consultar datos no estructurados. Siga los pasos de esta guía para crear una cuenta, instalar una biblioteca cliente de Node.js, conectarse a la cuenta, realizar operaciones comunes y consultar los datos finales de ejemplo.

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

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 .

• Node.js 22 o posteriores

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 usando az cosmosdb gremlin database create llamada 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. Inicialice un nuevo módulo.

   npm init es6 --yes
   

3. Instale el gremlin paquete desde el Administrador de paquetes de Node (npm).

   npm install --save gremlin
   

4. Cree el archivo index.js .

1. Inicie en una carpeta vacía.

2. Inicialice un nuevo módulo.

   npm init es6 --yes
   

3. Instale el typescript paquete desde el Administrador de paquetes de Node (npm).

   npm install --save-dev typescript
   

4. Instale el tsx paquete desde npm.

   npm install --save-dev tsx
   

5. Instale el gremlin paquete desde npm.

   npm install --save gremlin
   

6. Instale el @types/node paquete desde npm.

   npm install --save-dev @types/node
   

7. Instale el @types/gremlin paquete desde npm.

   npm install --save-dev @types/gremlin
   

8. Inicialice el proyecto de TypeScript mediante el compilador (tsc).

   npx tsc --init --target es2017 --module es2022 --moduleResolution nodenext
   

9. Cree el archivo index.ts .

Modelo de objetos

	Descripción
DriverRemoteConnection	Representa la conexión al 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 index.js en el entorno de desarrollo integrado (IDE).

2. Importe el gremlin paquete y los tipos necesarios:

   import gremlin from 'gremlin';
   const { Client, auth } = gremlin.driver;
   const { PlainTextSaslAuthenticator } = auth;
   

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

   const hostname = '<host>';
   const primaryKey = '<key>';
   

4. Cree un objeto de tipo PlainTextSaslAuthenticator mediante las credenciales y las variables de configuración creadas en los pasos anteriores. Almacene el objeto en una variable denominada authenticator.

   const authenticator = new PlainTextSaslAuthenticator(
       '/dbs/cosmicworks/colls/products',
       primaryKey
   );
   

5. Cree un Client objeto mediante la variable authenticator. Asigne un nombre a la variable client.

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

1. Abra el archivo index.ts en el entorno de desarrollo integrado (IDE).

2. Importe el gremlin paquete y los tipos necesarios:

   import gremlin from 'gremlin';
   const { Client, auth } = gremlin.driver;
   const { PlainTextSaslAuthenticator } = auth;
   

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

   const hostname: string = '<host>';
   const primaryKey: string = '<key>';
   

4. Cree un objeto de tipo PlainTextSaslAuthenticator mediante las credenciales y las variables de configuración creadas en los pasos anteriores. Almacene el objeto en una variable denominada authenticator.

   const authenticator = new PlainTextSaslAuthenticator(
       '/dbs/cosmicworks/colls/products',
       primaryKey
   );
   

5. Cree un Client objeto mediante la variable authenticator. Asigne un nombre a la variable client.

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

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.

   await client.submit('g.V().drop()');
   

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

   const 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.

   await client.submit(insert_vertex_query, {
       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,
   });
   

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

   await client.submit(insert_vertex_query, {
       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,
   });
   
   await client.submit(insert_vertex_query, {
       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,
   });
   

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

   const 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.

   await client.submit(insert_edge_query, {
       prop_partition_key: 'gear-surf-surfboards',
       prop_source_id: 'bbbbbbbb-1111-2222-3333-cccccccccccc',
       prop_target_id: 'aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb',
   });
   
   await client.submit(insert_edge_query, {
       prop_partition_key: 'gear-surf-surfboards',
       prop_source_id: 'bbbbbbbb-1111-2222-3333-cccccccccccc',
       prop_target_id: 'cccccccc-2222-3333-4444-dddddddddddd',
   });
   

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

   await client.submit('g.V().drop()');
   

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

   const insert_vertex_query: string = `
       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.

   await client.submit(insert_vertex_query, {
       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,
   });
   

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

   await client.submit(insert_vertex_query, {
       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,
   });
   
   await client.submit(insert_vertex_query, {
       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,
   });
   

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

   const insert_edge_query: string = `
       g.V([prop_partition_key, prop_source_id])
           .addE('replaces')
           .to(g.V([prop_partition_key, prop_target_id]))
   `;
   

6. Agregue dos bordes.

   await client.submit(insert_edge_query, {
       prop_partition_key: 'gear-surf-surfboards',
       prop_source_id: 'bbbbbbbb-1111-2222-3333-cccccccccccc',
       prop_target_id: 'aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb',
   });
   
   await client.submit(insert_edge_query, {
       prop_partition_key: 'gear-surf-surfboards',
       prop_source_id: 'bbbbbbbb-1111-2222-3333-cccccccccccc',
       prop_target_id: 'cccccccc-2222-3333-4444-dddddddddddd',
   });
   

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.

   const read_vertex_query = 'g.V([prop_partition_key, prop_id])';
   

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

   let read_results = await client.submit(read_vertex_query, {
       prop_partition_key: 'gear-surf-surfboards',
       prop_id: 'aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb',
   });
   
   let matched_item = read_results._items[0];
   

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

   const read_vertex_query: string = 'g.V([prop_partition_key, prop_id])';
   

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

   let read_results = await client.submit(read_vertex_query, {
       prop_partition_key: 'gear-surf-surfboards',
       prop_id: 'aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb',
   });
   
   let matched_item = read_results._items[0];
   

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.

   const 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.

   let find_results = await client.submit(find_vertices_query, {
       prop_partition_key: 'gear-surf-surfboards',
       prop_name: 'Montau Turtle Surfboard',
   });
   

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

   for (const item of find_results._items) {
       // Do something here with each result
   }
   

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

   const find_vertices_query: string = `
       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.

   let find_results = await client.submit(find_vertices_query, {
       prop_partition_key: 'gear-surf-surfboards',
       prop_name: 'Montau Turtle Surfboard',
   });
   

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

   for (const item of find_results._items) {
       // 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.

node index.js

npx tsx index.ts

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.