빠른 시작: .NET용 Azure Cosmos DB SQL API 클라이언트 라이브러리

적용 대상: SQL API

.NET용 Azure Cosmos DB 클라이언트 라이브러리를 시작하여 계정 내에서 데이터베이스, 컨테이너 및 항목을 만듭니다. 다음 단계에 따라 패키지를 설치하고 기본 작업에 대한 예제 코드를 사용해 보세요.

참고

예제 코드 조각은 GitHub에서 .NET 프로젝트로 사용할 수 있습니다.

API 참조 설명서 | 라이브러리 소스 코드 | 패키지(NuGet) | 샘플

사전 요구 사항

필수 구성 요소 확인

  • 터미널 또는 명령 창에서 dotnet --version을 실행하여 .NET SDK가 버전 6.0 이상인지 확인합니다.
  • az --version(Azure CLI) 또는 Get-Module -ListAvailable AzureRM(Azure PowerShell)을 실행하여 적절한 Azure 명령줄 도구가 설치되어 있는지 확인합니다.

설치

이 섹션에서는 Azure Cosmos 계정을 만들고 .NET용 Azure Cosmos DB SQL API 클라이언트 라이브러리를 사용하여 리소스를 관리하는 프로젝트를 설정하는 과정을 안내합니다.

Azure Cosmos DB 계정 만들기

이 빠른 시작에서는 SQL API를 사용하여 단일 Azure Cosmos DB 계정을 만듭니다.

  1. accountName, resourceGroupNamelocation에 대한 셸 변수를 만듭니다.

    # Variable for resource group name
    resourceGroupName="msdocs-cosmos-quickstart-rg"
    location="westus"
    
    # Variable for account name with a randomnly generated suffix
    let suffix=$RANDOM*$RANDOM
    accountName="msdocs-$suffix"
    
  2. 아직 로그인하지 않은 경우 az login 명령을 사용하여 Azure CLI에 로그인합니다.

  3. az group create 명령을 사용하여 새 리소스 그룹을 구독에 만듭니다.

    az group create \
        --name $resourceGroupName \
        --location $location
    
  4. az cosmosdb create 명령을 사용하여 기본 설정으로 새 Azure Cosmos DB SQL API 계정을 만듭니다.

    az cosmosdb create \
        --resource-group $resourceGroupName \
        --name $accountName \
        --locations regionName=$location
    
  5. az cosmosdb show 명령을 사용하여 계정에 대한 SQL API 엔드포인트 URI를 가져옵니다.

    az cosmosdb show \
        --resource-group $resourceGroupName \
        --name $accountName \
        --query "documentEndpoint"
    
  6. az-cosmosdb-keys-list 명령을 사용하여 계정에 대한 키 목록에서 기본 키를 찾습니다.

    az cosmosdb keys list \
        --resource-group $resourceGroupName \
        --name $accountName \
        --type "keys" \
        --query "primaryMasterKey"
    
  7. URI기본 키 값을 기록합니다. 이러한 자격 증명은 나중에 사용합니다.

새 .NET 앱 만들기

원하는 터미널을 사용하여 새 .NET 애플리케이션을 빈 폴더에 만듭니다. console 템플릿을 지정한 dotnet new 명령을 사용합니다.

dotnet new console

패키지 설치

Microsoft.Azure.Cosmos NuGet 패키지를 .NET 프로젝트에 추가합니다. NuGet 패키지의 이름을 지정한 dotnet add package 명령을 사용합니다.

dotnet add package Microsoft.Azure.Cosmos

dotnet build 명령을 사용하여 프로젝트를 빌드합니다.

dotnet build

빌드가 오류 없이 성공했는지 확인합니다. 이 빌드의 예상 출력은 다음과 같습니다.

  Determining projects to restore...
  All projects are up-to-date for restore.
  dslkajfjlksd -> C:\Users\sidandrews\Demos\dslkajfjlksd\bin\Debug\net6.0\dslkajfjlksd.dll

Build succeeded.
    0 Warning(s)
    0 Error(s)

환경 변수 구성

.NET 코드 내에서 URI기본 키 값을 사용하려면 애플리케이션을 실행하는 로컬 컴퓨터의 새 환경 변수에 유지합니다. 환경 변수를 설정하려면 원하는 터미널을 사용하여 다음 명령을 실행합니다.

$env:COSMOS_ENDPOINT = "<cosmos-account-URI>"
$env:COSMOS_KEY = "<cosmos-account-PRIMARY-KEY>"

개체 모델

애플리케이션 빌드를 시작하기 전에 Azure Cosmos DB의 리소스 계층 구조를 살펴보겠습니다. Azure Cosmos DB에는 리소스를 만들고 액세스하는 데 사용되는 특정 개체 모델이 있습니다. Azure Cosmos DB는 리소스를 계정, 데이터베이스, 컨테이너 및 항목으로 구성된 계층 구조에 만듭니다.

