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

Artigo
08/15/2024

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

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? Você pode experimentar o Azure Cosmos DB gratuitamente sem precisar de assinatura.
Python (mais recente)
- Não tem o Python 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:

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

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"

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

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

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

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.

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"

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"

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

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"

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.

Abra seu terminal em uma pasta vazia.
Abra o arquivo app.py.
```
touch app.py
```

Instalar o pacote PyPI

Adicionar o Pacote PyPI gremlinpython ao projeto Python.

Crie o arquivo requirements.txt.
```
touch requirements.txt
```
Adicione o pacote gremlinpython do Índice do Pacote Python ao arquivo de requisitos.
```
gremlinpython==3.7.0
```
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.

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>"
```
Valide se as variáveis de ambiente foram definidas corretamente.
```
printenv COSMOS_GREMLIN_ENDPOINT
printenv COSMOS_GREMLIN_KEY
```

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.

Abra o arquivo app.py.

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

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"]
```

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.

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

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

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.

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

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.

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

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.

Abra o terminal na pasta do projeto Python.
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.

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

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

Use az group delete para excluir o grupo de recursos.
```
az group delete \
    --name $resourceGroupName
```

Próxima etapa

Criar e consultar dados usando o Azure Cosmos DB for Apache Gremlin

Compartilhar via