Guia de início rápido: percorra vértices e bordas com o console Gremlin e o Azure Cosmos DB para Apache 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 o console Gremlin para se conectar a uma conta recém-criada do Azure Cosmos DB para Gremlin.

Pré-requisitos

• Uma conta do Azure com uma assinatura ativa.
  • Não há assinatura do Azure? Inscreva-se para obter uma conta gratuita do Azure.
• Servidor Docker
  • Não tem o Docker instalado? Experimente este início rápido no GitHub Codespaces.
• 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. Você pode usar 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:

Option	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.
Vá para https://shell.azure.com, ou selecione o botão Iniciar o Cloud Shell para abrir o Cloud Shell no navegador.
Selecione o botão Cloud Shell na barra de menus no canto superior direito do portal do Azure.

Para usar Azure Cloud Shell:

1. Iniciar Cloud Shell.

2. Selecione o botão Copiar em um bloco de código (ou bloco de comando) para copiar o código ou 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. Selecione Enter para executar o código ou comando.

Criar uma API para a conta Gremlin e recursos relevantes

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

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

2. Se ainda não o fez, inicie sessão na CLI do Azure usando az login.

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

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

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

   Observação

   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.

5. Obtenha a API do endpoint Gremlin NAME para a conta usando 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. Registe os valores de NAME e KEY. Utilizará estas 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 gráfico usando az cosmosdb gremlin graph create. 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
   

Iniciar e configurar o console Gremlin usando o Docker

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

1. Obtenha a 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 esta 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 símbolos de posição <account-name> e <account-key> pelos valores de NAME e KEY obtidos anteriormente neste guia rápido.

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

4. Execute a imagem do contêiner do Docker no modo interativo (--interactive --tty). Certifique-se de montar a pasta de trabalho atual no /opt/gremlin-console/conf/ caminho dentro do contêiner.

   docker run -it --mount type=bind,source=.,target=/opt/gremlin-console/conf/ tinkerpop/gremlin-console:3.4
   

5. Dentro do contêiner do console 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 atravessar vértices e arestas

Agora que a consola está conectada à conta, use a sintaxe Gremlin padrão para criar e atravessar tanto vértices quanto arestas.

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

   	Value
   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 :> . O prefixo THis é necessário para executar o comando remotamente.

2. Adicione outro vértice de produto com estas propriedades:

   	Value
   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 aresta nomeada 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 dentro do gráfico.

   :> g.V().count()
   

5. Percorra o gráfico para encontrar 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 encontrar todos os vértices que Montau Turtle Surfboard substitui.

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

Limpeza de recursos

Quando você não precisar mais da API para a conta 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 para Apache Gremlin resolveu nosso problema oferecendo Gremlin como um serviço. Com esta oferta, você não é obrigado a criar suas próprias instâncias de servidor Gremlin ou gerenciar sua própria infraestrutura. Ainda mais, você pode dimensionar sua solução à medida que suas necessidades crescem ao longo do tempo.

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