Diagram of the Azure Cosmos D B hierarchy including accounts, databases, containers, and items.

Hierarchical diagram showing an Azure Cosmos D B account at the top. The account has two child database nodes. One of the database nodes includes two child container nodes. The other database node includes a single child container node. That single container node has three child item nodes.

다양한 리소스의 계층 구조에 대한 자세한 내용은 Azure Cosmos DB의 데이터베이스, 컨테이너 및 항목 작업을 참조하세요.

다음 .NET 클래스를 사용하여 해당 리소스와 상호 작용합니다.

  • CosmosClient - 이 클래스는 Azure Cosmos DB 서비스에 대한 클라이언트 쪽 논리적 표현을 제공합니다. 이 클라이언트 개체는 서비스에 대한 요청을 구성하고 실행하는 데 사용됩니다.
  • Database - 이 클래스는 아직 서비스에 있거나 없을 수도 있는 데이터베이스에 대한 참조입니다. 데이터베이스에 액세스하거나 이에 대한 작업을 수행하려고 하면 서버 쪽에서 데이터베이스의 유효성이 검사됩니다.
  • Container - 이 클래스는 아직 서비스에 없을 수도 있는 컨테이너에 대한 참조입니다. 관련 작업을 시도하면 서버 쪽에서 컨테이너의 유효성이 검사됩니다.
  • QueryDefinition - 이 클래스는 SQL 쿼리 및 쿼리 매개 변수를 나타냅니다.
  • FeedIterator<> - 이 클래스는 현재 결과 페이지를 추적하고 새 결과 페이지를 가져올 수 있는 반복기를 나타냅니다.
  • FeedResponse<> - 이 클래스는 반복기의 단일 응답 페이지를 나타냅니다. 이 형식은 foreach 루프를 사용하여 반복할 수 있습니다.

코드 예제

이 문서에서 설명하는 샘플 코드에서는 products라는 컨테이너를 사용하여 adventureworks라는 데이터베이스를 만듭니다. products 테이블은 이름, 범주, 수량 및 판매 지표와 같은 제품 세부 정보를 포함하도록 설계되었습니다. 각 제품에는 고유 식별자도 포함됩니다.

이 샘플 코드에서는 컨테이너에서 범주를 논리 파티션 키로 사용합니다.

클라이언트 인증

프로젝트 디렉터리에서 Program.cs 파일을 엽니다. 편집기에서 Microsoft.Azure.Cosmos에 대한 using 지시문을 추가합니다.

using Microsoft.Azure.Cosmos;

생성자를 사용하는 CosmosClient 클래스의 새 인스턴스 및 이전에 만든 두 개의 환경 변수를 읽는 Environment.GetEnvironmentVariable를 정의합니다.

// New instance of CosmosClient class
using CosmosClient client = new(
    accountEndpoint: Environment.GetEnvironmentVariable("COSMOS_ENDPOINT")!,
    authKeyOrResourceToken: Environment.GetEnvironmentVariable("COSMOS_KEY")!
);

CosmosClient 인스턴스를 만드는 다양한 방법에 대한 자세한 내용은 Azure Cosmos DB SQL API 및 .NET 시작을 참조하세요.

데이터베이스 만들기

아직 없는 경우 CosmosClient.CreateDatabaseIfNotExistsAsync 메서드를 사용하여 새 데이터베이스를 만듭니다. 이 메서드는 기존 또는 새로 만든 데이터베이스에 대한 참조를 반환합니다.

// Database reference with creation if it does not already exist
Database database = await client.CreateDatabaseIfNotExistsAsync(
    id: "adventureworks"
);

Console.WriteLine($"New database:\t{database.Id}");

데이터베이스를 만드는 방법에 대한 자세한 내용은 .NET을 사용하여 Azure Cosmos DB SQL API에서 데이터베이스 만들기를 참조하세요.

컨테이너 만들기

Database.CreateContainerIfNotExistsAsync는 아직 없는 경우 새 컨테이너를 만듭니다. 이 메서드는 컨테이너에 대한 참조도 반환합니다.

// Container reference with creation if it does not alredy exist
Container container = await database.CreateContainerIfNotExistsAsync(
    id: "products",
    partitionKeyPath: "/category",
    throughput: 400
);

Console.WriteLine($"New container:\t{container.Id}");

컨테이너를 만드는 방법에 대한 자세한 내용은 .NET을 사용하여 Azure Cosmos DB SQL API에서 컨테이너 만들기를 참조하세요.

항목 만들기

