Início rápido: biblioteca cliente Azure Cosmos DB para Apache Gremlin em Python

• Python
• Node.js
• C#

Importante

Você está procurando uma solução de banco de dados para cenários de alta escala com um contrato de nível de serviço (SLA) de disponibilidade de 99.999%, dimensionamento automático instantâneo e failover automático em várias regiões? Considere Azure Cosmos DB para NoSQL.

Você está procurando implementar um gráfico de processamento analítico on-line (OLAP) ou migrar um aplicativo Apache Gremlin existente? Considere o gráfico no Microsoft Fabric.

Introduza-se à biblioteca cliente Azure Cosmos DB para Apache Gremlin em Python, destinada a armazenar, gerir e consultar dados não estruturados. Siga as etapas neste guia para criar uma nova conta, instalar uma biblioteca de cliente Python, conectar-se à conta, executar operações comuns e consultar seus dados de exemplo finais.

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

Pré-requisitos

• Uma assinatura do Azure

  • Se não tiver uma subscrição do Azure, crie uma conta gratuita antes de começar.

• A versão mais recente da CLI do Azure no Azure Cloud Shell.

  • Se preferir executar comandos de referência da CLI localmente, entre na CLI do Azure usando o az login comando.

• Python 3.12 ou posterior

Configuração

Primeiro, configure a conta e o ambiente de desenvolvimento para este guia. Esta seção orienta você pelo processo de criação de uma conta, obtenção de suas credenciais e, em seguida, preparação do ambiente de desenvolvimento.

Criar uma conta

Comece criando uma API para a conta Apache Gremlin. Depois que a conta for criada, crie o banco de dados e os recursos gráficos.

CLI do Azure

1. Se você ainda não tiver um grupo de recursos de destino, use o az group create comando para criar um novo grupo de recursos em sua assinatura.

   az group create \
       --name "<resource-group-name>" \
       --location "<location>"
   

2. Use o az cosmosdb create comando para criar uma nova conta do Azure Cosmos DB para Apache Gremlin com configurações padrão.

   az cosmosdb create \
       --resource-group "<resource-group-name>" \
       --name "<account-name>" \
       --locations "regionName=<location>" \
       --capabilities "EnableGremlin"
   

3. Crie um novo banco de dados usando az cosmosdb gremlin database create o nome cosmicworks.

   az cosmosdb gremlin database create \
       --resource-group "<resource-group-name>" \
       --account-name "<account-name>" \
       --name "cosmicworks"
   

4. Use o az cosmosdb gremlin graph create comando para criar um novo gráfico chamado products.

   az cosmosdb gremlin graph create \
       --resource-group "<resource-group-name>" \
       --account-name "<account-name>" \
       --database-name "cosmicworks" \
       --name "products" \
       --partition-key-path "/category"
   

portal do Azure

