Compartir a través de

Importación masiva de datos a la cuenta de Azure Cosmos DB for NoSQL mediante el SDK para .NET

SE APLICA A: NoSQL

En este tutorial se muestra cómo compilar una aplicación de consola de .NET que optimice la capacidad de proceso aprovisionada (RU/s) necesaria para importar datos en Azure Cosmos DB.

En este artículo, leerá los datos de un origen de datos de ejemplo e importará en un contenedor de Azure Cosmos DB.

Esta tutorial abarca lo siguiente:

  • Creación de una cuenta de Azure Cosmos DB
  • Configuración del proyecto
  • Conexión a una cuenta de Azure Cosmos DB con compatibilidad para la ejecución en bloque habilitada
  • Realización de una importación de datos mediante operaciones simultáneas de creación

Requisitos previos

Antes de seguir las instrucciones del presente artículo, asegúrese de tener los siguientes recursos:

Este tutorial usa la versión 3.0+ del SDK de .NET de Azure Cosmos DB, cuyo destino puede ser .NET Framework o .NET Core.

Paso 1: Creación de una cuenta de Azure Cosmos DB

Cree una cuenta de Azure Cosmos DB para NoSQL desde Azure Portal o cree la cuenta mediante el emulador de Azure Cosmos DB.

Paso 2: Configuración del proyecto .NET

Abra el símbolo del sistema de Windows o una ventana de Terminal desde el equipo local. En las secciones siguientes todos los comandos se ejecutarán desde el símbolo del sistema o desde el terminal. Ejecute el siguiente comando dotnet new para crear una nueva aplicación con el nombre bulk-import-demo.

dotnet new console -n bulk-import-demo

Cambie el directorio a la carpeta de aplicaciones recién creada. Para compilar la aplicación:

cd bulk-import-demo
dotnet build

El resultado esperado de la compilación debe parecerse a lo siguiente:

Restore completed in 100.37 ms for C:\Users\user1\Downloads\CosmosDB_Samples\bulk-import-demo\bulk-import-demo.csproj.
  bulk -> C:\Users\user1\Downloads\CosmosDB_Samples\bulk-import-demo \bin\Debug\netcoreapp2.2\bulk-import-demo.dll

Build succeeded.
    0 Warning(s)
    0 Error(s)

Time Elapsed 00:00:34.17

Paso 3: Incorporación del paquete de Azure Cosmos DB

Mientras sigue en el directorio de aplicaciones, instale el paquete de la biblioteca cliente de Azure Cosmos DB para .NET Core con el comando dotnet add package.

dotnet add package Microsoft.Azure.Cosmos

Paso 4: Obtención de las credenciales de la cuenta de Azure Cosmos DB

La aplicación de ejemplo debe autenticarse para la cuenta de Azure Cosmos DB. Para hacer la autenticación, debe pasar las credenciales de cuenta de Azure Cosmos DB a la aplicación. Para obtener las credenciales de cuenta de Azure Cosmos DB, siga estos pasos:

  1. Inicie sesión en Azure Portal.
  2. Vaya a la cuenta de Azure Cosmos DB.
  3. Abra el panel Claves y copia el URI y la CLAVE PRINCIPAL de la cuenta.

Si usa el emulador de Azure Cosmos DB, obtenga las credenciales del emulador.

Paso 5: Inicialización del objeto CosmosClient con compatibilidad de ejecución en bloque

Abra el archivo Program.cs generado en un editor de código. Cree una nueva instancia de CosmosClient con la ejecución masiva habilitada y úsela para realizar operaciones en Azure Cosmos DB.

Empiece por sobrescribir el método predeterminado Main y definir las variables globales. Estas variables globales incluyen el punto de conexión y las claves de autorización, el nombre de la base de datos, el contenedor que creará y el número de elementos que insertará en masa. Asegúrese de reemplazar los valores de URL de punto de conexión y clave de autorización según su entorno.

using System;
using System.Collections.Generic;
using System.Diagnostics;
using System.IO;
using System.Text.Json;
using System.Threading.Tasks;
using Microsoft.Azure.Cosmos;

public class Program
{
     private const string EndpointUrl = "https://<your-account>.documents.azure.com:443/";
     private const string AuthorizationKey = "<your-account-key>";
     private const string DatabaseName = "bulk-tutorial";
     private const string ContainerName = "items";
     private const int AmountToInsert = 300000;

     static async Task Main(string[] args)
     {

     }
}

Dentro del método Main, agregue el siguiente código para inicializar el objeto CosmosClient:

CosmosClient cosmosClient = new CosmosClient(EndpointUrl, AuthorizationKey, new CosmosClientOptions() { AllowBulkExecution = true });

Nota

Una vez que se especifica la ejecución masiva en CosmosClientOptions, son inmutables de forma eficaz durante la vigencia de CosmosClient. Cambiar los valores no tiene ningún efecto.