새 항목을 컨테이너에 만드는 가장 쉬운 방법은 먼저 JSON으로 직렬화하려는 모든 멤버를 사용하여 C# 클래스 또는 레코드 형식을 빌드하는 것입니다. 다음 예제의 C# 레코드에는 고유 식별자, 파티션 키에 대한 category 필드, 추가 name, quantitysale 필드가 있습니다.

// C# record representing an item in the container
public record Product(
    string id,
    string category,
    string name,
    int quantity,
    bool sale
);

Container.UpsertItemAsync를 호출하여 항목을 컨테이너에 만듭니다. 다음 예제에서는 이 샘플 코드를 두 번 이상 실행하는 경우에 대비하여 새 항목을 만드는 대신 upsert하도록 선택했습니다.

// Create new object and upsert (create or replace) to container
Product newItem = new(
    id: "68719518391",
    category: "gear-surf-surfboards",
    name: "Yamba Surfboard",
    quantity: 12,
    sale: false
);

Product createdItem = await container.UpsertItemAsync<Product>(
    item: newItem,
    partitionKey: new PartitionKey("gear-surf-surfboards")
);

Console.WriteLine($"Created item:\t{createdItem.id}\t[{createdItem.category}]");

항목 만들기, 업서팅 또는 바꾸기에 대한 자세한 내용은 .NET을 사용하여 Azure Cosmos DB SQL API에서 항목 만들기를 참조하세요.

항목 가져오기

Azure Cosmos DB에서는 고유 식별자(id)와 파티션 키 필드를 모두 사용하여 지점 읽기 작업을 수행할 수 있습니다. SDK에서 두 값을 모두 전달하는 Container.ReadItemAsync<>을 호출하여 C# 형식의 역직렬화된 인스턴스를 반환합니다.

// Point read item from container using the id and partitionKey
Product readItem = await container.ReadItemAsync<Product>(
    id: "68719518391",
    partitionKey: new PartitionKey("gear-surf-surfboards")
);

항목을 읽고 응답을 구문 분석하는 방법에 대한 자세한 내용은 .NET을 사용하여 Azure Cosmos DB SQL API에서 항목 읽기를 참조하세요.

쿼리 항목

항목이 삽입되면 특정 필터와 일치하는 모든 항목을 가져오는 쿼리를 실행할 수 있습니다. 다음 예제에서는 SELECT * FROM todo t WHERE t.partitionKey = 'gear-surf-surfboards' SQL 쿼리를 실행합니다. 이 예제에서는 QueryDefinition 형식 및 매개 변수가 있는 쿼리 식을 파티션 키 필터에 사용합니다. 쿼리가 정의되면 Container.GetItemQueryIterator<>를 호출하여 결과 페이지를 관리하는 결과 반복기를 가져옵니다. 그런 다음, whileforeach 루프의 조합을 사용하여 결과 페이지를 검색한 다음, 개별 항목을 반복합니다.

// Create query using a SQL string and parameters
var query = new QueryDefinition(
    query: "SELECT * FROM products p WHERE p.partitionKey = @key"
)
    .WithParameter("@key", "gear-surf-surfboards");

using FeedIterator<Product> feed = container.GetItemQueryIterator<Product>(
    queryDefinition: query
);

while (feed.HasMoreResults)
{
    FeedResponse<Product> response = await feed.ReadNextAsync();
    foreach (Product item in response)
    {
        Console.WriteLine($"Found item:\t{item.name}");
    }
}

코드 실행

이 앱에서는 Azure Cosmos DB SQL API 데이터베이스 및 컨테이너를 만듭니다. 그런 다음, 다음 예제에서 항목을 만든 다음, 정확히 동일한 항목을 다시 읽습니다. 마지막으로 다음 예제에서 해당 단일 항목만 반환해야 하는 쿼리를 실행합니다. 각 단계에서 예제는 수행한 단계에 대한 메타데이터를 콘솔에 출력합니다.

앱을 실행하려면 터미널을 사용하여 애플리케이션 디렉터리로 이동하고 애플리케이션을 실행합니다.

dotnet run

앱의 출력은 다음 예제와 비슷합니다.

New database:   adventureworks
New container:  products
Created item:   68719518391     [gear-surf-surfboards]

리소스 정리

Azure Cosmos DB SQL API 계정이 더 이상 필요하지 않으면 해당 리소스 그룹을 삭제할 수 있습니다.

az group delete 명령을 사용하여 리소스 그룹을 삭제합니다.

az group delete --name $resourceGroupName

다음 단계

이 빠른 시작에서는 Azure Cosmos DB SQL API 계정을 만들고, 데이터베이스를 만들고, .NET SDK를 사용하여 컨테이너를 만드는 방법을 알아보았습니다. 이제 더 많은 데이터를 가져오고, 복잡한 쿼리를 수행하고, Azure Cosmos DB SQL API 리소스를 관리하기 위해 SDK에 대해 자세히 알아볼 수 있습니다.