Inicio rápido: Compilación de una aplicación .NET Framework o Core mediante la cuenta de Gremlin API de Azure Cosmos DB

Artículo
08/25/2021
12 minutos para leer

SE APLICA A: Gremlin API

Azure Cosmos DB es un servicio de base de datos con varios modelos y de distribución global de Microsoft. Puede crear rápidamente bases de datos de documentos, clave-valor y grafos, y realizar consultas en ellas. Todas las bases de datos se beneficiarán de las funcionalidades de distribución global y escala horizontal en Azure Cosmos DB.

En este inicio rápido se muestra cómo crear una cuenta de Gremlin API, una base de datos y un grafo (contenedor) de Azure Cosmos DB mediante Azure Portal. Después, compile y ejecute una aplicación de consola compilada con el controlador Gremlin.Net de código abierto.

Requisitos previos

Si no tiene Visual Studio 2019 instalado, puede descargar y usar la versión gratuita de Visual Studio 2019 Community Edition. Asegúrese de que habilita Desarrollo de Azure durante la instalación de Visual Studio.

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

Creación de una cuenta de base de datos

En una nueva ventana del explorador, inicie sesión en Azure Portal.
En el menú de la izquierda, seleccione Crear un recurso.
En la página Nuevo, seleccione Bases de datos > Azure Cosmos DB.

En la página Crear una cuenta de Azure Cosmos DB, especifique la configuración de la nueva cuenta de Azure Cosmos DB.

Configuración	Value	Descripción
Suscripción	Nombre de suscripción	Seleccione la suscripción de Azure que desea usar para esta cuenta de Azure Cosmos.
Grupo de recursos	Definición de un nombre de grupo de recursos	Seleccione un grupo de recursos o seleccione Crear nuevo y escriba un nombre único para el grupo de recursos nuevo.
Nombre de cuenta	Escriba un nombre único.	Escriba un nombre único para identificar la cuenta de Azure Cosmos DB. El URI de la cuenta será gremlin.azure.com y se anexará al nombre único de la cuenta. El nombre de la cuenta solo puede utilizar letras minúsculas, números y guiones (-), y debe tener entre 3 y 44 caracteres de longitud.
API	Gremlin (grafo)	La API determina el tipo de cuenta que se va a crear. Azure Cosmos DB proporciona cinco API: Core (SQL) para bases de datos de documentos, Gremlin para bases de datos de grafos, MongoDB para bases de datos de documentos, Azure Table y Cassandra. Debe crear una cuenta independiente para cada API. Seleccione Gremlin (grafo), ya que en este inicio rápido va a crear una tabla que funciona con Gremlin API. Más información sobre Gremlin API.
Location	Región más cercana a los usuarios	Seleccione una ubicación geográfica para hospedar la cuenta de Azure Cosmos DB. Use la ubicación más cercana a los usuarios para que puedan acceder de la forma más rápida posible a los datos.
Capacity mode (Modo de capacidad)	Rendimiento aprovisionado o sin servidor	Seleccione Provisioned throughput (Rendimiento aprovisionado) para crear una cuenta en modo de rendimiento aprovisionado. Seleccione Serverless (Sin servidor) para crear una cuenta en modo sin servidor.
Aplicar el descuento del nivel Gratis de Azure Cosmos DB	Aplicar o No aplicar	Con el nivel Gratis de Azure Cosmos DB, recibirá los primeros 1000 RU/s y 25 GB de almacenamiento gratis en una cuenta. Más información acerca del nivel Gratis.

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 no ve la opción para aplicar el descuento por nivel Gratis, significará que en otra cuenta de la suscripción ya se ha habilitado el nivel Gratis.

Página de la nueva cuenta de Azure Cosmos DB

En la pestaña Distribución global, configure los detalles siguientes. Puede dejar los valores predeterminados para este inicio rápido:

