빠른 시작: .NET용 Azure Cosmos DB for Table

적용 대상: 테이블

이 빠른 시작에서는 .NET 애플리케이션에서 Azure Cosmos DB for Table을 시작하는 방법을 보여 줍니다. 테이블용 Azure Cosmos DB는 애플리케이션이 구조화된 테이블 데이터를 클라우드에 저장할 수 있도록 하는 스키마 없는 데이터 저장소입니다. Azure.Data.Tables 패키지(NuGet)를 사용하여 Azure Cosmos DB 리소스 내에서 테이블, 행을 만들고 기본 작업을 수행하는 방법을 알아봅니다.

참고 항목

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

Table용 API 참조 설명서 | Azure.Data.Tables 패키지(NuGet)

필수 조건

설정

이 프로젝트의 개발 컨테이너를 환경에 배포합니다. 그런 다음 Azure 개발자 CLI(azd)를 사용하여 테이블용 Azure Cosmos DB 계정을 만들고 컨테이너화된 샘플 애플리케이션을 배포합니다. 샘플 애플리케이션은 클라이언트 라이브러리를 사용하여 샘플 데이터를 관리, 만들기, 읽기 및 쿼리합니다.

Open in GitHub Codespaces

Open in Dev Container

Important

GitHub 계정에는 무료로 스토리지 및 핵심 시간에 대한 권한이 포함됩니다. 자세한 내용은 GitHub 계정에 포함된 스토리지 및 핵심 시간을 참조하세요.

  1. 프로젝트의 루트 디렉터리에서 터미널을 엽니다.

  2. azd auth login을 사용하여 Azure 개발자 CLI에 인증합니다. 원하는 Azure 자격 증명을 사용하여 CLI에 인증하려면 도구에 지정된 단계를 따릅니다.

    azd auth login
    
  3. 프로젝트를 초기화하려면 azd init를 사용합니다.

    azd init
    
  4. 초기화 중에 고유한 환경 이름을 구성합니다.

    환경 이름은 대상 리소스 그룹 이름으로도 사용됩니다. 이 빠른 시작에서는 msdocs-cosmos-db 사용을 고려해보세요.

  5. 를 사용하여 azd upAzure Cosmos DB 계정을 배포합니다. Bicep 템플릿은 샘플 웹 애플리케이션도 배포합니다.

    azd up
    
  6. 프로비전 과정에서 구독과 원하는 위치를 선택합니다. 프로비저닝 프로세스가 완료될 때까지 기다립니다. 이 과정은 약 5분 정도 소요됩니다.

  7. Azure 리소스 프로비전이 완료되면 실행 중인 웹 애플리케이션에 대한 URL이 출력에 포함됩니다.

    Deploying services (azd deploy)
    
      (✓) Done: Deploying service web
    - Endpoint: <https://[container-app-sub-domain].azurecontainerapps.io>
    
    SUCCESS: Your application was provisioned and deployed to Azure in 5 minutes 0 seconds.
    
  8. 콘솔의 URL을 사용하여 브라우저에서 웹 애플리케이션으로 이동합니다. 실행 중인 앱의 출력을 관찰합니다.

    Screenshot of the running web application.

클라이언트 라이브러리 설치

클라이언트 라이브러리는 NuGet을 통해 Microsoft.Azure.Cosmos 패키지로 사용할 수 있습니다.

  1. 터미널을 열고 /src/web 폴더로 이동합니다.

    cd ./src/web
    
  2. 아직 설치되지 않은 경우 dotnet add package을 사용하여 Microsoft.Azure.Cosmos 패키지를 설치합니다.

    dotnet add package Microsoft.Azure.Cosmos
    
  3. 또한 아직 설치되지 않은 경우 Azure.Identity 패키지를 설치합니다.

    dotnet add package Azure.Identity
    
  4. src/web/Cosmos.Samples.Table.Quickstart.Web.csproj 파일을 열고 검토하여 해당 파일과 Azure.Identity 항목이 Microsoft.Azure.Cosmos 모두 존재하는지 확인합니다.

코드 예제

이 문서에서 설명하는 샘플 코드에서는 adventureworks라는 테이블을 만듭니다. 각 테이블 행에는 이름, 범주, 수량 및 판매 지표와 같은 제품의 세부 정보가 포함됩니다. 각 제품에는 고유 식별자도 포함됩니다.

다음 Table용 API 클래스를 사용하여 이러한 리소스와 상호 작용합니다.

  • TableServiceClient - 이 클래스는 Azure Cosmos DB for Table을 사용하여 서비스 수준 작업을 수행하는 메서드를 제공합니다.
  • TableClient - 이 클래스를 사용하면 Azure Cosmos DB Table API에서 호스트되는 테이블과 상호 작용할 수 있습니다.
  • TableEntity - 이 클래스는 속성 및 열 데이터를 관리할 수 있는 테이블의 행에 대한 참조입니다.

클라이언트 인증

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