Una vez habilitada la ejecución en bloque, CosmosClient agrupa internamente las operaciones simultáneas en llamadas de servicio únicas. De este modo, optimiza el uso de la capacidad de proceso, ya que distribuye las llamadas de servicio entre las particiones y, por último, asigna los resultados individuales a los llamadores originales.

Después, se puede crear un contenedor para almacenar todos los elementos. Defina /pk como clave de partición, 50000 RU/s como rendimiento aprovisionado y una directiva de indexación personalizada que excluye todos los campos para optimizar el rendimiento de escritura. Agregue el siguiente código después de la instrucción de inicialización de CosmosClient:

Database database = await cosmosClient.CreateDatabaseIfNotExistsAsync(Program.DatabaseName);

await database.DefineContainer(Program.ContainerName, "/pk")
        .WithIndexingPolicy()
            .WithIndexingMode(IndexingMode.Consistent)
            .WithIncludedPaths()
                .Attach()
            .WithExcludedPaths()
                .Path("/*")
                .Attach()
        .Attach()
    .CreateAsync(50000);

Paso 6: Rellenado de una lista de tareas simultáneas

Para aprovechar las ventajas de la compatibilidad con la ejecución en bloque, cree una lista de tareas asincrónicas en función del origen de los datos y de las operaciones que desee realizar, y use Task.WhenAll para ejecutarlas simultáneamente. Empecemos por usar datos de Bogus para generar una lista de elementos a partir de nuestro modelo de datos. En una aplicación real, los elementos procederían del origen de datos deseado.

En primer lugar, agregue el paquete Bogus a la solución mediante el comando dotnet add package.

dotnet add package Bogus

Establezca la definición de los elementos que desea guardar. Debe definir la Item clase dentro del archivo Program.cs :

public class Item
{
    public string id {get;set;}
    public string pk {get;set;}

    public string username{get;set;}
}

A continuación, cree una función auxiliar dentro de la clase Program. Esta función auxiliar obtiene el número de elementos que definió para insertar y genera datos aleatorios:

private static IReadOnlyCollection<Item> GetItemsToInsert()
{
    return new Bogus.Faker<Item>()
    .StrictMode(true)
    //Generate item
    .RuleFor(o => o.id, f => Guid.NewGuid().ToString()) //id
    .RuleFor(o => o.username, f => f.Internet.UserName())
    .RuleFor(o => o.pk, (f, o) => o.id) //partitionkey
    .Generate(AmountToInsert);
}

Use la función auxiliar para inicializar una lista de documentos con los que trabajar:

IReadOnlyCollection<Item> itemsToInsert = Program.GetItemsToInsert();

A continuación, use la lista de documentos para crear tareas simultáneas y rellenar la lista de tareas para insertar los elementos en el contenedor. Para realizar esta operación, agregue el siguiente código a la clase Program:

Container container = database.GetContainer(ContainerName);
List<Task> tasks = new List<Task>(AmountToInsert);
foreach (Item item in itemsToInsert)
{
    tasks.Add(container.CreateItemAsync(item, new PartitionKey(item.pk))
        .ContinueWith(itemResponse =>
        {
            if (!itemResponse.IsCompletedSuccessfully)
            {
                AggregateException innerExceptions = itemResponse.Exception.Flatten();
                if (innerExceptions.InnerExceptions.FirstOrDefault(innerEx => innerEx is CosmosException) is CosmosException cosmosException)
                {
                    Console.WriteLine($"Received {cosmosException.StatusCode} ({cosmosException.Message}).");
                }
                else
                {
                    Console.WriteLine($"Exception {innerExceptions.InnerExceptions.FirstOrDefault()}.");
                }
            }
        }));
}

// Wait until all are done
await Task.WhenAll(tasks);

Todas estas operaciones de punto simultáneos se ejecutan juntas (que se encuentran en masa) como se describe en la sección introducción.

Paso 7: Ejecución de la muestra

Puede ejecutar el ejemplo simplemente con el comando dotnet:

dotnet run

Obtención del ejemplo completo

Si no dispuso de tiempo para completar los pasos de este tutorial, o simplemente desea descargar los ejemplos de código, puede obtenerlos de GitHub.

Después de clonar el proyecto, asegúrese de actualizar las credenciales que desee en Program.cs.

El ejemplo se puede ejecutar cambiando al directorio del repositorio y usando dotnet:

cd cosmos-dotnet-bulk-import-throughput-optimizer
dotnet run

Pasos siguientes

Consulta de Azure Cosmos DB mediante la API para NoSQL

¿Intenta planear la capacidad de una migración a Azure Cosmos DB? Para ello, puede usar información sobre el clúster de bases de datos existente.

  • Last updated on