Guia de início rápido: biblioteca do Azure Cosmos DB para Apache Gremlin para Python

APLICA-SE A: 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 a gremlinpython biblioteca para se conectar a uma conta recém-criada do Azure Cosmos DB para Gremlin.

Pacote de código-fonte | da biblioteca (PyPi)

Pré-requisitos

Azure Cloud Shell

O Azure aloja o Azure Cloud Shell, um ambiente de shell interativo que pode utilizar através do seu browser. Pode utilizar 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:

Opção 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. Screenshot that shows an example of Try It for Azure Cloud Shell.
Aceda a https://shell.azure.com ou selecione o botão Iniciar Cloud Shell para abrir o Cloud Shell no browser. Button to launch Azure Cloud Shell.
Selecione o botão Cloud Shell na barra de menus, na parte direita 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 comando.

  3. Cole o código ou comando na sessão do Cloud Shell selecionando Ctrl+Shift+V no Windows e Linux ou selecionando Cmd+Shift+V no macOS.

  4. Selecione Enter para executar o código ou comando.

Configuração

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

Criar uma API para a conta Gremlin

A API para a conta Gremlin deve ser criada antes de usar a biblioteca Python. 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, entre na CLI do Azure usando az logino .

  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
    

    Nota

    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 para o ponto de extremidade Gremlin NAME para a conta usando az cosmosdb showo .

    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 NAME e KEY . Você usa 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 gráfico usando az cosmosdb gremlin graph createo . 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
    

Criar um novo aplicativo de console Python

Crie um aplicativo de console Python em uma pasta vazia usando seu terminal preferido.

  1. Abra o terminal numa pasta vazia.

  2. Crie o arquivo app.py .

    touch app.py
    

Instalar o pacote PyPI

Adicione o gremlinpython pacote PyPI ao projeto Python.

  1. Crie o arquivo requirements.txt .

    touch requirements.txt
    
  2. Adicione o gremlinpython pacote do Python Package Index ao arquivo de requisitos.

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

    python install -r requirements.txt
    

Configurar variáveis de ambiente

Para usar os valores NAME e URI obtidos anteriormente neste início rápido, persista-os para novas variáveis de ambiente na máquina local que executa o aplicativo.

  1. Para definir a variável de ambiente, use seu terminal para persistir 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 neste artigo se conecta a um banco de dados chamado cosmicworks e a um gráfico chamado products. Em seguida, o código adiciona vértices e arestas ao gráfico antes de percorrer os itens adicionados.

Autenticar o cliente

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

  1. Abra o arquivo app.py .

  2. Importação client e serializer do gremlin_python.driver módulo.

    import os
    from gremlin_python.driver import client, serializer
    

    Aviso

    Dependendo da sua versão do Python, você também pode 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. Criar ACCOUNT_NAME e ACCOUNT_KEY variáveis. Armazene as variáveis e COSMOS_GREMLIN_KEY de COSMOS_GREMLIN_ENDPOINT ambiente como os valores para cada variável respetiva.

    ACCOUNT_NAME = os.environ["COSMOS_GREMLIN_ENDPOINT"]
    ACCOUNT_KEY = os.environ["COSMOS_GREMLIN_KEY"]
    
  4. Use Client para se conectar 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 Gremlin padrão para criar vértices.

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

    Value
    etiqueta 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 produto com estas propriedades:

    Value
    etiqueta 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 produto com estas propriedades:

    Value
    etiqueta 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 arestas

Crie arestas usando a sintaxe Gremlin para definir relações entre vértices.

  1. Crie uma borda do Montau Turtle Surfboard produto chamado substitui para o Kiama classic surfboard produto.

    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",
        },
    )
    

    Gorjeta

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

  2. Criar outro substitui a borda 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",
        },
    )
    

Consultar vértices & arestas

Use a sintaxe de Gremlin para atravessar o gráfico e descobrir relações entre vértices.

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

    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. Escreva no console o resultado dessa travessia.

    print(result)
    

Executar o código

Valide se seu aplicativo funciona conforme o esperado executando o aplicativo. 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
    

Clean up resources (Limpar 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
    

Próximo passo