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

Artigo
10/26/2023

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

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

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.
.NET (LTS)
- Não tem o .NET 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 da API para Gremlin e na configuração de um projeto .NET 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 .NET. 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

Criar um aplicativo de console .NET

Crie um aplicativo de console .NET em uma pasta vazia utilizando o terminal de sua preferência.

Abra seu terminal em uma pasta vazia.
Use o dotnet new comando que especifica o modelo de console .
```
dotnet new console
```

Instalar o pacote NuGet

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

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

Crie o projeto .NET utilizando dotnet build.

dotnet build

Verifique se o build foi bem-sucedido sem erros. A saída esperada da compilação deve ser algo como:

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 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 Program.cs.
Exclua qualquer conteúdo existente dentro do arquivo.
Adicionar um bloco using para o namespace Gremlin.Net.Driver.
```
using Gremlin.Net.Driver;
```
Crie as variáveis de cadeia de caracteres accountName e accountKey. Armazene as variáveis de ambiente COSMOS_GREMLIN_ENDPOINT e COSMOS_GREMLIN_KEY como os valores de cada variável respectiva.
```
string accountName = Environment.GetEnvironmentVariable("COSMOS_GREMLIN_ENDPOINT")!;
string accountKey = Environment.GetEnvironmentVariable("COSMOS_GREMLIN_KEY")!;
```

Crie uma nova instância de GremlinServer utilizando as credenciais da conta.

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

Crie uma nova instância de GremlinClient usando as credenciais do 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 padrão do Gremlin para criar os vértices.

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

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

await client.SubmitAsync(
    requestScript: "g.addV('product').property('id', '68719518409').property('name', 'Bondi Twin Surfboard').property('price', 585.50).property('category', '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.
```
await client.SubmitAsync(
    requestScript: "g.V(['surfboards', '68719518403']).addE('replaces').to(g.V(['surfboards', '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.

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

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

Gravar no console a cadeia de caracteres estática [CREATED PRODUCT]\t68719518403. Em seguida, itere sobre cada vértice correspondente usando um loop foreach e grave no console uma mensagem que comece com [REPLACES PRODUCT] e inclua o campo do produto correspondente id como 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. 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 .NET.
Use dotnet run para executar o aplicativo.
```
dotnet run
```

Observe a saída do aplicativo.

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

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