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

Introducción a la biblioteca cliente de Azure Cosmos DB para Apache Gremlin para .NET para almacenar, administrar y consultar datos no estructurados. Siga los pasos de esta guía para crear una cuenta, instalar una biblioteca cliente de .NET, conectarse a la cuenta, realizar operaciones comunes y consultar los datos finales de ejemplo.

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

Requisitos previos

• Una suscripción de Azure

  • Si no tiene una suscripción a Azure, cree una cuenta gratuita antes de empezar.

• La versión más reciente de Azure CLI en Azure Cloud Shell.

  • Si prefiere ejecutar comandos de referencia de la CLI localmente, inicie sesión en la CLI de Azure mediante el az login comando .

• SDK de .NET 9.0 o posterior

Instalación

Primero, configure la cuenta y el entorno de desarrollo para esta guía. En esta sección se explica el proceso de creación de una cuenta, la obtención de sus credenciales y la preparación del entorno de desarrollo.

Crear una cuenta

Empiece por crear una API para una cuenta de Apache Gremlin. Una vez creada la cuenta, cree la base de datos y los recursos del grafo.

Obtener credenciales

Ahora, obtenga la contraseña de la biblioteca cliente que se usará para crear una conexión a la cuenta creada recientemente.

Preparación del entorno de desarrollo

A continuación, configure el entorno de desarrollo con un nuevo proyecto y la biblioteca cliente. Este paso es el último requisito previo necesario antes de pasar al resto de esta guía.

1. Inicie en una carpeta vacía.

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

   dotnet new console
   

3. Importe el Gremlin.Net paquete desde NuGet.

   dotnet add package Gremlin.Net
   

4. Compile el proyecto.

   dotnet build
   

Modelo de objetos

Ejemplos de código

• Autenticar cliente
• Inserción de datos
• Leer datos
• Consultar datos

Autenticar cliente

Empiece por autenticar al cliente con las credenciales recopiladas anteriormente en esta guía.

1. Abra el archivo Program.cs en el entorno de desarrollo integrado (IDE).

2. Elimine cualquier contenido existente dentro del archivo.

3. Agregue directivas de uso para los siguientes espacios de nombres:

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

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

4. Cree variables de cadena para las credenciales recopiladas anteriormente en esta guía. Asigne un nombre a las variables hostname y primaryKey.

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

5. Cree un GremlinServer con las credenciales y las variables de configuración creadas en los pasos anteriores. Asigne un nombre a la variable server.

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

6. Ahora, cree un GremlinClient mediante la server variable y la GraphSON2MessageSerializer configuración.

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

Insertar datos

A continuación, inserte nuevos datos de vértices y bordes en el gráfico. Antes de crear los nuevos datos, borre el gráfico de los datos existentes.

1. Ejecute la g.V().drop() consulta para borrar todos los vértices y bordes del grafo.

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

2. Cree una consulta de Gremlin que agregue un 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. Agregue un vértice para un único producto.

   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. Agregue dos vértices más para dos productos adicionales.

   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. Cree otra consulta de Gremlin que agregue un borde.

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

6. Agregue dos bordes.

   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"
   });
   

Leer datos

A continuación, lea los datos que se insertaron anteriormente en el gráfico.

1. Cree una consulta que lea un vértice usando el identificador único y el valor de clave de partición.

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

2. A continuación, lea un vértice proporcionando los parámetros necesarios.

   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 datos

Por último, use una consulta para buscar todos los datos que coincidan con un recorrido o filtro específicos en el gráfico.

1. Cree una consulta que encuentre todos los vértices que parten desde un vértice específico.

   string findVerticesQuery = """
       g.V().hasLabel('product')
           .has('category', prop_partition_key)
           .has('name', prop_name)
           .outE('replaces').inV()
   """;
   

2. Ejecute la consulta que especifica el Montau Turtle Surfboard producto.

   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. Recorre en iteración los resultados de la consulta.

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

Ejecución del código

Ejecute la aplicación recién creada mediante un terminal en el directorio de la aplicación.

dotnet run

Limpieza de recursos

Cuando ya no necesite la cuenta, quite la cuenta de la suscripción de Azure mediante la eliminación del recurso.

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