Início Rápido: Percorrer vértices e bordas com o console do Gremlin e o Azure Cosmos DB for Apache Gremlin

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 forma descomplicada de começar a usar o Gremlin com um serviço que pode crescer e se expandir até o máximo de que você precisar com o mínimo de gerenciamento.

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

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? Experimente o Azure Cosmos DB gratuitamente sem necessidade de assinatura.
Host do Docker
- Não tem o Docker instalado? Experimente este início rápido no GitHub Codespaces.
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.

Criar uma conta da API para Gremlin e os recursos relevantes

A conta da API para Gremlin deve ser criada antes de usar o console do Gremlin. Além disso, também é útil ter o banco de dados e o grafo implementados.

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. Dê ao grafo o nome products, 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

Iniciar e configurar o console do Gremlin usando o Docker

Para o console do Gremlin, este início rápido usa a imagem de contêiner tinkerpop/gremlin-console do Docker Hub. Essa imagem garante que você esteja usando a versão apropriada do console (3.4) para conexão com a API para Gremlin. Depois que o console estiver em execução, conecte-se no host local do Docker à conta remota da API para Gremlin.

Efetue pull da versão 3.4 da imagem de contêiner tinkerpop/gremlin-console.
```
docker pull tinkerpop/gremlin-console:3.4
```

Crie uma pasta de trabalho vazia. Na pasta vazia, crie um arquivo remote-secure.yaml. Adicione essa configuração YAML ao arquivo.

hosts: [<account-name>.gremlin.cosmos.azure.com]
port: 443
username: /dbs/cosmicworks/colls/products
password: <account-key>
connectionPool: {
  enableSsl: true,
  sslEnabledProtocols: [TLSv1.2]
}
serializer: {
  className: org.apache.tinkerpop.gremlin.driver.ser.GraphSONMessageSerializerV2d0,
  config: {
    serializeResultToString: true
  }
}

Observação

Substitua os espaços reservados <account-name> e <account-key> pelos valores de NAME e KEY obtidos anteriormente neste início rápido.

Abra um novo terminal no contexto da pasta de trabalho que inclui o arquivo remote-secure.yaml.
Execute a imagem de contêiner do Docker no modo interativo (--interactive --tty). Lembre-se de montar a pasta de trabalho atual no caminho /opt/gremlin-console/conf/ dentro do contêiner.
```
docker run -it --mount type=bind,source=.,target=/opt/gremlin-console/conf/ tinkerpop/gremlin-console:3.4
```
No contêiner do console do Gremlin, conecte-se à conta remota (API para Gremlin) usando o arquivo de configuração remote-secure.yaml.
```
:remote connect tinkerpop.server conf/remote-secure.yaml
```

Criar e percorrer vértices e bordas

Agora que o console está conectado à conta, use a sintaxe padrão do Gremlin para criar e percorrer vértices e bordas.

Adicione um vértice para um produto com as seguintes propriedades:

Valor

rótulo product

id 68719518371

name Kiama classic surfboard

price 285.55

category surfboards
```
:> g.addV('product').property('id', '68719518371').property('name', 'Kiama classic surfboard').property('price', 285.55).property('category', 'surfboards')
```
Importante

Não se esqueça do prefixo :>. Esse prefixo é necessário para executar o comando remotamente.

Adicione outro vértice de produto com estas propriedades:

	Valor
rótulo	`product`
id	`68719518403`
`name`	`Montau Turtle Surfboard`
`price`	`600`
`category`	`surfboards`

:> g.addV('product').property('id', '68719518403').property('name', 'Montau Turtle Surfboard').property('price', 600).property('category', 'surfboards')

Crie uma borda chamada replaces para definir uma relação entre os dois produtos.

:> g.V(['surfboards', '68719518403']).addE('replaces').to(g.V(['surfboards', '68719518371']))

Conte todos os vértices do grafo.
```
:> g.V().count()
```

Percorra o grafo para localizar todos os vértices que substituem o Kiama classic surfboard.

:> g.V().hasLabel('product').has('category', 'surfboards').has('name', 'Kiama classic surfboard').inE('replaces').outV()

Percorra o grafo para localizar todos os vértices substituídos por Montau Turtle Surfboard.

:> g.V().hasLabel('product').has('category', 'surfboards').has('name', 'Montau Turtle Surfboard').outE('replaces').inV()

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
```

Como resolvemos o problema?

O Azure Cosmos DB for Apache Gremlin resolveu o problema oferecendo o Gremlin como um serviço. Com essa oferta, você não precisa criar instâncias de servidor próprias do Gremlin nem gerenciar uma infraestrutura própria. Além disso, você pode escalar a solução à medida que suas necessidades aumentam ao longo do tempo.

Para se conectar à conta da API para Gremlin, você usou a imagem de contêiner tinkerpop/gremlin-console para executar o console do Gremlin de maneira a não exigir uma instalação local. Em seguida, você usou a configuração armazenada no arquivo remote-secure.yaml para se conectar do contêiner em execução à conta da API para Gremlin. Nela, você executou vários comandos comuns do Gremlin.

Próxima etapa

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

	Valor
rótulo	`product`
id	`68719518371`
`name`	`Kiama classic surfboard`
`price`	`285.55`
`category`	`surfboards`