Guia de início rápido: biblioteca de cliente do Azure Cosmos DB para Apache Gremlin para Node.js

• Python
• Node.js
• C#

Importante

Você está procurando uma solução de banco de dados para cenários de alta escala com um contrato de nível de serviço (SLA) de disponibilidade de 99.999%, dimensionamento automático instantâneo e failover automático em várias regiões? Considere Azure Cosmos DB para NoSQL.

Você está procurando implementar um gráfico de processamento analítico on-line (OLAP) ou migrar um aplicativo Apache Gremlin existente? Considere o gráfico no Microsoft Fabric.

Introdução à biblioteca de cliente do Azure Cosmos DB para Apache Gremlin para Node.js armazenar, gerenciar e consultar dados não estruturados. Siga as etapas neste guia para criar uma nova conta, instalar uma biblioteca de cliente Node.js, conectar-se à conta, executar operações comuns e consultar seus dados de exemplo finais.

Pacote de código-fonte | da biblioteca (npm)

Pré-requisitos

• Uma assinatura do Azure

  • Se não tiver uma subscrição do Azure, crie uma conta gratuita antes de começar.

• A versão mais recente da CLI do Azure no Azure Cloud Shell.

  • Se preferir executar comandos de referência da CLI localmente, entre na CLI do Azure usando o az login comando.

• Node.js 22 ou superior

Configuração

Primeiro, configure a conta e o ambiente de desenvolvimento para este guia. Esta seção orienta você pelo processo de criação de uma conta, obtenção de suas credenciais e, em seguida, preparação do ambiente de desenvolvimento.

Criar uma conta

Comece criando uma API para a conta Apache Gremlin. Depois que a conta for criada, crie o banco de dados e os recursos gráficos.

CLI do Azure

1. Se você ainda não tiver um grupo de recursos de destino, use o az group create comando para criar um novo grupo de recursos em sua assinatura.

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

2. Use o az cosmosdb create comando para criar uma nova conta do Azure Cosmos DB para Apache Gremlin com configurações padrão.

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

3. Crie uma nova base de dados utilizando az cosmosdb gremlin database create denominado cosmicworks.

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

4. Use o az cosmosdb gremlin graph create comando para criar um novo gráfico chamado products.

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

portal do Azure

