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

Artigo
03/10/2024

APLICA-SE A: Gremlin

O Azure Cosmos DB para Apache Gremlin é um serviço de banco de dados gráfico totalmente gerenciado que implementa o popular Apache Tinkerpop, uma estrutura de computação gráfica usando a linguagem de consulta Gremlin. A API para Gremlin oferece uma maneira de baixo atrito para começar a usar Gremlin com um serviço que pode crescer e expandir tanto quanto você precisa com gerenciamento mínimo.

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

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

Pré-requisitos

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

Azure Cloud Shell

O Azure aloja o Azure Cloud Shell, um ambiente de shell interativo que pode utilizar através do seu browser. Pode utilizar o Bash ou o PowerShell com o Cloud Shell para trabalhar com os serviços do Azure. Você pode usar os comandos pré-instalados do Cloud Shell para executar o código neste artigo, sem precisar instalar nada em seu ambiente local.

Para iniciar o Azure Cloud Shell:

Opção	Exemplo/Ligação
Selecione Experimentar no canto superior direito de um código ou bloco de comandos. Selecionar Experimentar não copia automaticamente o código ou comando para o Cloud Shell.
Aceda a https://shell.azure.com ou selecione o botão Iniciar Cloud Shell para abrir o Cloud Shell no browser.
Selecione o botão Cloud Shell na barra de menus, na parte direita 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 comando.
Cole o código ou comando na sessão do Cloud Shell selecionando Ctrl+Shift+V no Windows e Linux ou selecionando Cmd+Shift+V no macOS.
Selecione Enter para executar o código ou comando.

Configuração

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

Criar uma API para a conta Gremlin

A API para a conta Gremlin deve ser criada antes de usar a biblioteca Node.js. Além disso, ajuda também ter o banco de dados e o gráfico no lugar.

Crie variáveis de shell para accountName, resourceGroupName e 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"

Se ainda não o fez, entre na CLI do Azure usando az logino .

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

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

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

Você pode ter até uma conta gratuita do Azure Cosmos DB por assinatura do Azure e deve optar por participar ao criar a conta. Se esse comando não aplicar o desconto de nível gratuito, isso significa que outra conta na assinatura já foi habilitada com o nível gratuito.

Obtenha a API para o ponto de extremidade Gremlin NAME para a conta usando az cosmosdb showo .

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 NAME e KEY . Você usa 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 gráfico usando az cosmosdb gremlin graph createo . Nomeie o gráfico productse, em seguida, defina a taxa de transferência como 400e, finalmente, 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 novo aplicativo de console Node.js

Crie um aplicativo de console Node.js em uma pasta vazia usando seu terminal preferido.

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

Instalar o pacote npm

Adicione o gremlin pacote npm 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 npm install comando para instalar todos os pacotes especificados no arquivo package.json .
```
npm install
```

Configurar variáveis de ambiente

Para usar os valores NAME e URI obtidos anteriormente neste início rápido, persista-os para novas variáveis de ambiente na máquina local que executa o aplicativo.

Para definir a variável de ambiente, use seu terminal para persistir 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 neste artigo se conecta a um banco de dados chamado cosmicworks e a um gráfico chamado products. Em seguida, o código adiciona vértices e arestas ao gráfico antes de percorrer os itens adicionados.

Autenticar o cliente

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

Abra o arquivo app.js .
Importe o gremlin módulo.
```
import gremlin from 'gremlin'
```
Criar accountName e accountKey variáveis. Armazene as variáveis e COSMOS_GREMLIN_KEY de COSMOS_GREMLIN_ENDPOINT ambiente como os valores para cada variável respetiva.
```
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 Gremlin padrão para criar vértices.

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

	Value
etiqueta	`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 produto com estas propriedades:

	Value
etiqueta	`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 produto com estas propriedades:

	Value
etiqueta	`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 arestas

Crie arestas usando a sintaxe Gremlin para definir relações entre vértices.

Crie uma borda do Montau Turtle Surfboard produto chamado substitui para o Kiama classic surfboard produto.
```
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'
  }
)
```
Gorjeta

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

Criar outro substitui a borda 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'
  }
)

Consultar vértices & arestas

Use a sintaxe de Gremlin para atravessar o gráfico e descobrir relações entre vértices.

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

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

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

Executar o código

Valide se seu aplicativo funciona conforme o esperado executando o aplicativo. 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 Node.js projeto.
Use npm <script> para executar o aplicativo. Observe a saída do aplicativo.
```
npm start
```

Clean up resources (Limpar recursos)

Quando você não precisar mais da API para a conta 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óximo passo

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