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

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

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

Pré-requisitos

• Uma conta do Azure com uma subscrição ativa.
  • Não há assinatura do Azure? Inscreva-se para obter uma conta gratuita do Azure.
  • Não quer uma assinatura do Azure? Você pode experimentar o Azure Cosmos DB gratuitamente sem a necessidade de assinatura.
• .NET (LTS)
  • Não tem o .NET instalado? Experimente este início rápido no GitHub Codespaces.
• Interface de Linha de Comandos do Azure (CLI)

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.
Aceda a https://shell.azure.com ou selecione o botão Iniciar Cloud Shell para abrir o Cloud Shell no browser.
Selecione o botão Cloud Shell na barra de menus, na parte direita do portal do Azure.

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

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

1. Abra o terminal numa pasta vazia.

2. Use o dotnet new comando especificando o modelo de console .

   dotnet new console
   

Instalar o pacote NuGet

Adicione o Gremlin.NET pacote NuGet ao projeto .NET.

1. Use o dotnet add package comando especificando o Gremlin.Net pacote NuGet.

   dotnet add package Gremlin.Net
   

2. Crie o projeto .NET usando dotnet buildo .

   dotnet build
   

   Certifique-se de que a compilação foi bem-sucedida sem erros. A saída esperada da compilação deve ser algo como isto:

   Determining projects to restore...
     All projects are up-to-date for restore.
     dslkajfjlksd -> \dslkajfjlksd\bin\Debug\net6.0\dslkajfjlksd.dll
   
   Build succeeded.
       0 Warning(s)
       0 Error(s)
   

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

• Autenticar o cliente
• Criar vértices
• Criar arestas
• Consultar vértices & arestas

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

2. Exclua qualquer conteúdo existente no arquivo.

3. Adicione um bloco using para o Gremlin.Net.Driver namespace.

   using Gremlin.Net.Driver;
   

4. Criar accountName e accountKey string variáveis. Armazene as variáveis e COSMOS_GREMLIN_KEY de COSMOS_GREMLIN_ENDPOINT ambiente como os valores para cada variável respetiva.

   string accountName = Environment.GetEnvironmentVariable("COSMOS_GREMLIN_ENDPOINT")!;
   string accountKey = Environment.GetEnvironmentVariable("COSMOS_GREMLIN_KEY")!;
   

5. Crie uma nova instância de uso das credenciais da GremlinServer conta.

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

6. Crie uma nova instância usando as credenciais do GremlinClient servidor remoto e o serializador GraphSON 2.0 .

   using var client = new GremlinClient(
       gremlinServer: server,
       messageSerializer: new Gremlin.Net.Structure.IO.GraphSON.GraphSON2MessageSerializer()
   );
   

Criar vértices

Agora que o aplicativo está conectado à conta, use a sintaxe Gremlin padrão para criar vértices.

1. Use SubmitAsync 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

   await client.SubmitAsync(
       requestScript: "g.addV('product').property('id', '68719518371').property('name', 'Kiama classic surfboard').property('price', 285.55).property('category', '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

   await client.SubmitAsync(
       requestScript: "g.addV('product').property('id', '68719518403').property('name', 'Montau Turtle Surfboard').property('price', 600.00).property('category', '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

   await client.SubmitAsync(
       requestScript: "g.addV('product').property('id', '68719518409').property('name', 'Bondi Twin Surfboard').property('price', 585.50).property('category', '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.

   await client.SubmitAsync(
       requestScript: "g.V(['surfboards', '68719518403']).addE('replaces').to(g.V(['surfboards', '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.

   await client.SubmitAsync(
       requestScript: "g.V(['surfboards', '68719518403']).addE('replaces').to(g.V(['surfboards', '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.

   var results = await client.SubmitAsync<Dictionary<string, object>>(
       requestScript: "g.V().hasLabel('product').has('category', 'surfboards').has('name', 'Montau Turtle Surfboard').outE('replaces').inV()"
   );
   

2. Escreva no console a cadeia de caracteres [CREATED PRODUCT]\t68719518403estática . Em seguida, itere sobre cada vértice correspondente usando um foreach loop e escreva no console uma mensagem que começa com [REPLACES PRODUCT] e inclui o campo de produto id correspondente como um sufixo.

   Console.WriteLine($"[CREATED PRODUCT]\t68719518403");
   foreach (var result in results ?? Enumerable.Empty<Dictionary<string, object>>())
   {
       Console.WriteLine($"[REPLACES PRODUCT]\t{result["id"]}");
   }
   

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

2. Use dotnet run para executar o aplicativo.

   dotnet run
   

3. Observe a saída do aplicativo.

   [CREATED PRODUCT]       68719518403
   [REPLACES PRODUCT]      68719518371
   [REPLACES PRODUCT]      68719518409
   

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