using Azure.Data.Tables;

생성자를 사용하여 TableServiceClient 클래스의 새 인스턴스를 정의하고 이전에 설정한 연결 문자열을 읽기 위해 Environment.GetEnvironmentVariable을 정의합니다.

// New instance of the TableClient class
TableServiceClient tableServiceClient = new TableServiceClient(Environment.GetEnvironmentVariable("COSMOS_CONNECTION_STRING"));

테이블 만들기

TableServiceClient 클래스를 사용하여 TableClient의 인스턴스를 검색합니다. 아직 없는 경우 TableClient에서 TableClient.CreateIfNotExistsAsync 메서드를 사용하여 새 테이블을 만듭니다. 이 메서드는 기존 또는 새로 만든 테이블에 대한 참조를 반환합니다.

// New instance of TableClient class referencing the server-side table
TableClient tableClient = tableServiceClient.GetTableClient(
    tableName: "adventureworks"
);

await tableClient.CreateIfNotExistsAsync();

항목 만들기

테이블에서 새 항목을 만드는 가장 쉬운 방법은 ITableEntity 인터페이스를 구현하는 클래스를 만드는 것입니다. 그런 다음, 사용자 고유의 속성을 클래스에 추가하여 해당 테이블 행의 데이터 열을 채울 수 있습니다.

// C# record type for items in the table
public record Product : ITableEntity
{
    public string RowKey { get; set; } = default!;

    public string PartitionKey { get; set; } = default!;

    public string Name { get; init; } = default!;

    public int Quantity { get; init; }

    public bool Sale { get; init; }

    public ETag ETag { get; set; } = default!;

    public DateTimeOffset? Timestamp { get; set; } = default!;
}

TableClient.AddEntityAsync<T>를 호출하여 Product 클래스를 사용하는 컬렉션에 항목을 만듭니다.

// Create new item using composite key constructor
var prod1 = new Product()
{
    RowKey = "68719518388",
    PartitionKey = "gear-surf-surfboards",
    Name = "Ocean Surfboard",
    Quantity = 8,
    Sale = true
};

// Add new item to server-side table
await tableClient.AddEntityAsync<Product>(prod1);

항목 가져오기

TableEntity.GetEntityAsync<T> 메서드를 사용하여 테이블에서 특정 항목을 검색할 수 있습니다. 해당 항목의 빠른 지점 읽기를 수행하기 위해 올바른 행을 식별하는 매개 변수로 partitionKeyrowKey를 제공합니다.

// Read a single item from container
var product = await tableClient.GetEntityAsync<Product>(
    rowKey: "68719518388",
    partitionKey: "gear-surf-surfboards"
);
Console.WriteLine("Single product:");
Console.WriteLine(product.Value.Name);

쿼리 항목

항목이 삽입되면 TableClient.Query<T> 메서드를 사용하여 특정 필터와 일치하는 모든 항목을 가져오는 쿼리를 실행할 수도 있습니다. 이 예제에서는 Linq 구문을 사용하여 범주별로 제품을 필터링합니다. 이는 Product 클래스와 같은 형식의 ITableEntity 모델을 사용하는 경우의 이점입니다.

참고 항목

OData 구문을 사용하여 항목을 쿼리할 수도 있습니다. 데이터 쿼리 가이드에서 이 방법의 예제를 확인할 수 있습니다.

// Read multiple items from container
var prod2 = new Product()
{
    RowKey = "68719518390",
    PartitionKey = "gear-surf-surfboards",
    Name = "Sand Surfboard",
    Quantity = 5,
    Sale = false
};

await tableClient.AddEntityAsync<Product>(prod2);

var products = tableClient.Query<Product>(x => x.PartitionKey == "gear-surf-surfboards");

Console.WriteLine("Multiple products:");
foreach (var item in products)
{
    Console.WriteLine(item.Name);
}

코드 실행

이 앱은 Azure Cosmos DB Table API 테이블을 만듭니다. 그런 다음, 다음 예제에서 항목을 만든 다음, 정확히 동일한 항목을 다시 읽습니다. 마지막으로, 예제에서 두 번째 항목을 만든 다음, 여러 항목을 반환해야 하는 쿼리를 수행합니다. 각 단계에서 예제는 수행한 단계에 대한 메타데이터를 콘솔에 출력합니다.

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

dotnet run

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

Single product name: 
Yamba Surfboard
Multiple products:
Yamba Surfboard
Sand Surfboard

리소스 정리

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

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

az group delete --name $resourceGroupName

다음 단계

이 빠른 시작에서는 .NET SDK를 사용하여 Azure Cosmos DB for Table 계정을 만들고, 테이블을 만들고, 항목을 관리하는 방법을 알아보았습니다. 이제 SDK를 더 자세히 알아보고, Azure Cosmos DB for Table 리소스에서 고급 데이터 쿼리 및 관리 작업을 수행하는 방법을 알아볼 수 있습니다.