Importar dados em massa para a conta do Azure Cosmos DB for NoSQL usando o SDK do .NET

Este tutorial mostra como criar um aplicativo de console .NET que otimiza a taxa de transferência provisionada (RU/s) necessária para importar dados para o Azure Cosmos DB.

Neste artigo, você vai ler sobre dados de uma fonte de dados de amostra e os importa para um contêiner do Azure Cosmos DB.

Este tutorial abrange:

Pré-requisitos

Antes de seguir as instruções deste artigo, verifique se você tem os seguintes recursos:

• Uma conta ativa do Azure. Se você não tiver uma assinatura do Azure, crie uma conta gratuita antes de começar.

  Você pode criar uma conta de camada gratuita do Azure Cosmos DB, com as primeiras 1000 RU/s e 25 GB de armazenamento grátis. Você também pode usar o emulador do Azure Cosmos DB com o URI https://localhost:8081. Quanto à chave a ser usada com o emulador, confira Autenticação de solicitações.

• SDK do .NET Core 3. Você pode verificar qual versão está disponível em seu ambiente executando dotnet --version.

Este tutorial usa a Versão 3.0 e posterior do SDK do .NET do Azure Cosmos DB, que pode ser direcionada para o .NET Framework ou o .NET Core.

Etapa 1: Criar uma conta do Azure Cosmos DB

Crie uma conta do Azure Cosmos DB for NoSQL no portal do Azure ou crie a conta usando o Emulador do Azure Cosmos DB.

Etapa 2: Configurar o projeto .NET

Abra o prompt de comando do Windows ou uma janela do Terminal no computador local. Você executará todos os comandos nas próximas seções no prompt de comando ou no terminal. Execute o novo comando dotnet a seguir para criar um novo aplicativo com o nome bulk-import-demo.

dotnet new console -n bulk-import-demo

Altere o diretório para a pasta do aplicativo recém-criado. É possível criar o aplicativo com:

cd bulk-import-demo
dotnet build

A saída esperada da compilação deve ser algo como:

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

Etapa 3: Adicionar o pacote do Azure Cosmos DB

Ainda no diretório do aplicativo, instale a biblioteca cliente do Azure Cosmos DB para .NET Core usando o comando dotnet add package.

dotnet add package Microsoft.Azure.Cosmos

Etapa 4: Obter suas credenciais da conta do Azure Cosmos DB

O aplicativo de exemplo precisa se autenticar na sua conta do Azure Cosmos DB. Para a autenticação, você deve transmitir as credenciais da conta do Azure Cosmos DB para o aplicativo. Obtenha suas credenciais da conta do Azure Cosmos DB seguindo estas etapas:

1. Entre no portal do Azure.
2. Navegue até a conta do Azure Cosmos DB.
3. Abra o painel Chaves e copie o URI e a CHAVE PRIMÁRIA da sua conta.

Se estiver usando o Emulador do Azure Cosmos DB, obtenha as credenciais do emulador.

Etapa 5: Inicializar o objeto CosmosClient com suporte para execução em massa

Abra o arquivo Program.cs gerado em um editor de código. Crie uma nova instância de CosmosClient com execução em massa habilitada e use-a para realizar operações no Azure Cosmos DB.

Comece substituindo o método Main padrão e definindo as variáveis globais. Essas variáveis globais incluem o ponto de extremidade e as chaves de autorização, o nome do banco de dados, o contêiner que você criará e o número de itens que você inserirá em massa. Substitua os valores de chave de autorização e URL de ponto de extremidade de acordo com seu ambiente.

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)
     {

     }
}

No método Main, adicione o seguinte código para inicializar o objeto CosmosClient:

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

Depois que a execução em massa estiver habilitada, o CosmosClient agrupará internamente as operações simultâneas em chamadas de serviço individuais. Dessa forma, ele otimiza a utilização da taxa de transferência distribuindo chamadas de serviço entre partições e finalmente atribuindo os resultados individuais aos chamadores originais.

Você pode criar um contêiner para armazenar todos os nossos itens. Defina /pk como a chave de partição, 50000 RU/s como a taxa de transferência provisionada e uma política de indexação personalizada que exclua todos os campos para otimizar a taxa de transferência de gravação. Adicione o código a seguir após a instrução de inicialização 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);

Etapa 6: Popular uma lista de tarefas simultâneas

Para usar o suporte à execução em massa, crie uma lista de tarefas assíncronas com base na fonte de dados e nas operações que você deseja executar e use Task.WhenAll para executá-las simultaneamente. Vamos começar usando dados Bogus para gerar uma lista de itens do nosso modelo de dados. Em um aplicativo do mundo real, os itens seriam provenientes de sua fonte de dados desejada.

Primeiro, adicione o pacote do Bogus à solução usando o comando add package do dotnet.

dotnet add package Bogus

Configure a definição dos itens que você deseja salvar. Você precisa definir a classe Item no arquivo Program.cs:

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

    public string username{get;set;}
}

Em seguida, crie uma função auxiliar dentro da classe Program. Esta função auxiliar obtém o número de itens que você definiu para inserir e gera dados aleatórios:

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 a função auxiliar para inicializar uma lista de documentos com os quais trabalhar:

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

Em seguida, use a lista de documentos para criar tarefas simultâneas e preencher a lista de tarefas para inserir os itens no contêiner. Para executar essa operação, adicione o código a seguir à classe 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 essas operações de ponto simultâneas são executadas juntas (ou seja, em massa), conforme descrito na seção de introdução.

Etapa 7: Executar o exemplo

Você pode executar o exemplo simplesmente pelo comando dotnet:

dotnet run

Obter o exemplo completo

Se você não teve tempo para concluir as etapas neste tutorial ou se deseja apenas baixar os exemplos de código, poderá obtê-los no GitHub.

Após clonar o projeto, atualize as credenciais desejadas dentro de Program.cs.

O exemplo pode ser executado alterando o diretório do repositório e usando dotnet:

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

Próximas etapas

Tentando fazer um planejamento de capacidade para uma migração para o Microsoft Azure Cosmos DB? Você pode usar informações sobre o seu cluster de banco de dados existente para planejamento de capacidade.

• Se você sabe apenas o número de vCores e servidores do cluster de banco de dados existente, leia sobre como estimar unidades de solicitação com vCores ou vCPUs
• Se souber as taxas de solicitação típicas da carga de trabalho do banco de dados atual, leia sobre como estimar unidades de solicitação usando o planejador de capacidade do Azure Cosmos DB