Inicio rápido: Biblioteca de Azure Cosmos DB for Apache Gremlin para .NET

Artículo
10/07/2023

SE APLICA A: Gremlin

Azure Cosmos DB for Apache Gremlin es un servicio de base de datos de grafos totalmente administrado que implementa el conocido Apache Tinkerpop, un marco informático de grafos mediante el lenguaje de consulta Gremlin. La API para Gremlin ofrece una forma sencilla de empezar a usar Gremlin con un servicio que puede aumentar y escalar horizontalmente tanto como necesite con una administración mínima.

En este inicio rápido, usará la biblioteca Gremlin.Net para conectarse a una cuenta de Azure Cosmos DB for Gremlin recién creada.

Código fuente de la biblioteca | Paquete (NuGet)

Requisitos previos

Una cuenta de Azure con una suscripción activa.
- ¿No tiene una suscripción de Azure? Regístrese para obtener una cuenta de Azure gratuita.
- ¿No quiere una suscripción de Azure? Puede probar Azure Cosmos DB gratis sin necesidad de suscripción.
.NET (LTS)
- ¿No tiene .NET instalado? Pruebe este inicio rápido en GitHub Codespaces.
Interfaz de la línea de comandos (CLI) de Azure

Azure Cloud Shell

En Azure se hospeda Azure Cloud Shell, un entorno de shell interactivo que puede utilizar mediante el explorador. Puede usar Bash o PowerShell con Cloud Shell para trabajar con los servicios de Azure. Puede usar los comandos preinstalados de Cloud Shell para ejecutar el código de este artículo sin tener que instalar nada en su entorno local.

Para iniciar Azure Cloud Shell:

Opción	Ejemplo o vínculo
Seleccione Pruébelo en la esquina superior derecha de un bloque de código o de comandos. Solo con seleccionar Pruébelo no se copia automáticamente el código o comando en Cloud Shell.
Vaya a https://shell.azure.com o seleccione el botón Iniciar Cloud Shell para abrir Cloud Shell en el explorador.
Seleccione el botón Cloud Shell en la barra de menús de la esquina superior derecha de Azure Portal.

Para usar Azure Cloud Shell:

Inicie Cloud Shell.
Seleccione el botón Copiar en un bloque de código (o bloque de comandos) para copiar el código o comando.
Pegue el código o comando en la sesión de Cloud Shell. Para ello, seleccione Ctrl+Mayús+V en Windows y Linux, o bien seleccione Cmd+Mayús+V en macOS.
Seleccione Intro para ejecutar el código o comando.

Instalación

En esta sección se explica cómo crear una cuenta de API para Gremlin y configurar un proyecto de .NET para usar la biblioteca para conectarse a la cuenta.

Creación de una API para una cuenta de Gremlin

La API para la cuenta de Gremlin debe crearse antes de usar la biblioteca de .NET. Además, ayuda a tener la base de datos y el grafo en su lugar.

Cree variables de shell para accountName, resourceGroupName y 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"

Si aún no lo ha hecho, inicie sesión en la CLI de Azure con az login.

Use az group create para crear un nuevo grupo de recursos en la suscripción.

az group create \
    --name $resourceGroupName \
    --location $location

Use az cosmosdb create para crear una nueva cuenta de API para Gremlin con la configuración predeterminada.
```
az cosmosdb create \
    --resource-group $resourceGroupName \
    --name $accountName \
    --capabilities "EnableGremlin" \
    --locations regionName=$location \
    --enable-free-tier true
```
Nota:

Puede tener una cuenta de Azure Cosmos DB de nivel Gratis por cada suscripción de Azure y debe optar por tenerla al crear la cuenta. Si este comando no consigue aplicar el descuento por nivel gratuito, significa que el nivel Gratis ya se habilitó en otra cuenta de la suscripción.

Obtenga la API para el punto de conexión de Gremlin NAME para la cuenta con az cosmosdb show.

az cosmosdb show \
    --resource-group $resourceGroupName \
    --name $accountName \
    --query "name"

Busque KEY en la lista de claves de la cuenta con az-cosmosdb-keys-list.

az cosmosdb keys list \
    --resource-group $resourceGroupName \
    --name $accountName \
    --type "keys" \
    --query "primaryMasterKey"

Registre los valores NAME y KEY. Necesitará estas credenciales más adelante.

Cree una base de datos denominada cosmicworks con az cosmosdb gremlin database create.

az cosmosdb gremlin database create \
    --resource-group $resourceGroupName \
    --account-name $accountName \
    --name "cosmicworks"

Cree un grafo mediante az cosmosdb gremlin graph create. Asigne un nombre al grafo products, establezca el rendimiento en 400 y, por último, establezca la ruta de acceso de la clave de partición en /category.

az cosmosdb gremlin graph create \
    --resource-group $resourceGroupName \
    --account-name $accountName \
    --database-name "cosmicworks" \
    --name "products" \
    --partition-key-path "/category" \
    --throughput 400

Creación de una aplicación de consola de .NET

Cree una aplicación de consola de .NET en una carpeta vacía con su terminal preferido.

Abra el terminal en una carpeta vacía.
Use el comando dotnet new que especifica la plantilla console.
```
dotnet new console
```

Instalación del paquete NuGet.

Agregue los paquetes NuGet Gremlin.NET al proyecto de .NET.

Use el comando dotnet add package especificando el nombre del paquete de NuGetGremlin.Net.
```
dotnet add package Gremlin.Net
```

