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

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

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. Captura de tela que mostra um exemplo de Experimente para o Azure Cloud Shell.
Acesse https://shell.azure.com ou selecione o botão Iniciar o Cloud Shell para abri-lo no navegador. Botão para iniciar o Azure Cloud Shell.
Selecione o botão Cloud Shell na barra de menus no canto superior direito do portal do Azure. Captura de tela que mostra o botão Cloud Shell no 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