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

APLICA-SE AO: Gremlin

• Console
• Python
• Node.js
• .NET

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:

1. Inicie o Cloud Shell.

2. Selecione o botão Copiar em um bloco de código (ou bloco de comando) para copiar o código ou o comando.

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

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

1. 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"
   

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

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

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

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

5. 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"
   

6. 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"
   

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

8. 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"
   

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

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

   docker pull tinkerpop/gremlin-console:3.4
   

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

3. Abra um novo terminal no contexto da pasta de trabalho que inclui o arquivo remote-secure.yaml.

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

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

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

2. 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')
   

3. 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']))
   

4. Conte todos os vértices do grafo.

   :> g.V().count()
   

5. 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()
   

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

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

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

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