Adatok tömeges importálása az Azure Cosmos DB for NoSQL-fiókba a .NET SDK használatával

  • Cikk

A KÖVETKEZŐRE VONATKOZIK: NoSQL

Ez az oktatóanyag bemutatja, hogyan hozhat létre egy .NET-konzolalkalmazást, amely optimalizálja az adatok Azure Cosmos DB-be való importálásához szükséges kiépített átviteli sebességet (RU/s).

Ebben a cikkben egy mintaadatforrás adatait fogja olvasni, és importálni egy Azure Cosmos DB-tárolóba. Ez az oktatóanyag az Azure Cosmos DB .NET SDK 3.0-s vagy újabb verzióját használja, amely .NET-keretrendszer vagy .NET Core-ra célozható.

Ez az oktatóanyag az alábbiakkal foglalkozik:

  • Azure Cosmos DB-fiók létrehozása
  • A projekt konfigurálása
  • Csatlakozás Azure Cosmos DB-fiókhoz tömeges támogatással engedélyezve
  • Adatimportálás végrehajtása egyidejű létrehozási műveletekkel

Előfeltételek

A cikk utasításainak követése előtt győződjön meg arról, hogy rendelkezik a következő erőforrásokkal:

1. lépés: Azure Cosmos DB-fiók létrehozása

Hozzon létre egy Azure Cosmos DB for NoSQL-fiókot a Azure Portal, vagy hozza létre a fiókot az Azure Cosmos DB Emulator használatával.

2. lépés: A .NET-projekt beállítása

Nyissa meg a Windows parancssort vagy egy terminálablakot a helyi számítógépről. A parancssorból vagy a terminálból a következő szakaszokban futtatja az összes parancsot. Futtassa a következő dotnet új parancsot egy új alkalmazás tömeges importálás-demo néven való létrehozásához.

dotnet new console -n bulk-import-demo

Módosítsa a könyvtárat az újonnan létrehozott alkalmazásmappára. Az alkalmazást a következőkkel hozhatja létre:

cd bulk-import-demo
dotnet build

A build várt kimenetének a következőképpen kell kinéznie:

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. lépés: Az Azure Cosmos DB-csomag hozzáadása

Miközben még az alkalmazáskönyvtárban van, telepítse a .NET Core-hoz készült Azure Cosmos DB ügyfélkódtárat a dotnet add package paranccsal.

dotnet add package Microsoft.Azure.Cosmos

4. lépés: Azure Cosmos DB-fiók hitelesítő adatainak lekérése

A mintaalkalmazásnak hitelesítenie kell magát az Azure Cosmos DB-fiókban. A hitelesítéshez át kell adnia az Azure Cosmos DB-fiók hitelesítő adatait az alkalmazásnak. Az alábbi lépésekkel szerezheti be az Azure Cosmos DB-fiók hitelesítő adatait:

  1. Jelentkezzen be az Azure Portalra.
  2. Lépjen az Azure Cosmos DB-fiókjához.
  3. Nyissa meg a Kulcsok panelt, és másolja ki a fiók URI-ját és ELSŐDLEGES KULCSát .

Ha az Azure Cosmos DB Emulatort használja, szerezze be az emulátor hitelesítő adatait ebből a cikkből.

5. lépés: A CosmosClient objektum inicializálása tömeges végrehajtás támogatásával

Nyissa meg a létrehozott Program.cs fájlt egy kódszerkesztőben. Létrehoz egy új CosmosClient-példányt, amelyen engedélyezve van a tömeges végrehajtás, és az használatával műveleteket hajthat végre az Azure Cosmos DB-vel.

Kezdjük az alapértelmezett Main metódus felülírásával és a globális változók definiálásával. Ezek a globális változók tartalmazzák a végpontot és az engedélyezési kulcsokat, az adatbázis nevét, a létrehozandó tárolót, valamint a tömegesen beszúrandó elemek számát. Mindenképpen cserélje le az endpointURL és az engedélyezési kulcs értékeit a környezetének megfelelően.

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

     }
}

