Início Rápido: biblioteca de clientes do Azure Cosmos DB para Apache Gremlin para .NET

Comece a usar a biblioteca cliente para .NET do Azure Cosmos DB para Apache Gremlin para armazenar, gerenciar e consultar dados não estruturados. Siga as etapas neste guia para criar uma nova conta, instalar uma biblioteca de clientes do .NET, conectar-se à conta, executar operações comuns e consultar seus dados de exemplo finais.

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

Prerequisites

• Uma assinatura de Azure

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

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

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

• SDK do .NET 9.0 ou posterior

Configurando

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, obtendo suas credenciais e, em seguida, preparando seu ambiente de desenvolvimento.

Criar uma conta

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

Obter credenciais

Agora, obtenha a senha da biblioteca de clientes a ser usada para criar uma conexão com a conta criada recentemente.

Prepare o ambiente de desenvolvimento

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

1. Comece em uma pasta vazia.

2. Criar um novo aplicativo de console .NET

   dotnet new console
   

3. Importe o Gremlin.Net pacote do NuGet.

   dotnet add package Gremlin.Net
   

4. Construa o projeto.

   dotnet build
   

Modelo de objeto

Exemplos de código

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

Autenticar cliente

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

1. Abra o arquivo Program.cs no IDE (ambiente de desenvolvimento integrado).

2. Exclua qualquer conteúdo existente dentro do arquivo.

3. Adicione diretivas de uso para os seguintes namespaces:

   • Gremlin.Net.Driver
   • Gremlin.Net.Structure.IO.GraphSON

   using Gremlin.Net.Driver;
   using Gremlin.Net.Structure.IO.GraphSON;
   

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

   string hostname = "<host>";
   string primaryKey = "<key>";
   

5. Crie um GremlinServer usando as credenciais e as variáveis de configuração criadas nas etapas anteriores. Dê o nome server à variável.

   GremlinServer server = new(
       $"{hostname}.gremlin.cosmos.azure.com",
       443,
       enableSsl: true,
       username: "/dbs/cosmicworks/colls/products",
       password: primaryKey
   );
   

6. Agora, crie um GremlinClient usando a server variável e a GraphSON2MessageSerializer configuração.

   GremlinClient client = new(
       server,
       new GraphSON2MessageSerializer()
   );
   

Inserir dados

Em seguida, insira novos dados de vértice e borda no grafo. Antes de criar os novos dados, desmarque o grafo de todos os dados existentes.

1. Execute a g.V().drop() consulta para limpar todos os vértices e bordas do grafo.

   await client.SubmitAsync("g.V().drop()");
   

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

   string insertVertexQuery = """
       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.

   await client.SubmitAsync(insertVertexQuery, new Dictionary<string, object>
   {
       ["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
   });
   

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

   await client.SubmitAsync(insertVertexQuery, new Dictionary<string, object>
   {
       ["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
   });
   
   await client.SubmitAsync(insertVertexQuery, new Dictionary<string, object>
   {
       ["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
   });
   

5. Crie outra consulta Gremlin que adicione uma aresta.

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

6. Adicione duas bordas.

   await client.SubmitAsync(insertEdgeQuery, new Dictionary<string, object>
   {
       ["prop_partition_key"] = "gear-surf-surfboards",
       ["prop_source_id"] = "bbbbbbbb-1111-2222-3333-cccccccccccc",
       ["prop_target_id"] = "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb"
   });
   
   await client.SubmitAsync(insertEdgeQuery, new Dictionary<string, object>
   {
       ["prop_partition_key"] = "gear-surf-surfboards",
       ["prop_source_id"] = "bbbbbbbb-1111-2222-3333-cccccccccccc",
       ["prop_target_id"] = "cccccccc-2222-3333-4444-dddddddddddd"
   });
   

Ler dados

Em seguida, leia os dados que foram inseridos anteriormente no grafo.

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

   string readVertexQuery = "g.V([prop_partition_key, prop_id])";
   

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

   ResultSet<Dictionary<string, object>> readResults = await client.SubmitAsync<Dictionary<string, object>>(readVertexQuery, new Dictionary<string, object>
   {
       ["prop_partition_key"] = "gear-surf-surfboards",
       ["prop_id"] = "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb"
   });
   
   Dictionary<string, object> matchedItem = readResults.Single();
   

Consultar dados

Por fim, use uma consulta para localizar todos os dados que correspondem a uma passagem ou filtro específico no grafo.

1. Crie uma consulta que encontre todos os vértices que partem de um vértice específico.

   string findVerticesQuery = """
       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.

   ResultSet<Dictionary<string, object>> findResults = await client.SubmitAsync<Dictionary<string, object>>(findVerticesQuery, new Dictionary<string, object>
   {
       ["prop_partition_key"] = "gear-surf-surfboards",
       ["prop_name"] = "Montau Turtle Surfboard"
   });
   

3. Percorrer os resultados da consulta.

   foreach (Dictionary<string, object> result in findResults)
   {
       // Do something here with each result
   }
   

Executar o código

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

dotnet run

Limpar os recursos

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

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