빠른 시작: .NET용 Azure Cosmos DB for NoSQL 라이브러리

적용 대상: NoSQL

• .NET
• Node.js
• Java
• Python
• Go

.NET용 Azure Cosmos DB for NoSQL 클라이언트 라이브러리를 시작하여 컨테이너의 데이터를 쿼리하고 개별 항목에 대한 일반적인 작업을 수행합니다. Azure 개발자 CLI를 사용하여 환경에 최소 솔루션을 배포하려면 다음 단계를 따릅니다.

API 참조 설명서 | 라이브러리 소스 코드 | 패키지(NuGet) | Azure 개발자 CLI

필수 조건

• 활성 구독이 있는 Azure 계정. 체험 계정을 만듭니다.
• GitHub 계정

• 활성 구독이 있는 Azure 계정. 체험 계정을 만듭니다.
• Azure Developer CLI
• Docker Desktop

설정

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

Important

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

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

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

   azd auth login
   

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

   azd init --template cosmos-db-nosql-dotnet-quickstart
   

   참고 항목

   이 빠른 시작은 azure-samples/cosmos-db-nosql-dotnet-quickstart 템플릿 GitHub 리포지토리를 사용합니다. Azure 개발자 CLI는 이 프로젝트가 아직 없는 경우 컴퓨터에 자동으로 복제합니다.

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

   팁

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

5. azd up을 사용하여 Azure 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을 사용하여 브라우저에서 웹 애플리케이션으로 이동합니다. 실행 중인 앱의 출력을 관찰합니다.

   

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

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

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

   cd ./src/web
   

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

   dotnet add package Microsoft.Azure.Cosmos --version 3.*
   

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

   dotnet add package Azure.Identity --version 1.12.*
   

4. src/web/Cosmos.Samples.NoSQL.Quickstart.Web.csproj 파일을 열고 검토하여 Microsoft.Azure.Cosmos 및 Azure.Identity 항목이 모두 존재하는지 유효성을 검사합니다.

개체 모델

이름	설명
CosmosClient	이 클래스는 기본 클라이언트 클래스이며 계정 전체의 메타데이터 또는 데이터베이스를 관리하는 데 사용됩니다.
Database	이 클래스는 계정 내의 데이터베이스를 나타냅니다.
Container	이 클래스는 주로 컨테이너 또는 컨테이너 내에 저장된 항목에 대해 읽기, 업데이트 및 삭제 작업을 수행하는 데 사용됩니다.
PartitionKey	이 클래스는 논리 파티션 키를 나타냅니다. 이 클래스는 많은 일반적인 작업 및 쿼리에 필요합니다.

코드 예제

• 클라이언트 인증
• 데이터베이스 가져오기
• 컨테이너 가져오기
• 항목 만들기
• 항목 가져오기
• 쿼리 항목

템플릿의 샘플 코드는 cosmicworks라는 데이터베이스와 products라는 컨테이너를 사용합니다. products 컨테이너에는 각 제품의 이름, 범주, 수량, 고유 식별자 및 판매 플래그와 같은 세부 정보가 포함되어 있습니다. 컨테이너는 /category 속성을 논리 파티션 키로 사용합니다.

클라이언트 인증

대부분의 Azure 서비스에 대한 애플리케이션 요청은 승인되어야 합니다. 애플리케이션과 Azure Cosmos DB for NoSQL 간에 암호 없는 연결을 구현하는 기본 방법으로 DefaultAzureCredential 형식을 사용합니다. DefaultAzureCredential은 여러 인증 방법을 지원하고 런타임에 사용해야 하는 방법을 결정합니다.

Important

암호, 연결 문자열 또는 기타 자격 증명을 직접 사용하여 Azure 서비스에 대한 요청에 권한을 부여할 수도 있습니다. 그러나 이 방법은 신중하게 사용해야 합니다. 개발자는 이러한 비밀을 안전하지 않은 위치에 절대 노출하지 않도록 끊임없이 노력해야 합니다. 암호나 비밀 키에 액세스할 수 있는 사용자는 누구나 데이터베이스 서비스에 인증할 수 있습니다. DefaultAzureCredential은 계정 키에 비해 개선된 관리 및 보안 이점을 제공하므로 키를 저장할 위험 없이 암호 없는 인증이 가능합니다.

이 샘플은 CosmosClient 클래스의 새 인스턴스를 만들고 DefaultAzureCredential 인스턴스를 사용하여 인증합니다.

DefaultAzureCredential credential = new();

CosmosClient client = new(
    accountEndpoint: "<azure-cosmos-db-nosql-account-endpoint>",
    tokenCredential: new DefaultAzureCredential()
);

데이터베이스 가져오기

client.GetDatabase를 사용하여 cosmicworks라는 기존 데이터베이스를 검색합니다.

Database database = client.GetDatabase("cosmicworks");

컨테이너 가져오기

database.GetContainer를 사용하여 기존 products 컨테이너를 검색합니다.

Container container = database.GetContainer("products");

항목 만들기

JSON으로 직렬화하려는 모든 멤버를 사용하여 C# 레코드 종류를 빌드합니다. 이 예에서 형식에는 고유 식별자와 범주, 이름, 수량, 가격 및 판매에 대한 필드가 있습니다.

public record Product(
    string id,
    string category,
    string name,
    int quantity,
    decimal price,
    bool clearance
);

container.UpsertItem을 사용하여 컨테이너에 항목을 만듭니다. 이 방법은 항목이 이미 존재하는 경우 해당 항목을 효과적으로 바꿔 해당 항목을 "upsert"합니다.

Product item = new(
    id: "68719518391",
    category: "gear-surf-surfboards",
    name: "Yamba Surfboard",
    quantity: 12,
    price: 850.00m,
    clearance: false
);

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

항목 읽기

고유 식별자(id)와 파티션 키 필드를 모두 사용하여 포인트 읽기 작업을 수행합니다. 특정 항목을 효율적으로 검색하려면 container.ReadItem을 사용합니다.

ItemResponse<Product> response = await container.ReadItemAsync<Product>(
    id: "68719518391",
    partitionKey: new PartitionKey("gear-surf-surfboards")
);

쿼리 항목

container.GetItemQueryIterator를 사용하여 컨테이너의 여러 항목에 대해 쿼리를 수행합니다. 다음 매개 변수가 있는 쿼리를 사용하여 지정된 범주 내의 모든 항목을 찾습니다.

SELECT * FROM products p WHERE p.category = @category

string query = "SELECT * FROM products p WHERE p.category = @category"

var query = new QueryDefinition(query)
  .WithParameter("@category", "gear-surf-surfboards");

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

feed.ReadNextAsync를 사용하여 결과의 각 페이지를 반복하여 페이지가 매겨진 쿼리 결과를 구문 분석합니다. 각 루프 시작 시 결과가 남아 있는지 확인하려면 feed.HasMoreResults를 사용합니다.

List<Product> items = new();
while (feed.HasMoreResults)
{
    FeedResponse<Product> response = await feed.ReadNextAsync();
    foreach (Product item in response)
    {
        items.Add(item);
    }
}

리소스 정리

샘플 애플리케이션이나 리소스가 더 이상 필요하지 않으면 해당 배포와 모든 리소스를 제거합니다.

azd down

GitHub Codespaces에서 실행 중인 codespace를 삭제하여 스토리지 및 핵심 권한을 최대화합니다.

관련 콘텐츠

• Node.js 빠른 시작
• Python 빠른 시작
• Java 빠른 시작
• 빠른 시작으로 이동