A metóduson Main belül adja hozzá a következő kódot a CosmosClient objektum inicializálásához:

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

Megjegyzés

Ha a CosmosClientOptionsban a tömeges végrehajtás meg van adva, azok gyakorlatilag nem módosíthatók a CosmosClient élettartama során. Az értékek módosítása nem lesz hatással.

A tömeges végrehajtás engedélyezése után a CosmosClient belsőleg egyetlen szolgáltatáshívásba csoportosítja az egyidejű műveleteket. Így optimalizálja az átviteli sebesség kihasználtságát azáltal, hogy elosztja a szolgáltatáshívásokat a partíciók között, és végül egyedi eredményeket rendel az eredeti hívókhoz.

Ezután létrehozhat egy tárolót az összes elem tárolásához. Definiálja /pk a partíciókulcsot, az 50000 RU/s értéket kiosztott átviteli sebességként, és egy egyéni indexelési szabályzatot, amely kizárja az összes mezőt az írási sebesség optimalizálásához. Adja hozzá a következő kódot a CosmosClient inicializálási utasítása után:

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. lépés: Egyidejű tevékenységek listájának feltöltése

A tömeges végrehajtás támogatásának kihasználásához hozzon létre egy listát az aszinkron feladatokról az adatok forrása és a végrehajtani kívánt műveletek alapján, és használja Task.WhenAll őket egyidejű végrehajtásra. Kezdjük a "Hamis" adatok használatával az adatmodell elemeinek listájának létrehozásához. Egy valós alkalmazásban az elemek a kívánt adatforrásból származnak.

Először adja hozzá a Hamis csomagot a megoldáshoz a dotnet add package paranccsal.

dotnet add package Bogus

Határozza meg a menteni kívánt elemek definícióját. Meg kell határoznia a osztályt Item a fájlban Program.cs :

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

    public string username{get;set;}
}

Ezután hozzon létre egy segédfüggvényt az Program osztályon belül. Ez a segédfüggvény lekéri a véletlenszerű adatok beszúrásához és generálásához definiált elemek számát:

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

A segédfüggvény használatával inicializálhatja a dokumentumok listáját a következőkkel való munkához:

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

Ezután a dokumentumok listájával egyidejű tevékenységeket hozhat létre, és feltöltheti a feladatlistát, hogy beszúrja az elemeket a tárolóba. A művelet végrehajtásához adja hozzá a következő kódot az Program osztályhoz:

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

Ezeket az egyidejű pontműveleteket a rendszer együtt hajtja végre (ez tömegesen történik), a bevezető szakaszban leírtak szerint.

7. lépés: A minta futtatása

A minta futtatásához egyszerűen dotnet a következő paranccsal végezheti el:

dotnet run

A teljes minta lekérése

Ha nincs ideje az oktatóanyag lépéseinek végrehajtására, vagy csak szeretné letölteni a mintakódokat, a GitHubon beszerezhetőek.

A projekt klónozása után frissítse a kívánt hitelesítő adatokat a Program.cs fájlban.

A minta az adattár könyvtárára való módosítással és a következő használatával dotnetfuttatható:

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

Következő lépések

Ebben az oktatóanyagban a következő lépéseket hajtotta végre:

  • Azure Cosmos DB-fiók létrehozása
  • A projekt konfigurálása
  • Csatlakozás Azure Cosmos DB-fiókhoz tömeges támogatással engedélyezve
  • Adatimportálás végrehajtása egyidejű létrehozási műveletekkel

Most folytathatja a következő oktatóanyagot:

Az Azure Cosmos DB lekérdezése a NoSQL-hez készült API használatával

Kapacitástervezést szeretne végezni az Azure Cosmos DB-be való migráláshoz? A kapacitástervezéshez használhatja a meglévő adatbázisfürt adatait.