Configuración	Value	Descripción
Redundancia geográfica	Deshabilitar	Habilite o deshabilite la distribución global en su cuenta. Para ello, debe emparejar su región con una región de par. Puede agregar más regiones a su cuenta más adelante.
Escrituras en varias regiones	Deshabilitar	La funcionalidad de escrituras en varias regiones le permite aprovechar el rendimiento aprovisionado para sus bases de datos y contenedores de todo el mundo.

Nota

Las siguientes opciones no están disponibles si selecciona Serverless (Sin servidor) en Capacity mode (Modo de capacidad):

Aplicación de descuento por nivel Gratis
Redundancia geográfica
Escrituras en varias regiones

Opcionalmente, puede configurar detalles adicionales en las pestañas siguientes:
- Redes: configure el acceso desde una red virtual.
- Directiva de copia de seguridad: configure una directiva de copia de seguridad periódica o continua.
- Cifrado: use una clave administrada por el servicio o una clave administrada por el cliente.
- Etiquetas: son pares nombre-valor que permiten categorizar los recursos y ver una facturación consolidada mediante la aplicación de la misma etiqueta en varios recursos y grupos de recursos.
Seleccione Revisar + crear.
La cuenta tarda unos minutos en crearse. Espere a que el portal muestre la página ¡Enhorabuena! Se ha creado su cuenta de Azure Cosmos DB.

Agregar un grafo

Ahora puede usar la herramienta Explorador de datos en Azure Portal para crear una base de datos de grafos.

Seleccione Explorador de datos > New Graph (Nuevo grafo).

El área Agregar gráfico se muestra en el extremo derecho, pero es posible que haya que desplazarse hacia la derecha para verlo.

En la página Agregar gráfico, especifique la configuración del nuevo gráfico.

Configuración	Valor sugerido	Descripción
Identificador de base de datos	sample-database	Escriba sample-database como nombre de la nueva base de datos. Los nombres de bases de datos deben tener entre 1 y 255 caracteres y no pueden contener `/ \ # ?` o un espacio al final.
Throughput	400 RU	Cambie el rendimiento a 400 unidades de solicitud por segundo (RU/s). Si quiere reducir la latencia, puede escalar verticalmente el rendimiento más adelante.
Identificador de grafo	sample-graph	Escriba sample-graph como nombre de la nueva colección. Los nombres de grafo tienen los mismos requisitos de caracteres que los identificadores de base de datos.
Partition Key	/pk	Todas las cuentas de Cosmos DB necesitan una clave de partición para escalar horizontalmente. Aprenda a seleccionar una clave de partición adecuada en el artículo de creación de particiones de datos de Graph.

Una vez que haya rellenado el formulario, seleccione Aceptar.

Clonación de la aplicación de ejemplo

Ahora, vamos a clonar una aplicación de Gremlin API desde GitHub, establecer la cadena de conexión y ejecutarla. Verá lo fácil que es trabajar con datos mediante programación.

Abra un símbolo del sistema, cree una carpeta nueva denominada ejemplos de GIT y, después, cierre el símbolo del sistema.
```
md "C:\git-samples"
```
Abra una ventana de terminal de Git, como git bash y utilice el comando cd para cambiar a la nueva carpeta para instalar la aplicación de ejemplo.
```
cd "C:\git-samples"
```
Ejecute el comando siguiente para clonar el repositorio de ejemplo. Este comando crea una copia de la aplicación de ejemplo en el equipo.
```
git clone https://github.com/Azure-Samples/azure-cosmos-db-graph-gremlindotnet-getting-started.git
```
A continuación, abra Visual Studio y el archivo de solución.
Restaure los paquetes de NuGet en el proyecto. Debe incluir el controlador Gremlin.Net, así como el paquete Newtonsoft.Json.
También puede instalar manualmente el controlador Gremlin.Net@v3.4.6 mediante el administrador de paquetes NuGet o la utilidad de línea de comandos de NuGet:
```
nuget install Gremlin.NET -Version 3.4.6
```

Nota

