使用 .NET SDK 將資料大量匯入 Azure Cosmos DB for NoSQL 帳戶

發行項
08/15/2024

適用於：NoSQL

本教學課程說明如何建立 .NET 主控台應用程式，以將資料匯入至 Azure Cosmos DB 所需的佈建輸送量 (RU/秒) 最佳化。

在本文中，您將從範例資料來源讀取資料，並將其匯入 Azure Cosmos DB 容器。本教學課程使用 3.0+ 版的 Azure Cosmos DB .NET SDK，其以 .NET Framework 或 .NET Core 作為目標。

此教學課程涵蓋：

建立 Azure Cosmos DB 帳戶
設定專案
連線至已啟用大量支援的 Azure Cosmos DB 帳戶
透過並行建立作業執行資料匯入

必要條件

依照本文的指示進行之前，請確定您具備下列資源：

使用中的 Azure 帳戶。如尚未擁有 Azure 訂用帳戶，請在開始之前先建立免費帳戶。

您可以免費試用 Azure Cosmos DB，不需 Azure 訂用帳戶，也不需要承諾用量。或者，您可以建立 Azure Cosmos DB 免費層帳戶，免費使用前 1000 RU/秒和 25 GB 的儲存體。您也可以搭配 https://localhost:8081 的 URI 使用 Azure Cosmos DB 模擬器。如需要搭配模擬器使用的金鑰，請參閱驗證要求。
NET Core 3 SDK. 您可以藉由執行 dotnet --version，來確認您環境中可使用的版本。

步驟 1：建立 Azure Cosmos DB 帳戶

從 Azure 入口網站建立 Azure Cosmos DB for NoSQL 帳戶，或者您也可以使用 Azure Cosmos DB 模擬器來建立帳戶。

步驟 2：設定 .NET 專案

從您的本機電腦開啟 Windows 命令提示字元或終端機視窗。您將會在命令提示字元或終端機中執行下一節中的所有命令。執行下列 dotnet 新命令，來建立名為 bulk-import-demo 的新應用程式。

dotnet new console -n bulk-import-demo

將目錄變更為新建立的應用程式資料夾。您可以使用下列命令來建置應用程式：

cd bulk-import-demo
dotnet build

組建的預期輸出看起來應像這樣：

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

步驟 3：新增 Azure Cosmos DB 套件

若您仍在應用程式目錄中，請使用 dotnet add package 命令安裝適用於 .NET Core 的 Azure Cosmos DB 用戶端程式庫。

dotnet add package Microsoft.Azure.Cosmos

步驟 4：取得 Azure Cosmos DB 帳戶認證

範例應用程式需要驗證您的 Azure Cosmos DB 帳戶。若要進行驗證，您應該將 Azure Cosmos DB 帳號認證傳遞給應用程式。請遵循下列步驟取得 Azure Cosmos DB 帳戶認證：

登入 Azure 入口網站。
瀏覽至 Azure Cosmos DB 帳戶。
開啟 [金鑰] 窗格，然後複製您帳戶的 URI 與主索引鍵。

如果您使用的是 Azure Cosmos DB 模擬器，請從此發行項中取得模擬器認證。

步驟 5：使用大量執行支援初始化 CosmosClient 物件

在程式碼編輯器中開啟產生的 Program.cs 檔案。您將為已啟用大量執行的 CosmosClient 建立新的執行個體，並用於對 Azure Cosmos DB 執行作業。

讓我們從覆寫預設的 Main 方法並定義全域變數開始。這些全域變數將包含端點和授權金鑰、資料庫名稱、您將建立的容器，以及您將大量插入的項目數目。請務必根據您的環境取代 endpointURL 和授權金鑰值。

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

     }
}

在 Main 方法中，新增下列程式碼以初始化 CosmosClient 物件：

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

注意

一旦在 CosmosClientOptions 中指定大量執行後，CosmosClient 的存留期就會有效固定。變更值將沒有任何作用。

啟用大量執行之後，CosmosClient 會在內部將並行作業組為單一服務呼叫。如此一來，它會藉由在分割區之間發佈服務呼叫，最後再將個別結果指派給原始呼叫端的方式，以將輸送量使用率最佳化。

接著，您可以建立容器來儲存我們所有的項目。將 /pk 定義為分割區索引鍵，定義每秒 50000 RU 為佈建的輸送量，並定義自訂編製索引原則來排除所有欄位，以將寫入輸送量最佳化。在 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);

步驟 6：填入並行工作的清單

若要利用大量執行支援，請根據資料來源和您想要執行的作業來建立非同步工作清單，並使用 Task.WhenAll 來同時執行它們。讓我們從使用「假」資料開始，從我們的資料模型產生項目清單。在真實世界的應用程式中，項目是來自您所需的資料來源。

首先，使用 dotnet add package 命令，將假封裝新增至解決方案。

dotnet add package Bogus

定義所要儲存項目的定義。您必須在 Program.cs 檔案內定義 Item 類別：

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

    public string username{get;set;}
}

接下來，在 Program 類別內建立 helper 函數。此 helper 函數會取得您定義要插入的項目數目，並產生隨機資料：

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

使用協助程式函數來初始化要使用的文件清單：

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

接下來，使用文件清單來建立並行工作，並填入工作清單以將項目插入容器中。若要執行這項操作，請將下列程式碼新增至 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);

這些並行點作業會全部一起執行 (亦即大量)，如簡介一節中所述。

步驟 7：執行樣本

若要執行範例，只要透過 dotnet 命令來執行此動作：

dotnet run

取得完整範例

如果您沒有時間完成本教學課程中的步驟，或只想要下載程式碼範例，您可以從 GitHub 取得程式碼。

複製專案之後，請務必在 Program.cs 內更新所需的認證。

您可以透過變更為存放庫目錄並使用 dotnet，來執行此範例：

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

下一步

在本教學課程中，您已完成下列步驟：

建立 Azure Cosmos DB 帳戶
設定專案
連線至已啟用大量支援的 Azure Cosmos DB 帳戶
透過並行建立作業執行資料匯入

現在您可以繼續進行下一個教學課程：

使用 API for NoSQL 查詢 Azure Cosmos DB

正在嘗試為遷移至 Azure Cosmos DB 進行容量規劃嗎？您可以使用現有資料庫叢集的相關資訊進行容量規劃。

如果您知道現有資料庫叢集中的虛擬核心和伺服器數目，請參閱使用虛擬核心或 vCPU 來估計要求單位
如果您知道目前資料庫工作負載的一般要求率，請參閱使用 Azure Cosmos DB 容量規劃工具來估計要求單位

共用方式為