.NET SDK를 사용하여 Azure Cosmos DB for NoSQL 계정으로 데이터 대량 가져오기

아티클
08/15/2024

적용 대상: NoSQL

이 자습서에서는 Azure Cosmos DB으로 데이터를 가져오는 데 필요한 프로비저닝된 처리량(RU/초)을 최적화하는 .NET 콘솔 애플리케이션을 빌드하는 방법을 설명합니다.

이 문서에서는 샘플 데이터 원본에서 데이터를 읽고 Azure Cosmos DB 컨테이너로 가져옵니다. 이 자습서에서는 .NET Framework 또는 .NET Core를 대상으로 하는 버전 3.0 이상 Azure Cosmos DB .NET SDK를 사용합니다.

이 자습서에서는 다음 내용을 다룹니다.

Azure Cosmos DB 계정 만들기
프로젝트 구성
대량 지원을 사용하도록 설정한 Azure Cosmos DB 계정에 연결
동시 만들기 작업을 통해 데이터 가져오기 수행

필수 조건

이 문서의 지침을 따르기 전에 다음 리소스가 있는지 확인하세요.

활성 Azure 계정. Azure 구독이 없는 경우 시작하기 전에 체험 계정을 만듭니다.

Azure 구독 및 약정 없이 Azure Cosmos DB를 무료로 사용해 볼 수 있습니다. 또는 무료로 처음 1000RU/s와 25GB의 스토리지를 사용하여 Azure Cosmos DB 무료 계층 계정을 만들 수 있습니다. 또한 URI가 https://localhost:8081인 Azure Cosmos DB Emulator를 사용할 수도 있습니다. 에뮬레이터에서 사용할 키는 요청 인증을 참조하세요.
NET Core 3 SDK. dotnet --version을 실행하여 작업 환경에서 사용할 수 있는 버전을 확인할 수 있습니다.

1단계: Azure Cosmos DB 계정 만들기

Azure Portal에서 Azure Cosmos DB for NoSQL 계정을 만들거나 Azure Cosmos DB 에뮬레이터를 사용하여 계정을 만들 수 있습니다.

2단계: .NET 프로젝트 설정

로컬 컴퓨터에서 Windows 명령 프롬프트 또는 터미널 창을 엽니다. 명령 프롬프트 또는 터미널에서 다음 섹션의 명령을 모두 실행합니다. 다음 dotnet new 명령을 실행하여 이름이 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 Portal에 로그인합니다.
Azure Cosmos DB 계정으로 이동합니다.
키 창을 열고 계정의 URI 및 기본 키를 복사합니다.

Azure Cosmos DB 에뮬레이터를 사용하는 경우 이 문서에서 에뮬레이터 자격 증명을 가져옵니다.

5단계: 대량 실행을 지원하여 CosmosClient 개체 초기화

생성된 Program.cs 파일을 코드 편집기에서 엽니다. 대량 실행이 설정된 CosmosClient의 새 인스턴스를 만들고 이 인스턴스를 사용하여 Azure Cosmos DB에 대한 작업을 수행합니다.

먼저 기본 Main 메서드를 덮어쓰고 전역 변수를 정의합니다. 이러한 전역 변수에는 엔드포인트 및 인증 키, 데이터베이스 이름, 만들 컨테이너 및 대량으로 삽입할 항목의 수가 포함됩니다. 작업 환경에 따라 엔드포인트 URL 및 인증 키 값을 바꾸어야 합니다.

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/s로 정의하고, 모든 필드를 제외하여 쓰기 처리량을 최적화하는 사용자 지정 인덱싱 정책을 정의합니다. 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 클래스 내에 도우미 함수를 만듭니다. 이 도우미 함수는 삽입하도록 정의한 항목 수를 가져오고 임의의 데이터를 생성합니다.

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로 마이그레이션하기 위한 용량 계획을 수행하려고 하시나요? 용량 계획을 위해 기존 데이터베이스 클러스터에 대한 정보를 사용할 수 있습니다.

기존 데이터베이스 클러스터의 vCore 및 서버의 수만 알고 있는 경우 vCore 또는 vCPU를 사용하여 요청 단위 예측을 참조하세요
현재 데이터베이스 워크로드에 대한 일반적인 요청 비율을 알고 있는 경우 Azure Cosmos DB 용량 계획 도구를 사용하여 요청 단위 예측에 대해 읽어보세요.

다음을 통해 공유