Gremlin API actualmente solo admite Gremlin.Net hasta la versión v3.4.6. Si instala la versión más reciente, se producirán errores al usar el servicio.

Revisión del código

Este paso es opcional. Si está interesado en aprender cómo se crean los recursos de base de datos en el código, puede revisar los siguientes fragmentos de código. En caso contrario, puede ir directamente a Actualización de la cadena de conexión.

Los fragmentos de código siguientes se han tomado del archivo Program.cs.

Establezca los parámetros de conexión en función de la cuenta creada anteriormente:

private static string Host => Environment.GetEnvironmentVariable("Host") ?? throw new ArgumentException("Missing env var: Host");
private static string PrimaryKey => Environment.GetEnvironmentVariable("PrimaryKey") ?? throw new ArgumentException("Missing env var: PrimaryKey");
private static string Database => Environment.GetEnvironmentVariable("DatabaseName") ?? throw new ArgumentException("Missing env var: DatabaseName");
private static string Container => Environment.GetEnvironmentVariable("ContainerName") ?? throw new ArgumentException("Missing env var: ContainerName");

private static bool EnableSSL
{
    get
    {
        if (Environment.GetEnvironmentVariable("EnableSSL") == null)
        {
            return true;
        }

        if (!bool.TryParse(Environment.GetEnvironmentVariable("EnableSSL"), out bool value))
        {
            throw new ArgumentException("Invalid env var: EnableSSL is not a boolean");
        }

        return value;
    }
}

private static int Port
{
    get
    {
        if (Environment.GetEnvironmentVariable("Port") == null)
        {
            return 443;
        }

        if (!int.TryParse(Environment.GetEnvironmentVariable("Port"), out int port))
        {
            throw new ArgumentException("Invalid env var: Port is not an integer");
        }

        return port;
    } 
}

Se muestran los comandos de Gremlin que se van a ejecutar en un diccionario:

private static Dictionary<string, string> gremlinQueries = new Dictionary<string, string>
{
    { "Cleanup",        "g.V().drop()" },
    { "AddVertex 1",    "g.addV('person').property('id', 'thomas').property('firstName', 'Thomas').property('age', 44).property('pk', 'pk')" },
    { "AddVertex 2",    "g.addV('person').property('id', 'mary').property('firstName', 'Mary').property('lastName', 'Andersen').property('age', 39).property('pk', 'pk')" },
    { "AddVertex 3",    "g.addV('person').property('id', 'ben').property('firstName', 'Ben').property('lastName', 'Miller').property('pk', 'pk')" },
    { "AddVertex 4",    "g.addV('person').property('id', 'robin').property('firstName', 'Robin').property('lastName', 'Wakefield').property('pk', 'pk')" },
    { "AddEdge 1",      "g.V('thomas').addE('knows').to(g.V('mary'))" },
    { "AddEdge 2",      "g.V('thomas').addE('knows').to(g.V('ben'))" },
    { "AddEdge 3",      "g.V('ben').addE('knows').to(g.V('robin'))" },
    { "UpdateVertex",   "g.V('thomas').property('age', 44)" },
    { "CountVertices",  "g.V().count()" },
    { "Filter Range",   "g.V().hasLabel('person').has('age', gt(40))" },
    { "Project",        "g.V().hasLabel('person').values('firstName')" },
    { "Sort",           "g.V().hasLabel('person').order().by('firstName', decr)" },
    { "Traverse",       "g.V('thomas').out('knows').hasLabel('person')" },
    { "Traverse 2x",    "g.V('thomas').out('knows').hasLabel('person').out('knows').hasLabel('person')" },
    { "Loop",           "g.V('thomas').repeat(out()).until(has('id', 'robin')).path()" },
    { "DropEdge",       "g.V('thomas').outE('knows').where(inV().has('id', 'mary')).drop()" },
    { "CountEdges",     "g.E().count()" },
    { "DropVertex",     "g.V('thomas').drop()" },
};

