Início rápido: biblioteca do Azure Cosmos DB for Apache Gremlin para Node.js

Artigo
10/26/2023

APLICA-SE AO: Gremlin

O Azure Cosmos DB for Apache Gremlin é um serviço de banco de dados de grafo totalmente gerenciado que implementa o popular Apache Tinkerpop, uma estrutura de computação de grafo que usa a linguagem de consulta Gremlin. A API para Gremlin oferece uma maneira fácil de começar a usar o Gremlin com um serviço que pode crescer e escalar horizontalmente conforme sua necessidade, com gerenciamento mínimo.

Neste início rápido, você usa a biblioteca gremlin para se conectar a uma conta recém-criada do Azure Cosmos DB for Gremlin.

Código-fonte da biblioteca | Pacote (npm)

Pré-requisitos

Uma conta do Azure com uma assinatura ativa.
- Nenhuma assinatura do Azure? Inscreva-se para obter uma conta do Azure gratuita.
- Não quer uma assinatura do Azure? Você pode experimentar o Azure Cosmos DB gratuitamente sem precisar de assinatura.
Node.js (LTS)
- Não tem o Node.js instalado? Experimente este início rápido no GitHub Codespaces.codespaces.new/github/codespaces-blank?quickstart=1)
CLI (interface de linha de comando) do Azure

Azure Cloud Shell

O Azure hospeda o Azure Cloud Shell, um ambiente de shell interativo que pode ser usado por meio do navegador. É possível usar o bash ou o PowerShell com o Cloud Shell para trabalhar com os serviços do Azure. É possível usar os comandos pré-instalados do Cloud Shell para executar o código neste artigo, sem precisar instalar nada no seu ambiente local.

Para iniciar o Azure Cloud Shell:

Opção	Exemplo/Link
Selecione Experimentar no canto superior direito de um bloco de código ou de comando. Selecionar Experimentar não copia automaticamente o código nem o comando para o Cloud Shell.
Acesse https://shell.azure.com ou selecione o botão Iniciar o Cloud Shell para abri-lo no navegador.
Selecione o botão Cloud Shell na barra de menus no canto superior direito do portal do Azure.

Para usar o Azure Cloud Shell:

Inicie o Cloud Shell.
Selecione o botão Copiar em um bloco de código (ou bloco de comando) para copiar o código ou o comando.
Cole o código ou comando na sessão do Cloud Shell selecionando Ctrl+Shift+V no Windows e no Linux, ou selecionando Cmd+Shift+V no macOS.
Pressione Enter para executar o código ou comando.

Configurando

Esta seção orienta você para a criação de uma conta da API para Gremlin e na configuração de um projeto Node.js para usar a biblioteca para se conectar à conta.

Criar uma conta da API para Gremlin

A conta da API para Gremlin deve ser criada antes de usar a biblioteca Node.js. Além disso, ajuda também ter o banco de dados e o grafo em vigor.

Crie variáveis em shell para accountName, resourceGroupName e localização.

# 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"

Caso ainda não tenha feito isso, entre na CLI do Azure usando az login.

Use az group create para criar um grupo de recursos na sua assinatura.

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

Use o az cosmosdb create para criar uma nova API para uma conta do Gremlin com as configurações padrão.
```
az cosmosdb create \
    --resource-group $resourceGroupName \
    --name $accountName \
    --capabilities "EnableGremlin" \
    --locations regionName=$location \
    --enable-free-tier true
```
Observação

Você pode ter no máximo uma conta do nível gratuito do Azure Cosmos DB por assinatura do Azure e deve aceitar ao criar a conta. Se esse comando falhar ao aplicar o desconto por nível gratuito, isso significa que outra conta na assinatura já foi habilitada com o nível gratuito.

Obtenha a API para o NOME do ponto de extremidade do Gremlin da conta utilizando az cosmosdb show.

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

Encontre a CHAVE na lista de chaves da conta com az-cosmosdb-keys-list.

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

Registre os valores NOME e CHAVE. Você usará essas credenciais mais tarde.

Crie um banco de dados chamado cosmicworks usando az cosmosdb gremlin database create.

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

Crie um grafo usando az cosmosdb gremlin graph create. Nomeie o grafo products e defina a taxa de transferência como 400 e, por fim, defina o caminho da chave de partição como /category.

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

Criar um aplicativo de console Node.js

Crie um aplicativo de console Node.js em uma pasta vazia usando seu terminal de preferência.

