Mengimpor data secara massal ke Azure Cosmos DB untuk akun NoSQL dengan menggunakan .NET SDK

  • Artikel

BERLAKU UNTUK: NoSQL

Tutorial ini menunjukkan cara membuat aplikasi konsol .NET yang mengoptimalkan throughput yang disediakan (RU/s) yang diperlukan untuk mengimpor data ke Azure Cosmos DB.

Dalam artikel ini, Anda akan membaca data dari sumber data sampel dan mengimpornya ke dalam kontainer Azure Cosmos DB. Tutorial ini menggunakan Versi 3.0+ dari Azure Cosmos DB .NET SDK, yang dapat ditargetkan ke .NET Framework atau .NET Core.

Tutorial ini mencakup:

  • Membuat akun Azure Cosmos DB
  • Mengonfigurasi proyek Anda
  • Menyambungkan ke akun Azure Cosmos DB dengan dukungan massal diaktifkan
  • Melakukan impor data melalui operasi buat bersamaan

Prasyarat

Sebelum mengikuti instruksi dalam artikel ini, pastikan Anda memiliki sumber daya berikut:

Langkah 1: Buat akun Azure Cosmos DB

Buat akun Azure Cosmos DB for NoSQL dari portal Azure atau Anda dapat membuat akun dengan menggunakan Emulator Azure Cosmos DB.

Langkah 2: Siapkan proyek .NET Anda

Buka prompt perintah Windows atau jendela Terminal dari komputer lokal Anda. Anda akan menjalankan semua perintah di bagian berikutnya dari perintah atau terminal. Jalankan perintah baru dotnet berikut untuk membuat aplikasi baru dengan nama bulk-import-demo.

dotnet new console -n bulk-import-demo

Ubah direktori Anda ke folder aplikasi yang baru dibuat. Anda dapat membuat aplikasi dengan:

cd bulk-import-demo
dotnet build

Output yang diharapkan dari build akan terlihat seperti ini:

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

Langkah 3: Tambahkan paket Azure Cosmos DB

Saat masih dalam direktori aplikasi, pasang pustaka klien Azure Cosmos DB untuk .NET Core menggunakan perintah tambahkan paket dotnet.

dotnet add package Microsoft.Azure.Cosmos

Langkah 4: Dapatkan kredensial akun Azure Cosmos DB Anda

Aplikasi sampel perlu mengautentikasi ke akun Azure Cosmos DB Anda. Untuk mengautentikasi, Anda harus meneruskan kredensial akun Azure Cosmos DB ke aplikasi. Dapatkan kredensial akun Azure Cosmos DB Anda dengan mengikuti langkah-langkah berikut:

  1. Masuk ke portal Microsoft Azure.
  2. Navigasikan ke akun Azure Cosmos DB Anda.
  3. Buka panel Kunci lalu salin URI dan KUNCI PRIMER akun Anda.

Jika Anda menggunakan Emulator Azure Cosmos DB, dapatkan kredensial emulator dari artikel ini.

Langkah 5: Mulai objek CosmosClient dengan dukungan eksekusi massal

Buka file Program.cs yang dihasilkan dalam editor kode. Anda akan membuat instans baru CosmosClient dengan eksekusi massal diaktifkan dan menggunakannya untuk melakukan operasi terhadap Azure Cosmos DB.

Mari kita mulai dengan menimpa metode Main default dan mendefinisikan variabel global. Variabel global ini akan mencakup titik akhir dan kunci otorisasi, nama database, kontainer yang akan Anda buat, dan jumlah item yang akan Anda sisipkan secara massal. Pastikan untuk mengganti nilai endpointURL dan kunci otorisasi sesuai dengan lingkungan Anda.

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

     }
}

Di dalam metode Main, tambahkan kode berikut untuk memulai objek CosmosClient:

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

Catatan

Setelah eksekusi massal ditentukan dalam CosmosClientOptions, eksekusi tersebut secara efektif tidak dapat diubah selama masa pakai CosmosClient. Mengubah nilai tidak akan berpengaruh.

Setelah eksekusi massal diaktifkan, CosmosClient secara internal mengelompokkan operasi bersamaan menjadi satu panggilan layanan. Cara ini mengoptimalkan pemanfaatan throughput dengan mendistribusikan panggilan layanan di seluruh partisi, dan akhirnya menetapkan hasil individual kepada penelepon asli.

Anda kemudian dapat membuat kontainer untuk menyimpan semua item. Tentukan /pk sebagai kunci partisi, 50000 RU/s sebagai throughput yang disediakan, dan kebijakan pengindeksan kustom yang akan mengecualikan semua bidang untuk mengoptimalkan throughput tulis. Tambahkan kode berikut setelah pernyataan inisialisasi 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);

Langkah 6: Isi daftar tugas bersamaan

Untuk memanfaatkan dukungan eksekusi massal, buat daftar tugas asinkron berdasarkan sumber data dan operasi yang ingin Anda lakukan, dan gunakan Task.WhenAll untuk mengeksekusinya secara bersamaan. Mari kita mulai dengan menggunakan data "Bogus" untuk menghasilkan daftar item dari model data kita. Dalam penerapannya di dunia nyata, item akan berasal dari sumber data yang Anda inginkan.

Pertama, tambahkan paket Palsu ke solusi menggunakan perintah tambahkan paket dotnet.

dotnet add package Bogus

Tentukan definisi item yang ingin Anda simpan. Anda perlu menentukan kelas Item dalam file Program.cs:

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

    public string username{get;set;}
}

Selanjutnya, buat fungsi pembantu di dalam kelas Program. Fungsi pembantu ini akan mendapatkan jumlah item yang Anda tentukan untuk menyisipkan dan menghasilkan data acak:

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);
}

Gunakan fungsi pembantu untuk menginisialisasi daftar dokumen yang akan dikerjakan:

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

Selanjutnya, gunakan daftar dokumen untuk membuat tugas bersamaan dan mengisi daftar tugas untuk memasukkan item ke kontainer. Untuk melakukan operasi ini, tambahkan kode berikut ke kelas 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);

Semua operasi titik bersamaan ini akan dijalankan bersamaan (yaitu secara massal) seperti yang dijelaskan di bagian pengenalan.

Langkah 7: Jalankan sampel

Untuk menjalankan sampel, Anda dapat melakukannya hanya dengan perintah dotnet:

dotnet run

Mendapatkan sampel lengkap

Jika Anda tidak punya waktu untuk menyelesaikan langkah-langkah dalam tutorial ini, atau hanya ingin mengunduh sampel kode, Anda bisa mendapatkannya dari GitHub.

Setelah mengkloning proyek, pastikan untuk memperbarui kredensial yang diinginkan di dalam Program.cs.

Sampel dapat dijalankan dengan mengubah ke direktori repositori dan menggunakan dotnet:

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

Langkah berikutnya

Dalam tutorial ini, Anda telah melakukan tugas berikut:

  • Membuat akun Azure Cosmos DB
  • Mengonfigurasi proyek Anda
  • Menyambungkan ke akun Azure Cosmos DB dengan dukungan massal diaktifkan
  • Melakukan impor data melalui operasi buat bersamaan

Sekarang Anda dapat melanjutkan ke tutorial berikutnya:

Mengkueri Azure Cosmos DB dengan menggunakan API untuk NoSQL

Mencoba melakukan perencanaan kapasitas untuk migrasi ke Azure Cosmos DB? Anda dapat menggunakan informasi tentang kluster database Anda yang ada saat ini untuk perencanaan kapasitas.