1. Entre no portal do Azure (https://portal.azure.com).

2. Insira Azure Cosmos DB na barra de pesquisa global.

3. Em Serviços, selecione Azure Cosmos DB.

4. No painel Azure Cosmos DB , selecione Criar e, em seguida, Azure Cosmos DB para Apache Gremlin na guia Outros .

5. No painel Noções básicas, configure as seguintes opções e selecione Revisar + criar:

   	Value
   Tipo de carga de trabalho	Aprendizagem
   Subscrição	Selecione sua assinatura do Azure
   Grupo de Recursos	Criar um novo grupo de recursos ou selecionar um grupo de recursos existente
   Nome da Conta	Forneça um nome globalmente exclusivo
   Zonas de Disponibilidade	Desativar
   Localização	Selecione uma região do Azure suportada para a sua subscrição

   Gorjeta

   Você pode deixar quaisquer opções não especificadas para seus valores padrão. Você também pode configurar a conta para limitar a taxa de transferência total da conta a 1.000 unidades de solicitação por segundo (RU/s) ou habilitar o nível gratuito para minimizar seus custos.

6. No painel Rever + criar, aguarde até que a validação da sua conta conclua com sucesso e, em seguida, selecione Criar.

7. O Portal navega automaticamente para o painel Implantação. Aguarde até que a implementação seja concluída.

8. Quando a implantação estiver concluída, selecione Ir para o recurso para navegar até a nova API para a conta Apache Gremlin.

9. No menu de recursos, selecione a opção Data Explorer .

10. No Data Explorer, selecione + Novo Gráfico.

11. Na caixa de diálogo Adicionar gráfico, configure as seguintes opções e selecione OK:

    	Value
    Base de dados	Criar novo
    Nome da base de dados	cosmicworks
    Nome do gráfico	products
    Chave de partição	/category

    Gorjeta

    Você pode deixar quaisquer opções não especificadas para seus valores padrão.

Obter credenciais

Agora, obtenha a senha para a biblioteca do cliente usar para criar uma conexão com a conta criada recentemente.

CLI do Azure

1. Use az cosmosdb show para obter o host para a conta.

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

2. Registe o valor da propriedade host proveniente da saída dos comandos anteriores. O valor desta propriedade é o host que você usa posteriormente neste guia para se conectar à conta com a biblioteca.

3. Use az cosmosdb keys list para obter as chaves da conta.

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

4. Registe o valor da propriedade primaryMasterKey proveniente da saída dos comandos anteriores. O valor dessa propriedade é a chave que você usa posteriormente neste guia para se conectar à conta com a biblioteca.

portal do Azure

1. No menu de recursos da conta, selecione a opção Visão geral .

2. Registre o valor do nome da conta. O valor dessa propriedade é o host que você usa posteriormente neste guia para se conectar à conta com a biblioteca.

3. No menu de recursos da conta novamente, selecione a opção Cadeias de conexão na seção Configurações .

4. Exponha e registre o valor do campo CHAVE PRIMÁRIA nesta página. O valor dessa propriedade é a chave que você usa posteriormente neste guia para se conectar à conta com a biblioteca.

Preparar o ambiente de desenvolvimento

Em seguida, configure seu ambiente de desenvolvimento com um novo projeto e a biblioteca do cliente. Esta etapa é o último pré-requisito necessário antes de passar para o resto deste guia.

1. Comece em uma pasta vazia.

2. Inicialize um novo módulo.

   npm init es6 --yes
   

3. Instale o pacote gremlin a partir do Gestor de Pacotes Node (npm).

   npm install --save gremlin
   

4. Crie o arquivo index.js .

1. Comece em uma pasta vazia.

2. Inicialize um novo módulo.

   npm init es6 --yes
   

3. Instale o pacote typescript a partir do Gestor de Pacotes Node (npm).

   npm install --save-dev typescript
   

4. Instale o pacote tsx do npm.

   npm install --save-dev tsx
   

5. Instale o pacote gremlin do npm.

   npm install --save gremlin
   

6. Instale o pacote @types/node do npm.

   npm install --save-dev @types/node
   

7. Instale o pacote @types/gremlin do npm.

   npm install --save-dev @types/gremlin
   

8. Inicialize o projeto TypeScript usando o compilador (tsc).

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

9. Crie o arquivo index.ts .

Modelo de objeto

	Descrição
DriverRemoteConnection	Representa a conexão com o servidor Gremlin
GraphTraversalSource	Usado para construir e executar percursos de Gremlin

Exemplos de código

• Autenticar cliente
• Inserir dados
• Ler dados
• Consultar dados

Autenticar cliente

Comece autenticando o cliente usando as credenciais reunidas anteriormente neste guia.

1. Abra o ficheiro index.js no seu ambiente de desenvolvimento integrado (IDE).

2. Importe o gremlin pacote e os tipos necessários.

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

3. Crie variáveis de cadeia de caracteres para as credenciais coletadas anteriormente neste guia. Nomeie as variáveis hostname e primaryKey.

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

4. Crie um objeto do tipo PlainTextSaslAuthenticator usando as credenciais e variáveis de configuração criadas nas etapas anteriores. Armazene o objeto em uma variável chamada authenticator.

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

5. Crie um Client objeto usando a variável autenticadora. Nomeie a variável 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 o arquivo index.ts em seu ambiente de desenvolvimento integrado (IDE).

2. Importe o gremlin pacote e os tipos necessários.

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

3. Crie variáveis de cadeia de caracteres para as credenciais coletadas anteriormente neste guia. Nomeie as variáveis hostname e primaryKey.

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

4. Crie um objeto do tipo PlainTextSaslAuthenticator usando as credenciais e variáveis de configuração criadas nas etapas anteriores. Armazene o objeto em uma variável chamada authenticator.

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

5. Crie um Client objeto usando a variável autenticadora. Nomeie a variável client.

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

Inserir dados

Em seguida, insira novos dados de vértice e borda no gráfico. Antes de criar os novos dados, limpe o gráfico de todos os dados existentes.

1. Execute a g.V().drop() consulta para limpar todos os vértices e arestas do gráfico.

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

2. Crie uma consulta Gremlin que adicione um 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. Adicione um vértice para um único produto.

   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. Adicione mais dois vértices para dois produtos extras.

   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. Crie outra consulta Gremlin que adicione uma aresta.

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

6. Adicione duas arestas.

   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. Execute a g.V().drop() consulta para limpar todos os vértices e arestas do gráfico.

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

2. Crie uma consulta Gremlin que adicione um 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. Adicione um vértice para um único produto.

   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. Adicione mais dois vértices para dois produtos extras.

   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. Crie outra consulta Gremlin que adicione uma aresta.

   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. Adicione duas arestas.

   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',
   });
   

Ler dados

Em seguida, leia os dados que foram inseridos anteriormente no gráfico.

1. Crie uma consulta que leia um vértice usando o identificador exclusivo e o valor da chave de partição.

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

2. Em seguida, leia um vértice fornecendo os parâmetros necessários.

   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. Crie uma consulta que leia um vértice usando o identificador exclusivo e o valor da chave de partição.

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

2. Em seguida, leia um vértice fornecendo os parâmetros necessários.

   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 dados

Finalmente, use uma consulta para localizar todos os dados que correspondem a uma travessia ou filtro específico no gráfico.

1. Crie uma consulta que encontre todos os vértices que saem de um 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. Execute a consulta especificando o Montau Turtle Surfboard produto.

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

3. Itere sobre os resultados da consulta.

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

1. Crie uma consulta que encontre todos os vértices que saem de um 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. Execute a consulta especificando o Montau Turtle Surfboard produto.

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

3. Itere sobre os resultados da consulta.

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

Executar o código

Execute o aplicativo recém-criado usando um terminal no diretório do aplicativo.

node index.js

npx tsx index.ts

Clean up resources (Limpar recursos)

Quando você não precisar mais da conta, remova a conta da sua assinatura do Azure excluindo o recurso.

CLI do Azure

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

portal do Azure

1. Navegue até o recurso existente do Azure Cosmos DB para Apache Gremlin que você criou anteriormente neste guia.

2. Na página do recurso, selecione Excluir na barra de menus.

3. Siga as instruções na caixa de diálogo de confirmação.