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

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

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

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.

• .NET SDK 9.0 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.

Obter credenciais

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

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. 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 reunidas anteriormente neste guia.

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

2. Exclua qualquer conteúdo existente no arquivo.

3. Adicione usando diretivas 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 variáveis de configuração criadas nas etapas anteriores. Nomeie a variável server.

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

   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 arestas.

   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 gráfico.

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

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 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. Itere sobre 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

Clean up resources (Limpar recursos)

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

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