Início Rápido: biblioteca do Azure Cosmos DB for Apache Gremlin para Python

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 maneira fácil de começar a usar o Gremlin com um serviço que pode crescer e escalar horizontalmente conforme sua necessidade, com gerenciamento mínimo.

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

Código-fonte da biblioteca | Pacote (PyPi)

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. Screenshot that shows an example of Try It for Azure Cloud Shell.
Acesse https://shell.azure.com ou selecione o botão Iniciar o Cloud Shell para abri-lo no navegador. Button to launch Azure Cloud Shell.
Selecione o botão Cloud Shell na barra de menus no canto superior direito do portal do Azure. Screenshot that shows the Cloud Shell button in the Azure portal

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.

Configurando

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

Crie uma conta de API para o Gremlin

A conta da API para Gremlin deve ser criada antes de utilizar a biblioteca Python. 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. Nomeie o grafo como products, depois 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
    

Crie um novo aplicativo de console do Python

Crie um aplicativo de console Python em uma pasta vazia utilizando o terminal de sua preferência.

  1. Abra seu terminal em uma pasta vazia.

  2. Abra o arquivo app.py.

    touch app.py
    

Instalar o pacote PyPI

Adicionar o Pacote PyPI gremlinpython ao projeto Python.

  1. Crie o arquivo requirements.txt.

    touch requirements.txt
    
  2. Adicione o pacote gremlinpython do Índice do Pacote Python ao arquivo de requisitos.

    gremlinpython==3.7.0
    
  3. Instale todos os requisitos para seu projeto.

    python install -r requirements.txt
    

Configurar variáveis de ambiente

Para utilizar os valores NOME e URI obtidos anteriormente neste início rápido: mantenha-os em novas variáveis de ambiente no computador local que está executando o aplicativo.

  1. Para definir a variável de ambiente, utilize seu terminal para manter os valores como COSMOS_ENDPOINT e COSMOS_KEY, respectivamente.

    export COSMOS_GREMLIN_ENDPOINT="<account-name>"
    export COSMOS_GREMLIN_KEY="<account-key>"
    
  2. Valide se as variáveis de ambiente foram definidas corretamente.

    printenv COSMOS_GREMLIN_ENDPOINT
    printenv COSMOS_GREMLIN_KEY
    

Exemplos de código

O código deste artigo conecta-se a um banco de dados denominado cosmicworks e a um gráfico denominado products. Em seguida, o código adiciona vértices e bordas ao gráfico antes de percorrer os itens adicionados.

Autenticar o cliente

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

  1. Abra o arquivo app.py.

  2. Importe client e serializer do módulo gremlin_python.driver.

    import os
    from gremlin_python.driver import client, serializer
    

    Aviso

    Dependendo da sua versão do Python, você também precisará importar asyncio e substituir a política de loop de eventos:

    import asyncio
    import sys
    
    if sys.platform == "win32":
        asyncio.set_event_loop_policy(asyncio.WindowsSelectorEventLoopPolicy())
    
  3. Crie as variáveis ACCOUNT_NAME e ACCOUNT_KEY. Armazene as variáveis de ambiente COSMOS_GREMLIN_ENDPOINT e COSMOS_GREMLIN_KEY como os valores de cada variável respectiva.

    ACCOUNT_NAME = os.environ["COSMOS_GREMLIN_ENDPOINT"]
    ACCOUNT_KEY = os.environ["COSMOS_GREMLIN_KEY"]
    
  4. Use Client para conectar-se usando as credenciais da conta e o serializador GraphSON 2.0.

    client = client.Client(
        url=f"wss://{ACCOUNT_NAME}.gremlin.cosmos.azure.com:443/",
        traversal_source="g",
        username="/dbs/cosmicworks/colls/products",
        password=f"{ACCOUNT_KEY}",
        message_serializer=serializer.GraphSONSerializersV2d0(),
    )
    