Compile el proyecto de .NET mediante dotnet build.

dotnet build

Asegúrese de que la compilación se realizó correctamente sin errores. El resultado esperado de la compilación debe parecerse a lo siguiente:

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)

Configuración de las variables de entorno

Para usar los valores NAME y URI obtenidos anteriormente en este inicio rápido, consérvelos en nuevas variables de entorno del equipo local que ejecuta la aplicación.

Para establecer la variable de entorno, use el terminal para conservar los valores como COSMOS_ENDPOINT y COSMOS_KEY, respectivamente.
```
export COSMOS_GREMLIN_ENDPOINT="<account-name>"
export COSMOS_GREMLIN_KEY="<account-key>"
```
Compruebe que las variables de entorno se hayan establecido correctamente.
```
printenv COSMOS_GREMLIN_ENDPOINT
printenv COSMOS_GREMLIN_KEY
```

El código de este artículo se conecta a una base de datos denominada cosmicworks y a un grafo denominado products. A continuación, el código agrega vértices y bordes al gráfico antes de atravesar los elementos agregados.

Autenticar el cliente

Deben autorizarse las solicitudes de aplicación a la mayor parte de servicios de Azure. En el caso de la API para Gremlin, use los valores NAME y URI obtenidos anteriormente en este inicio rápido.

Abra el archivo Program.cs.
Elimine cualquier contenido existente dentro del archivo.
Agregue un bloque using para el espacio de nombres Gremlin.Net.Driver.
```
using Gremlin.Net.Driver;
```
Crear variables de cadena accountName y accountKey. Almacene las variables de entorno COSMOS_GREMLIN_ENDPOINT y COSMOS_GREMLIN_KEY como los valores de cada variable respectiva.
```
string accountName = Environment.GetEnvironmentVariable("COSMOS_GREMLIN_ENDPOINT")!;
string accountKey = Environment.GetEnvironmentVariable("COSMOS_GREMLIN_KEY")!;
```

Cree una nueva instancia de GremlinServer con las credenciales del emulador.

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

Cree una nueva instancia de GremlinClient para conectarse mediante las credenciales del servidor remoto y el serializador GraphSON 2.0.

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

Creación de vértices

Ahora que la aplicación está conectada a la cuenta, use la sintaxis estándar de Gremlin para crear vértices.

Use SubmitAsync para ejecutar un servidor de comandos en la cuenta de la API para Gremlin. Cree un vértice de producto con las siguientes propiedades:

Valor

label 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')"
);
```

Cree un segundo vértice de producto con estas propiedades:

	Valor
label	`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')"
);

Cree un tercer vértice de producto con estas propiedades:

	Valor
label	`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')"
);

Creación de bordes

Cree bordes mediante la sintaxis de Gremlin para definir relaciones entre vértices.

Cree un perímetro desde el producto Montau Turtle Surfboard denominado replaces hasta el producto Kiama classic surfboard.
```
await client.SubmitAsync(
    requestScript: "g.V(['surfboards', '68719518403']).addE('replaces').to(g.V(['surfboards', '68719518371']))"
);
```
Sugerencia

Esta definición de borde usa la sintaxis g.V(['<partition-key>', '<id>']). Como alternativa, puede usar g.V('<id>').has('category', '<partition-key>').

Crear otro reemplaza el borde desde el mismo producto hasta Bondi Twin Surfboard.

await client.SubmitAsync(
    requestScript: "g.V(['surfboards', '68719518403']).addE('replaces').to(g.V(['surfboards', '68719518409']))"
);

Consulta de vértices y bordes

Use la sintaxis de Gremlin para recorrer el grafo y detectar relaciones entre vértices.

Recorra el grafo y busque todos los vértices que Montau Turtle Surfboard reemplaza.

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

Escriba en la consola la cadena estática [CREATED PRODUCT]\t68719518403. A continuación, recorra en iteración cada vértice coincidente mediante un bucleforeach y escriba en la consola un mensaje que comience por [REPLACES PRODUCT] e incluya el campo de producto coincidente idcomo sufijo.
```
Console.WriteLine($"[CREATED PRODUCT]\t68719518403");
foreach (var result in results ?? Enumerable.Empty<Dictionary<string, object>>())
{
    Console.WriteLine($"[REPLACES PRODUCT]\t{result["id"]}");
}
```

Ejecución del código

Compruebe que la aplicación funcione según lo previsto mediante la ejecución de la aplicación. La aplicación debe ejecutarse sin errores ni advertencias. La salida de la aplicación incluye datos sobre los elementos creados y consultados.

Abra el terminal en la carpeta del proyecto de .NET.
Use dotnet run para ejecutar la aplicación.
```
dotnet run
```

Observe la salida de la aplicación.

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

Limpieza de recursos

Cuando ya no necesite la cuenta de la API para Gremlin, podrá eliminar el grupo de recursos correspondiente.

Cree una variable de shell para resourceGroupName si aún no existe.

# Variable for resource group name
resourceGroupName="msdocs-cosmos-gremlin-quickstart"

Use az group delete para eliminar el grupo de recursos.
```
az group delete \
    --name $resourceGroupName
```

Paso siguiente

Creación y consulta de datos mediante Azure Cosmos DB for Apache Gremlin

	Valor
label	`product`
id	`68719518371`
`name`	`Kiama classic surfboard`
`price`	`285.55`
`category`	`surfboards`