Partilhar via

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

  • Aplica-se a: ✅ NoSQL

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ê lê dados de uma fonte de dados de exemplo e os importa para um contêiner do Azure Cosmos DB.

Este tutorial aborda:

  • Criando uma conta do Azure Cosmos DB
  • Configurando seu projeto
  • Conectando-se a uma conta do Azure Cosmos DB com suporte em massa habilitado
  • Executar uma importação de dados por meio de operações de criação simultâneas

Pré-requisitos

Antes de seguir as instruções neste artigo, certifique-se de que tem os seguintes recursos:

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

Passo 1: criar uma conta do Azure Cosmos DB

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

Etapa 2: Configurar seu 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 do prompt de comando ou terminal. Execute o seguinte comando dotnet new para criar um novo aplicativo com o nome bulk-import-demo.

dotnet new console -n bulk-import-demo

Altere seu diretório para a pasta do aplicativo recém-criada. Você pode criar o aplicativo com:

cd bulk-import-demo
dotnet build

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

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

Enquanto ainda estiver no diretório do aplicativo, instale a biblioteca de 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 de conta do Azure Cosmos DB

O aplicativo de exemplo precisa se autenticar em sua conta do Azure Cosmos DB. Para autenticar, você deve passar as credenciais da conta do Azure Cosmos DB para o aplicativo. Obtenha suas credenciais de conta do Azure Cosmos DB seguindo estas etapas:

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

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

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

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

Comece substituindo o método padrão Main e definindo as variáveis globais. Essas variáveis globais incluem as chaves de ponto de extremidade e 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. Certifique-se de substituir os valores de endpointURL e chave de autorização 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)
     {

     }
}

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

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

Observação

Uma vez que a execução em massa é especificada no CosmosClientOptions, eles são efetivamente imutáveis durante o tempo de vida do CosmosClient. A alteração dos valores não tem efeito.

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

Você pode então criar um recipiente para armazenar todos os nossos itens. Defina /pk como a chave de partição, 50000 RU/s como taxa de transferência provisionada e uma política de indexação personalizada que exclui todos os campos para otimizar a taxa de transferência de gravação. Adicione o seguinte código 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: preencher uma lista de tarefas simultâneas

Para aproveitar 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 falsos para gerar uma lista de itens do nosso modelo de dados. Em um aplicativo do mundo real, os itens viriam da fonte de dados desejada.

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

dotnet add package Bogus

Defina a definição dos itens que você deseja salvar. Você precisa definir a Item classe dentro do 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 Program classe. 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 preencha a lista de tarefas para inserir os itens no contêiner. Para executar essa operação, adicione o seguinte código à Program classe:

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 pontuais simultâneas são executadas juntas (ou seja, em massa), conforme descrito na seção de introdução.

Etapa 7: Executar o exemplo

Para executar o exemplo, você pode fazê-lo simplesmente pelo dotnet comando:

dotnet run

Obtenha a amostra completa

Se não tiver tempo de completar os passos deste tutorial, ou apenas pretender transferir os exemplos de código, pode obtê-los a partir do GitHub.

Depois de clonar o projeto, certifique-se de atualizar as credenciais desejadas dentro Program.cs.

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

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

Próximos passos

Consultar o Azure Cosmos DB usando a API para NoSQL

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

  • Last updated on