Criar vértices

Agora que o aplicativo está conectado à conta, use a sintaxe padrão do Gremlin para criar os vértices.

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

    Valor
    rótulo product
    id 68719518371
    name Kiama classic surfboard
    price 285.55
    category surfboards
    client.submit(
        message=(
            "g.addV('product')"
            ".property('id', prop_id)"
            ".property('name', prop_name)"
            ".property('price', prop_price)"
            ".property('category', prop_partition_key)"
        ),
        bindings={
            "prop_id": "68719518371",
            "prop_name": "Kiama classic surfboard",
            "prop_price": 285.55,
            "prop_partition_key": "surfboards",
        },
    )
    
  2. Crie um segundo vértice de produtos com essas propriedades:

    Valor
    rótulo product
    id 68719518403
    name Montau Turtle Surfboard
    price 600.00
    category surfboards
    client.submit(
        message=(
            "g.addV('product')"
            ".property('id', prop_id)"
            ".property('name', prop_name)"
            ".property('price', prop_price)"
            ".property('category', prop_partition_key)"
        ),
        bindings={
            "prop_id": "68719518403",
            "prop_name": "Montau Turtle Surfboard",
            "prop_price": 600.00,
            "prop_partition_key": "surfboards",
        },
    )
    
  3. Crie um terceiro vértice de produtos com essas propriedades:

    Valor
    rótulo product
    id 68719518409
    name Bondi Twin Surfboard
    price 585.50
    category surfboards
    client.submit(
        message=(
            "g.addV('product')"
            ".property('id', prop_id)"
            ".property('name', prop_name)"
            ".property('price', prop_price)"
            ".property('category', prop_partition_key)"
        ),
        bindings={
            "prop_id": "68719518409",
            "prop_name": "Bondi Twin Surfboard",
            "prop_price": 585.50,
            "prop_partition_key": "surfboards",
        },
    )
    

Criar bordas

Crie bordas utilizando a sintaxe do Gremlin para definir os relacionamentos entre os vértices.

  1. Crie uma borda de produto Montau Turtle Surfboard denominada substituições para o produto Kiama classic surfboard.

    client.submit(
        message=(
            "g.V([prop_partition_key, prop_source_id])"
            ".addE('replaces')"
            ".to(g.V([prop_partition_key, prop_target_id]))"
        ),
        bindings={
            "prop_partition_key": "surfboards",
            "prop_source_id": "68719518403",
            "prop_target_id": "68719518371",
        },
    )
    

    Dica

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

  2. Crie outra borda de substituições do mesmo produto para o Bondi Twin Surfboard.

    client.submit(
        message=(
            "g.V([prop_partition_key, prop_source_id])"
            ".addE('replaces')"
            ".to(g.V([prop_partition_key, prop_target_id]))"
        ),
        bindings={
            "prop_partition_key": "surfboards",
            "prop_source_id": "68719518403",
            "prop_target_id": "68719518409",
        },
    )
    

Bordas e vértices de consulta

Use a sintaxe do Gremlin para percorrer o grafo e descobrir os relacionamentos entre os vértices.

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

    result = client.submit(
        message=(
            "g.V().hasLabel('product')"
            ".has('category', prop_partition_key)"
            ".has('name', prop_name)"
            ".outE('replaces').inV()"
        ),
        bindings={
            "prop_partition_key": "surfboards",
            "prop_name": "Montau Turtle Surfboard",
        },
    )
    
  2. Grave no console o resultado dessa travessia.

    print(result)
    

Executar o código

Valide se seu aplicativo funciona conforme o esperado executando-o. O aplicativo deve ser executado sem erros ou avisos. A saída do aplicativo inclui dados sobre os itens criados e consultados.

  1. Abra o terminal na pasta do projeto Python.

  2. Use python <filename> para executar o aplicativo. Observe a saída do aplicativo.

    python app.py
    

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
    

Próxima etapa