Abra o terminal em uma pasta vazia.
Inicializar um novo módulo
```
npm init es6 --yes
```
Crie o arquivo app.js
```
touch app.js
```

instalar o pacote npm

Adicione o pacote npm gremlin ao projeto Node.js.

Abra o arquivo package.json e substitua o conteúdo por essa configuração JSON.

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

Use o comando npm install para instalar todos os pacotes especificados no arquivo package.json.
```
npm install
```

Configurar variáveis de ambiente

Para utilizar os valores NOME e URI obtidos anteriormente neste início rápido: mantenha-os em novas variáveis de ambiente no computador local que está executando o aplicativo.

Para definir a variável de ambiente, utilize seu terminal para manter os valores como COSMOS_ENDPOINT e COSMOS_KEY, respectivamente.
```
export COSMOS_GREMLIN_ENDPOINT="<account-name>"
export COSMOS_GREMLIN_KEY="<account-key>"
```
Valide se as variáveis de ambiente foram definidas corretamente.
```
printenv COSMOS_GREMLIN_ENDPOINT
printenv COSMOS_GREMLIN_KEY
```

O código deste artigo conecta-se a um banco de dados denominado cosmicworks e a um gráfico denominado products. Em seguida, o código adiciona vértices e bordas ao gráfico antes de percorrer os itens adicionados.

Autenticar o cliente

As solicitações do aplicativo para a maioria dos serviços do Azure precisam ser autorizadas. Para a API do Gremlin, use os valores de NAME e URI obtidos anteriormente neste início rápido.

Abra o arquivo app.js.
Importe o módulo gremlin.
```
import gremlin from 'gremlin'
```
Crie as variáveis accountName e accountKey. Armazene as variáveis de ambiente COSMOS_GREMLIN_ENDPOINT e COSMOS_GREMLIN_KEY como os valores de cada variável respectiva.
```
const accountName = process.env.COSMOS_GREMLIN_ENDPOINT
const accountKey = process.env.COSMOS_GREMLIN_KEY
```

Use PlainTextSaslAuthenticator para criar um novo objeto para as credenciais da conta.

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

Use Client para se conectar usando as credenciais do servidor remoto e o serializador GraphSON 2.0. Em seguida, use Open para criar uma nova conexão com o 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()

Criar vértices

Agora que o aplicativo está conectado à conta, use a sintaxe padrão do Gremlin para criar os vértices.

Use submit para executar um comando do lado do servidor na conta da API para Gremlin. Crie um vértice de produtos com as seguintes propriedades:

	Valor
rótulo	`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'
  }
)

Crie um segundo vértice de produtos com essas propriedades:

	Valor
rótulo	`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'
  }
)

Crie um terceiro vértice de produtos com essas propriedades:

	Valor
rótulo	`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'
  }
)

Criar bordas

Crie bordas utilizando a sintaxe do Gremlin para definir os relacionamentos entre os vértices.

Crie uma borda de produto Montau Turtle Surfboard denominada substituições para o produto 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'
  }
)
```
Dica

Essa definição de borda utiliza a sintaxe g.V(['<partition-key>', '<id>']). Alternativamente, você pode utilizar g.V('<id>').has('category', '<partition-key>').

Crie outra borda de substituições do mesmo produto para o 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'
  }
)

Bordas e vértices de consulta

Use a sintaxe do Gremlin para percorrer o grafo e descobrir os relacionamentos entre os vértices.

Percorra o gráfico e encontre todos os vértices que Montau Turtle Surfboard substitui.

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

Grave no console o resultado dessa travessia.
```
console.dir(result)
```

Executar o código

Valide se seu aplicativo funciona conforme o esperado executando-o. O aplicativo deve ser executado sem erros ou avisos. A saída do aplicativo inclui dados sobre os itens criados e consultados.

Abra o terminal na pasta do projeto do Node.js.
Use npm <script> para executar o aplicativo. Observe a saída do aplicativo.
```
npm start
```

Limpar os recursos

Quando você não precisar mais da conta da API para Gremlin, exclua o grupo de recursos correspondente.

Crie uma variável de shell para resourceGroupName se ela ainda não existir.

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

Use az group delete para excluir o grupo de recursos.
```
az group delete \
    --name $resourceGroupName
```

Próxima etapa

Criar e consultar dados usando o Azure Cosmos DB for Apache Gremlin