빠른 시작: MongoDB 드라이버를 사용하는 .NET용 Azure Cosmos DB for MongoDB

적용 대상: MongoDB

MongoDB를 시작하여 Azure Cosmos DB 리소스 내에서 데이터베이스, 컬렉션 및 문서를 만듭니다. Azure 개발자 CLI를 사용하여 환경에 최소 솔루션을 배포하려면 다음 단계를 따릅니다.

MongoDB용 API 참조 설명서 | MongoDB 패키지(NuGet) 패키지/Microsoft.Azure.Cosmos) | Azure 개발자 CLI

필수 조건

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

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

설정

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

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

   

---

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

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

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

   cd ./src/web
   

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

   dotnet add package MongoDb.Driver
   

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

   dotnet add package Azure.Identity
   

개체 모델

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

맨 위에 있는 Azure Cosmos DB 계정을 보여 주는 계층 다이어그램. 계정에는 두 개의 분할된 자식 데이터베이스가 있습니다. 분할된 데이터베이스 중 하나에는 두 개의 자식 컬렉션 분할이 포함되어 있습니다. 다른 분할된 데이터베이스에는 단일 자식 컬렉션 분할이 포함됩니다. 단일 컬렉션 분할된 데이터베이스에는 세 개의 자식 문서 분할된 데이터베이스가 있습니다.

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

• MongoClient - 이 클래스는 Azure Cosmos DB에서 API for MongoDB 계층에 대한 클라이언트 쪽 논리적 표현을 제공합니다. 이 클라이언트 개체는 서비스에 대한 요청을 구성하고 실행하는 데 사용됩니다.
• MongoDatabase - 이 클래스는 아직 서비스에 있거나 없을 수도 있는 데이터베이스에 대한 참조입니다. 데이터베이스에 액세스하거나 이에 대한 작업을 수행하려고 하면 서버 쪽에서 데이터베이스의 유효성이 검사됩니다.
• Collection - 이 클래스는 아직 서비스에 없을 수도 있는 컬렉션에 대한 참조입니다. 관련 작업을 시도하면 서버 쪽에서 컬렉션의 유효성이 검사됩니다.

코드 예제

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

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

클라이언트 인증

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

using MongoDB.Driver;

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

// New instance of CosmosClient class
var client = new MongoClient(Environment.GetEnvironmentVariable("MONGO_CONNECTION"));

데이터베이스 만들기

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

// Database reference with creation if it does not already exist
var db = client.GetDatabase("adventure");

컬렉션 만들기

MongoDatabase.GetCollection은 컬렉션이 아직 없는 경우 새 컬렉션을 만들고 컬렉션에 대한 참조를 반환합니다.

// Container reference with creation if it does not alredy exist
var _products = db.GetCollection<Product>("products");

항목 만들기

새 항목을 컬렉션에 만드는 가장 쉬운 방법은 JSON으로 직렬화하려는 모든 멤버가 포함된 C# 클래스 또는 레코드 형식을 만드는 것입니다. 다음 예제의 C# 레코드에는 고유 식별자, 파티션 키에 대한 category 필드, 추가 name, quantity 및 sale 필드가 있습니다.

public record Product(
    string Id,
    string Category,
    string Name,
    int Quantity,
    bool Sale
);

IMongoCollection<TDocument>.InsertOne을 호출해 Product 레코드를 사용하여 컬렉션에 항목을 만듭니다.

// Create new object and upsert (create or replace) to container
_products.InsertOne(new Product(
    Guid.NewGuid().ToString(),
    "gear-surf-surfboards",
    "Yamba Surfboard", 
    12, 
    false
));

항목 가져오기

Azure Cosmos DB에서 Linq를 사용해 쿼리를 작성하여 항목을 검색할 수 있습니다. SDK에서 IMongoCollection.FindAsync<>를 호출하고 C# 식을 전달하여 결과를 필터링합니다.

// Read a single item from container
var product = (await _products.FindAsync(p => p.Name.Contains("Yamba"))).FirstOrDefault();
Console.WriteLine("Single product:");
Console.WriteLine(product.Name);

쿼리 항목

항목을 삽입한 후 컬렉션을 IQueryable로 처리하여 특정 필터와 일치하는 모든 항목을 가져오는 쿼리를 실행할 수 있습니다. 이 예제에서는 식을 사용하여 제품을 범주별로 필터링합니다. AsQueryable에 대한 호출이 완료되면 MongoQueryable.Where를 호출하여 필터링된 항목 세트를 검색합니다.

// Read multiple items from container
_products.InsertOne(new Product(
    Guid.NewGuid().ToString(),
    "gear-surf-surfboards",
    "Sand Surfboard",
    4,
    false
));

var products = _products.AsQueryable().Where(p => p.Category == "gear-surf-surfboards");

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

코드 실행

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

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

dotnet run

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

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

리소스 정리

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

Azure CLI/ Resource Manager 템플릿

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

az group delete --name $resourceGroupName

PowerShell

Remove-AzResourceGroup cmdlet을 사용하여 리소스 그룹을 삭제합니다.

$parameters = @{
    Name = $RESOURCE_GROUP_NAME
}
Remove-AzResourceGroup @parameters

포털

1. Azure Portal에서 이전에 만든 리소스 그룹으로 이동합니다.

   팁

   이 빠른 시작에서는 msdocs-cosmos-quickstart-rg 이름이 권장되었습니다.

2. 리소스 그룹 삭제를 선택합니다.

   

3. 삭제하시겠나요? 대화 상자에서 리소스 그룹의 이름을 입력한 다음, 삭제를 선택합니다.