1. Entre no portal do Azure (https://portal.azure.com).

2. Insira Azure Cosmos DB na barra de pesquisa global.

3. Em Serviços, selecione Azure Cosmos DB.

4. No painel Azure Cosmos DB , selecione Criar e, em seguida, Azure Cosmos DB para Apache Gremlin na guia Outros .

5. No painel Noções básicas, configure as seguintes opções e selecione Revisar + criar:

   	Value
   Tipo de carga de trabalho	Aprendizagem
   Subscrição	Selecione sua assinatura do Azure
   Grupo de Recursos	Criar um novo grupo de recursos ou selecionar um grupo de recursos existente
   Nome da Conta	Forneça um nome globalmente exclusivo
   Zonas de Disponibilidade	Desativar
   Localização	Selecione uma região do Azure suportada para a sua subscrição

   Gorjeta

   Você pode deixar quaisquer opções não especificadas para seus valores padrão. Você também pode configurar a conta para limitar a taxa de transferência total da conta a 1.000 unidades de solicitação por segundo (RU/s) ou habilitar o nível gratuito para minimizar seus custos.

6. No painel Rever + criar, aguarde até que a validação da sua conta conclua com sucesso e, em seguida, selecione Criar.

7. O Portal navega automaticamente para o painel Implantação. Aguarde até que a implementação seja concluída.

8. Quando a implantação estiver concluída, selecione Ir para o recurso para navegar até a nova API para a conta Apache Gremlin.

9. No menu de recursos, selecione a opção Data Explorer .

10. No Data Explorer, selecione + Novo Gráfico.

11. Na caixa de diálogo Adicionar gráfico, configure as seguintes opções e selecione OK:

    	Value
    Base de dados	Criar novo
    Nome da base de dados	cosmicworks
    Nome do gráfico	products
    Chave de partição	/category

    Gorjeta

    Você pode deixar quaisquer opções não especificadas para seus valores padrão.

Obter credenciais

Agora, obtenha a senha para a biblioteca do cliente usar para criar uma conexão com a conta criada recentemente.

CLI do Azure

1. Use az cosmosdb show para obter o host para a conta.

   az cosmosdb show \
       --resource-group "<resource-group-name>" \
       --name "<account-name>" \
       --query "{host:name}"
   

2. Registe o valor da propriedade host proveniente da saída dos comandos anteriores. O valor desta propriedade é o host que você usa posteriormente neste guia para se conectar à conta com a biblioteca.

3. Use az cosmosdb keys list para obter as chaves da conta.

   az cosmosdb keys list \
       --resource-group "<resource-group-name>" \
       --name "<account-name>" \
       --type "keys"
   

4. Registe o valor da propriedade primaryMasterKey proveniente da saída dos comandos anteriores. O valor dessa propriedade é a chave que você usa posteriormente neste guia para se conectar à conta com a biblioteca.

portal do Azure

1. No menu de recursos da conta, selecione a opção Visão geral .

2. Registre o valor do nome da conta. O valor dessa propriedade é o host que você usa posteriormente neste guia para se conectar à conta com a biblioteca.

3. No menu de recursos da conta novamente, selecione a opção Cadeias de conexão na seção Configurações .

4. Exponha e registre o valor do campo CHAVE PRIMÁRIA nesta página. O valor dessa propriedade é a chave que você usa posteriormente neste guia para se conectar à conta com a biblioteca.

Preparar o ambiente de desenvolvimento

Em seguida, configure seu ambiente de desenvolvimento com um novo projeto e a biblioteca do cliente. Esta etapa é o último pré-requisito necessário antes de passar para o resto deste guia.

1. Comece em uma pasta vazia.

2. Importe o gremlinpython pacote do Python Package Index (PyPI).

   pip install gremlinpython
   

3. Crie o arquivo app.py .

Modelo de objeto

	Descrição
GremlinClient	Representa o cliente usado para se conectar e interagir com o servidor Gremlin
GraphTraversalSource	Utilizado para criar e executar percursos em Gremlin

Exemplos de código

• Autenticar cliente
• Inserir dados
• Ler dados
• Consultar dados

Autenticar cliente

Comece autenticando o cliente usando as credenciais reunidas anteriormente neste guia.

1. Abra o arquivo app.py em seu ambiente de desenvolvimento integrado (IDE).

2. Importe os seguintes tipos da gremlin_python.driver biblioteca:

   • gremlin_python.driver.client
   • gremlin_python.driver.serializer

   from gremlin_python.driver import client, serializer
   

3. Crie variáveis de cadeia de caracteres para as credenciais coletadas anteriormente neste guia. Nomeie as variáveis hostname e primary_key.

   hostname = "<host>"
   primary_key = "<key>"
   

4. Crie um Client objeto usando as credenciais e variáveis de configuração criadas nas etapas anteriores. Nomeie a variável client.

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

Inserir dados

Em seguida, insira novos dados de vértice e borda no gráfico. Antes de criar os novos dados, limpe o gráfico de todos os dados existentes.

1. Execute a g.V().drop() consulta para limpar todos os vértices e arestas do gráfico.

   client.submit("g.V().drop()").all().result()
   

2. Crie uma consulta Gremlin que adicione um vértice.

   insert_vertex_query = (
       "g.addV('product')"
       ".property('id', prop_id)"
       ".property('name', prop_name)"
       ".property('category', prop_category)"
       ".property('quantity', prop_quantity)"
       ".property('price', prop_price)"
       ".property('clearance', prop_clearance)"
   )
   

3. Adicione um vértice para um único produto.

   client.submit(
       message=insert_vertex_query,
       bindings={
           "prop_id": "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb",
           "prop_name": "Yamba Surfboard",
           "prop_category": "gear-surf-surfboards",
           "prop_quantity": 12,
           "prop_price": 850.00,
           "prop_clearance": False,
       },
   ).all().result()
   

4. Adicione mais dois vértices para dois produtos extras.

   client.submit(
       message=insert_vertex_query,
       bindings={
           "prop_id": "bbbbbbbb-1111-2222-3333-cccccccccccc",
           "prop_name": "Montau Turtle Surfboard",
           "prop_category": "gear-surf-surfboards",
           "prop_quantity": 5,
           "prop_price": 600.00,
           "prop_clearance": True,
       },
   ).all().result()
   
   client.submit(
       message=insert_vertex_query,
       bindings={
           "prop_id": "cccccccc-2222-3333-4444-dddddddddddd",
           "prop_name": "Noosa Surfboard",
           "prop_category": "gear-surf-surfboards",
           "prop_quantity": 31,
           "prop_price": 1100.00,
           "prop_clearance": False,
       },
   ).all().result()
   

5. Crie outra consulta Gremlin que adicione uma aresta.

   insert_edge_query = (
       "g.V([prop_partition_key, prop_source_id])"
       ".addE('replaces')"
       ".to(g.V([prop_partition_key, prop_target_id]))"
   )
   

6. Adicione duas arestas.

   client.submit(
       message=insert_edge_query,
       bindings={
           "prop_partition_key": "gear-surf-surfboards",
           "prop_source_id": "bbbbbbbb-1111-2222-3333-cccccccccccc",
           "prop_target_id": "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb",
       },
   ).all().result()
   
   client.submit(
       message=insert_edge_query,
       bindings={
           "prop_partition_key": "gear-surf-surfboards",
           "prop_source_id": "bbbbbbbb-1111-2222-3333-cccccccccccc",
           "prop_target_id": "cccccccc-2222-3333-4444-dddddddddddd",
       },
   ).all().result()
   

Ler dados

Em seguida, leia os dados que foram inseridos anteriormente no gráfico.

1. Crie uma consulta que leia um vértice usando o identificador exclusivo e o valor da chave de partição.

   read_vertex_query = "g.V([prop_partition_key, prop_id])"
   

2. Em seguida, leia um vértice fornecendo os parâmetros necessários.

   matched_item = client.submit(
       message=read_vertex_query,
       bindings={
           "prop_partition_key": "gear-surf-surfboards",
           "prop_id": "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb"
       }
   ).one()
   

Consultar dados

Finalmente, use uma consulta para localizar todos os dados que correspondem a uma travessia ou filtro específico no gráfico.

1. Crie uma consulta que encontre todos os vértices que se estendem a partir de um vértice específico.

   find_vertices_query = (
       "g.V().hasLabel('product')"
       ".has('category', prop_partition_key)"
       ".has('name', prop_name)"
       ".outE('replaces').inV()"
   )
   

2. Execute a consulta especificando o Montau Turtle Surfboard produto.

   find_results = client.submit(
       message=find_vertices_query,
       bindings={
           "prop_partition_key": "gear-surf-surfboards",
           "prop_name": "Montau Turtle Surfboard",
       },
   ).all().result()
   

3. Percorra os resultados da consulta.

   for result in find_results:
       # Do something here with each result
   

Executar o código

Execute o aplicativo recém-criado usando um terminal no diretório do aplicativo.

python app.py

Clean up resources (Limpar recursos)

Quando você não precisar mais da conta, remova a conta da sua assinatura do Azure excluindo o recurso.

CLI do Azure

az cosmosdb delete \
    --resource-group "<resource-group-name>" \
    --name "<account-name>"

portal do Azure

1. Navegue até o recurso existente do Azure Cosmos DB para Apache Gremlin que você criou anteriormente neste guia.

2. Na página do recurso, selecione Excluir na barra de menus.

3. Siga as instruções na caixa de diálogo de confirmação.