Cree objetos de conexión GremlinServer y GremlinClient nuevos con los parámetros proporcionados anteriormente:

string containerLink = "/dbs/" + Database + "/colls/" + Container;
Console.WriteLine($"Connecting to: host: {Host}, port: {Port}, container: {containerLink}, ssl: {EnableSSL}");
var gremlinServer = new GremlinServer(Host, Port, enableSsl: EnableSSL, 
                                        username: containerLink, 
                                        password: PrimaryKey);

ConnectionPoolSettings connectionPoolSettings = new ConnectionPoolSettings()
{
    MaxInProcessPerConnection = 10,
    PoolSize = 30, 
    ReconnectionAttempts= 3,
    ReconnectionBaseDelay = TimeSpan.FromMilliseconds(500)
};

var webSocketConfiguration =
    new Action<ClientWebSocketOptions>(options =>
    {
        options.KeepAliveInterval = TimeSpan.FromSeconds(10);
    });


using (var gremlinClient = new GremlinClient(
    gremlinServer, 
    new GraphSON2Reader(), 
    new GraphSON2Writer(), 
    GremlinClient.GraphSON2MimeType, 
    connectionPoolSettings, 
    webSocketConfiguration))
{

Ejecute cada consulta de Gremlin mediante el objeto GremlinClient con una tarea asincrónica. Puede leer las consultas Gremlin del diccionario definido en el paso anterior y ejecutarlas. Más tarde, recupere el resultado y lea los valores con formato de diccionario mediante la clase JsonSerializer del paquete Newtonsoft.Json:

foreach (var query in gremlinQueries)
{
    Console.WriteLine(String.Format("Running this query: {0}: {1}", query.Key, query.Value));

    // Create async task to execute the Gremlin query.
    var resultSet = SubmitRequest(gremlinClient, query).Result;
    if (resultSet.Count > 0)
    {
        Console.WriteLine("\tResult:");
        foreach (var result in resultSet)
        {
            // The vertex results are formed as Dictionaries with a nested dictionary for their properties
            string output = JsonConvert.SerializeObject(result);
            Console.WriteLine($"\t{output}");
        }
        Console.WriteLine();
    }

    // Print the status attributes for the result set.
    // This includes the following:
    //  x-ms-status-code            : This is the sub-status code which is specific to Cosmos DB.
    //  x-ms-total-request-charge   : The total request units charged for processing a request.
    //  x-ms-total-server-time-ms   : The total time executing processing the request on the server.
    PrintStatusAttributes(resultSet.StatusAttributes);
    Console.WriteLine();
}

Actualización de la cadena de conexión

Ahora vuelva a Azure Portal para obtener la información de la cadena de conexión y cópiela en la aplicación.

En Azure Portal, vaya a la cuenta de base de datos de grafos. En la pestaña Información general, puede ver dos puntos de conexión.

URI del SDK de .NET: este valor se usa al conectarse a la cuenta de grafos mediante la biblioteca de Microsoft.Azure.Graphs.

Punto de conexión de Gremlin: este valor se usa cuando se conecta a la cuenta de grafos mediante la biblioteca Gremlin.Net.

Para ejecutar este ejemplo, copie el valor de Punto de conexión de Gremlin y elimine el número de puerto del final de manera que el identificador URI se convierta en https://<your cosmos db account name>.gremlin.cosmosdb.azure.com. El valor del punto de conexión debe parecerse a testgraphacct.gremlin.cosmosdb.azure.com.
A continuación, vaya a la pestaña Claves y copie el valor de CLAVE PRINCIPAL de Azure Portal.
Una vez copiados el URI y la CLAVE PRINCIPAL de la cuenta, guárdelos en una variable de entorno nueva en la máquina local que ejecuta la aplicación. Para establecer la variable de entorno, abra una ventana del símbolo del sistema y ejecute el siguiente comando. Asegúrese de reemplazar los valores de <URI_de_la_cuenta_de_Azure_Cosmos> y <CLAVE_PRINCIPAL_de_la_cuenta_de_Azure_Cosmos>.
```
setx Host "<your Azure Cosmos account name>.gremlin.cosmosdb.azure.com"
setx PrimaryKey "<Your_Azure_Cosmos_account_PRIMARY_KEY>"
```
Abra el archivo Program.cs y actualice las variables "base de datos" y "contenedor" con los nombres de la base de datos y el contenedor (que también es el nombre del grafo) creados anteriormente.

private static string database = "your-database-name"; private static string container = "your-container-or-graph-name";
Guarde el archivo Program.cs.

Ya ha actualizado la aplicación con toda la información que necesita para comunicarse con Azure Cosmos DB.

Ejecutar la aplicación de consola

Haga clic en CTRL + F5 para ejecutar la aplicación. La aplicación imprimirá los resultados de la consola y los comandos de consulta de Gremlin.

En la ventana de la consola se muestran los vértices y los bordes que se agregan al grafo. Cuando se complete el script, presione ENTRAR para cerrar la ventana de la consola.

Examinar mediante el Explorador de datos

Ahora puede volver al Explorador de datos en Azure Portal para examinar y consultar los datos del nuevo grafo.

En el Explorador de datos, la nueva base de datos aparece en el panel Grafos. Expanda los nodos del contenedor y de la base de datos y, a continuación, haga clic en Grafo.
Haga clic en el botón Aplicar filtro para usar la consulta predeterminada para visualizar todos los vértices del grafo. Los datos generados por la aplicación de ejemplo se muestran en el panel grafos.

Puede acercar o alejar el grafo, expandir el espacio de visualización del grafo, agregar vértices adicionales y mover los vértices sobre la superficie de visualización.

Revisión de los SLA en Azure Portal

Azure Portal supervisa el rendimiento, capacidad de almacenamiento, disponibilidad, latencia y coherencia de su cuenta de Cosmos DB. Los gráficos de las métricas asociadas con un Acuerdo de Nivel de Servicio (SLA) de Azure Cosmos DB muestran el rendimiento real en comparación con el valor de este acuerdo. Este conjunto de métricas hace que la supervisión de los Acuerdos de Nivel de Servicio sea transparente.

Para revisar las métricas y los Acuerdos de Nivel de Servicio:

Seleccione Métricas en el menú de navegación de la cuenta de Cosmos DB.
Seleccione una pestaña como Latencia y seleccione un período de tiempo a la derecha. Compare las líneas Real y SLA de los gráficos.
Revise las métricas de las otras pestañas.

Limpieza de recursos

Cuando haya terminado tanto con la aplicación como con la cuenta de Azure Cosmos DB, puede eliminar los recursos de Azure que creó para no tener más gastos. Para eliminar los recursos:

En la barra de búsqueda de Azure Portal, busque y seleccione Grupos de recursos.
En la lista, seleccione el grupo de recursos que creó para este inicio rápido.
En la página Información general del grupo de recursos, seleccione Eliminar grupo de recursos.
En la ventana siguiente, escriba el nombre del grupo de recursos que desea eliminar y, después, seleccione Eliminar.

Pasos siguientes

En esta guía de inicio rápido, ha obtenido información sobre cómo crear una cuenta de Azure Cosmos DB, crear un grafo mediante el Explorador de datos y ejecutar una aplicación. Ahora puede crear consultas más complejas e implementar con Gremlin una lógica eficaz de recorrido del grafo.

Consulta mediante Gremlin

Inicio rápido: Compilación de una aplicación .NET Framework o Core mediante la cuenta de Gremlin API de Azure Cosmos DB

Valore su experiencia

Requisitos previos

Creación de una cuenta de base de datos

Agregar un grafo

Clonación de la aplicación de ejemplo

Revisión del código

Actualización de la cadena de conexión

Ejecutar la aplicación de consola

Examinar mediante el Explorador de datos

Revisión de los SLA en Azure Portal

Limpieza de recursos

Pasos siguientes