Compartilhar via

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

  • Artigo

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ê lerá os dados de uma fonte de dados de exemplo e os importará em um contêiner do Azure Cosmos DB. 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.

Este tutorial abrange:

  • Criar uma conta do Azure Cosmos DB
  • Configurar seu projeto
  • Como se conectar a uma conta do Azure Cosmos DB com o suporte em massa habilitado
  • Executar uma importação de dados por meio de operações de criação simultânea

Pré-requisitos

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

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 de clientes do Azure Cosmos DB para .NET Core usando o comando para adicionar pacote do dotnet.

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 você estiver usando o Emulador do Azure Cosmos DB, obtenha as credenciais do emulador deste artigo.

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. Você criará uma instância do CosmosClient com a execução em massa habilitada e a usará para realizar operações em relação ao Azure Cosmos DB.

Vamos começar substituindo o método Main padrão e definindo as variáveis globais. Essas variáveis globais incluirão as chaves de ponto de extremidade e de autorização, o nome do banco de dados, o contêiner que você criará e o número de itens que você inserirá na execução 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 });

Observação

Depois que a execução em massa for especificada em CosmosClientOptions, ela fica efetivamente imutável durante o tempo de vida do CosmosClient. A alteração dos valores não terá efeito.

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, 50 mil RU/s como taxa de transferência provisionada e uma política de indexação personalizada que excluirá 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 falsos para gerar uma lista de itens com base em 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 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 classe Program. Esta função auxiliar obterá o número de itens que você definiu para serem inseridos e gerará 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 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 serão executadas em conjunto (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

Neste tutorial, você fez as seguintes tarefas:

  • Criar uma conta do Azure Cosmos DB
  • Configurar seu projeto
  • Como se conectar a uma conta do Azure Cosmos DB com o suporte em massa habilitado
  • Executar uma importação de dados por meio de operações de criação simultânea

Agora você pode passar para o próximo tutorial:

Consultar o Azure Cosmos DB usando a API for NoSQL

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