다음을 통해 공유

Azure Cosmos DB에 Node.js Mongoose 애플리케이션 연결

  • 아티클

적용 대상: MongoDB

이 자습서에서는 Azure Cosmos DB에 데이터를 저장할 때 Mongoose 프레임워크를 사용하는 방법을 보여 줍니다. 이 연습에서는 Azure Cosmos DB의 API for MongoDB를 사용합니다. 잘 모르는 사람도 있겠지만, Mongoose는 Node.js에 있는 MongoDB용 개체 모델링 프레임워크이며 애플리케이션 데이터를 모델링하기 위한 간단한 스키마 기반 솔루션을 제공합니다.

Azure Cosmos DB는 Microsoft의 세계적으로 유통된 멀티 모델 데이터베이스 서비스입니다. Azure Cosmos DB의 핵심인 전역 배포 및 수평적 크기 조정 기능의 이점을 활용하여 문서, 키/값 및 그래프 데이터베이스를 빠르게 만들고 쿼리할 수 있습니다.

필수 조건

Azure를 구독하고 있지 않다면 시작하기 전에 Azure 체험 계정을 만듭니다.

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

Node.js 버전 v0.10.29 이상

Azure Cosmos DB 계정 만들기

Azure Cosmos DB 계정을 만들어 보겠습니다. 사용하려는 계정이 이미 있는 경우 Node.js 애플리케이션 설치로 건너뛸 수 있습니다. Azure Cosmos DB 에뮬레이터를 사용하는 경우 Azure Cosmos DB 에뮬레이터의 단계에 따라 에뮬레이터를 설정하고 Node.js 애플리케이션 설정으로 건너뜁니다.

  1. 새 브라우저 창에서 Azure Portal에 로그인합니다.

  2. 왼쪽 메뉴에서 + 리소스 만들기를 선택합니다.

    Azure Portal에서 리소스를 만드는 스크린샷

  3. 새로 만들기 페이지에서 데이터베이스>Azure Cosmos DB를 차례로 선택합니다.

    Azure Portal 데이터베이스 창의 스크린샷.

  4. API 옵션 선택 페이지에서 Azure Cosmos DB for MongoDB>만들기를 선택합니다.

    API는 만들 계정의 형식을 결정합니다. 이 빠른 시작에서는 MongoDB에서 사용하는 컬렉션을 만들기 때문에 Azure Cosmos DB for MongoDB를 선택합니다. 자세한 내용은 Azure Cosmos DB for MongoDB 개요를 참조하세요.

    API 선택 옵션 창의 스크린샷

  5. Azure Cosmos DB 계정 만들기 페이지에서 새 Azure Cosmos DB 계정에 대한 설정을 입력합니다.

    설정 값 Description
    구독 구독 이름 이 Azure Cosmos DB 계정에 사용할 Azure 구독을 선택합니다.
    리소스 그룹 리소스 그룹 이름 리소스 그룹을 선택하거나 새로 만들기를 선택한 후, 새 리소스 그룹에 고유한 이름을 입력합니다.
    계정 이름 고유한 이름 입력 내 Azure Cosmos DB 계정을 식별하는 고유한 이름을 입력합니다. 계정 URI는 고유한 계정 이름에 mongo.cosmos.azure.com이 추가됩니다.

    계정 이름은 소문자, 숫자 및 하이픈(-) 문자만 포함할 수 있으며, 3-44자여야 합니다.
    위치 사용자와 가장 가까운 지역 Azure Cosmos DB 계정을 호스트할 지리적 위치를 선택합니다. 데이터에 가장 빨리 액세스할 수 있도록 사용자와 가장 가까운 위치를 사용합니다.
    용량 모드 프로비저닝된 처리량 또는 서버리스 프로비저닝된 처리량을 선택하여 프로비저닝된 처리량 모드에서 계정을 만듭니다. 서버리스를 선택하여 서버리스 모드에서 계정을 만듭니다.

    참고: API for MongoDB 버전 4.2, 4.0 및 3.6만 서버리스 계정에서 지원합니다. 3.2 버전을 선택하면 계정이 프로비저닝된 처리량 모드로 강제 적용됩니다.
    Azure Cosmos DB 체험 계층 할인 적용 적용 또는 적용 안 함 Azure Cosmos DB 무료 계층을 사용하면 계정 하나에 처음 1000RU/초 및 25GB의 스토리지가 별도의 비용 없이 제공됩니다. 체험 계층에 대해 자세히 알아보세요.
    버전 필요한 서버 버전 선택 Azure Cosmos DB for MongoDB는 서버 버전 4.2, 4.0, 3.6 및 3.2와 호환됩니다. 계정을 만든 후 업그레이드하거나 다운그레이드할 수 있습니다.

    참고 항목

    Azure 구독당 최대 1개의 체험 계층 Azure Cosmos DB 계정을 사용할 수 있으며 계정을 만들 때 옵트인해야 합니다. 체험 계층 할인을 적용하는 옵션이 표시되지 않으면 구독의 다른 계정에서 이미 체험 계층을 사용하도록 설정되었음을 의미합니다.

    Azure Cosmos DB에 대한 새 계정 페이지의 스크린샷

  6. 전역 배포 탭에서 다음 세부 정보를 구성합니다. 이 빠른 시작의 목적을 위해 기본값을 그대로 둘 수 있습니다.

    설정 값 Description
    지리적 중복 사용 안 함 지역에 쌍 영역을 페어링하여 계정에서 글로벌 배포를 사용하거나 사용하지 않도록 설정합니다. 나중에 계정에 더 많은 지역을 추가할 수 있습니다.
    다중 지역 쓰기 사용 안 함 다중 영역 쓰기 기능을 사용하면 전 세계의 데이터베이스 및 컨테이너에 대해 프로비저닝된 처리량을 활용할 수 있습니다.

    참고 항목

    용량 모드로 서버리스를 선택한 경우 다음 옵션을 사용할 수 없습니다.

    • 무료 계층 할인 적용
    • 지리적 중복도
    • 다중 지역 쓰기

  7. 필요에 따라 다음 탭에서 추가 세부 정보를 구성할 수 있습니다.

    • 네트워킹 - 가상 네트워크에서 액세스를 구성합니다.
    • 백업 정책 - 주기적 또는 지속적인 백업 정책을 구성합니다.
    • 암호화 - 서비스 관리형 키 또는 고객 관리형 키를 사용합니다.
    • 태그 - 태그는 동일한 태그를 여러 개의 리소스 및 리소스 그룹에 적용하여 리소스를 범주화하고 통합된 청구를 볼 수 있는 이름/값 쌍입니다.

  8. 검토 + 만들기를 선택합니다.

  9. 계정 생성에는 몇 분 정도가 소요됩니다. 포털에 축하합니다! Azure Cosmos DB for MongoDB 계정이 준비되었습니다. 페이지가 표시될 때까지 기다리세요.

    Azure Portal 알림 창의 스크린샷.

데이터베이스 만들기

이 애플리케이션에서는 Azure Cosmos DB에서 컬렉션을 만드는 두 가지 방법을 설명하려고 합니다.

  • 별도 컬렉션에 각 개체 모델 저장: 전용 처리량을 사용하여 데이터베이스를 만드는 것이 좋습니다. 이 용량 모델을 사용하면 더 나은 비용 효율성을 얻을 수 있습니다.

    Node.js 자습서 - Mongoose Node 모듈에서 사용할 수 있도록 Azure Cosmos DB 계정에 대한 Data Explorer에서 데이터베이스를 만드는 방법을 보여 주는 Azure Portal의 스크린샷

  • 단일 Azure Cosmos DB 컬렉션에 모든 개체 모델 저장: 모든 모델을 단일 컬렉션에 저장하려면 처리량 프로비저닝 옵션을 선택하지 않고 새 데이터베이스를 만들 수 있습니다. 이 용량 모델을 사용하면 모든 개체 모델에 대해 고유한 처리량 용량으로 각 컬렉션이 생성됩니다.

데이터베이스를 만든 후에는 아래의 COSMOSDB_DBNAME 환경 변수에서 해당 이름을 사용합니다.

Node.js 애플리케이션 설정

참고 항목

애플리케이션 자체를 설정하는 대신 샘플 코드를 연습하려는 경우 이 자습서에 사용되는 샘플을 복제하고 Azure Cosmos DB에서 Node.js Mongoose 애플리케이션을 빌드합니다.

  1. 선택한 폴더에 Node.js 애플리케이션을 만들려면 노드 명령 프롬프트에서 다음 명령을 실행합니다.

    npm init

    질문에 답변하면 프로젝트를 이동할 준비가 됩니다.

  2. 폴더에 새 파일을 추가하고 이름을 index.js로 지정합니다.

  3. npm install 옵션 중 하나를 사용하여 필요한 패키지를 설치합니다.

    • Mongoose: npm install mongoose --save

    참고 항목

    MongodB용 API 서버 버전과 호환되는 mongoose 버전에 대한 자세한 내용은 Mongoose 호환성을 참조하세요.

    • Dotenv(.env 파일에서 비밀을 로드하려는 경우)npm install dotenv --save

      참고 항목

      --save 플래그는 package.json 파일에 종속성을 추가합니다.

  4. index.js 파일에서 종속성을 가져옵니다.

    var mongoose = require('mongoose');
var env = require('dotenv').config();   //Use the .env file to load the variables

  5. Azure Cosmos DB 연결 문자열과 Azure Cosmos DB 이름을 .env 파일에 추가합니다. 자리 표시자 {cosmos-account-name} 및 {dbname}을 중괄호 기호 없이 고유한 Azure Cosmos DB 계정 이름 및 데이터베이스 이름으로 바꿉니다.

    // You can get the following connection details from the Azure portal. You can find the details on the Connection string pane of your Azure Cosmos DB account.

COSMOSDB_USER = "<Azure Cosmos DB account's user name, usually the database account name>"
COSMOSDB_PASSWORD = "<Azure Cosmos DB account password, this is one of the keys specified in your account>"
COSMOSDB_DBNAME = "<Azure Cosmos DB database name>"
COSMOSDB_HOST= "<Azure Cosmos DB Host name>"
COSMOSDB_PORT=10255

  6. index.js의 끝에 다음 코드를 추가하여 Mongoose 프레임워크로 Azure Cosmos DB에 연결합니다.

    mongoose.connect("mongodb://"+process.env.COSMOSDB_HOST+":"+process.env.COSMOSDB_PORT+"/"+process.env.COSMOSDB_DBNAME+"?ssl=true& replicaSet=globaldb", {
   auth: {
     username: process.env.COSMOSDB_USER,
     password: process.env.COSMOSDB_PASSWORD
   },
   useNewUrlParser: true,
   useUnifiedTopology: true,
   retryWrites: false
})
.then(() => console.log('Connection to CosmosDB successful'))
.catch((err) => console.error(err));

    참고 항목

    여기에서 환경 변수는 dotenv npm 패키지를 사용하여 process.env.{variableName}을 사용하여 로드됩니다.

    Azure Cosmos DB에 연결되면 Mongoose에서 개체 모델 설정을 시작할 수 있습니다.

Azure Cosmos DB에서 Mongoose를 사용하는 모범 사례

Mongoose는 사용자가 만드는 각 모델에 대한 새 컬렉션을 만듭니다. 이 작업은 앞에서 설명한 데이터베이스 수준 처리량 옵션을 사용하여 처리하는 것이 가장 좋습니다. 단일 컬렉션을 사용하려면 Mongoose 판별자를 사용해야 합니다. 판별자는 스키마 상속 메커니즘입니다. 판별자를 통해 동일한 기본 MongoDB 컬렉션에서 스키마가 겹치는 여러 모델을 사용할 수 있습니다.

동일한 컬렉션에 다양한 데이터 모델을 저장한 다음 쿼리 시 필터 절을 사용하여 필요한 데이터만 가져올 수 있습니다. 각 모델을 살펴보겠습니다.

개체 모델당 하나의 컬렉션

이 섹션에서는 Azure Cosmos DB의 API for MongoDB를 사용하여 이 작업을 수행하는 방법을 살펴봅니다. 이 방법은 비용 및 용량을 제어할 수 있으므로 권장되는 방법입니다. 따라서 데이터베이스의 요청 단위 양은 개체 모델 수에 따라 좌우되지 않습니다. Mongoose에 대한 기본 운영 모델이므로 이에 대해 잘 알고 있을 수 있습니다.

  1. index.js를 다시 엽니다.

  2. ‘Family’에 대한 스키마 정의를 만듭니다.

    const Family = mongoose.model('Family', new mongoose.Schema({
    lastName: String,
    parents: [{
        familyName: String,
        firstName: String,
        gender: String
    }],
    children: [{
        familyName: String,
        firstName: String,
        gender: String,
        grade: Number
    }],
    pets:[{
        givenName: String
    }],
    address: {
        country: String,
        state: String,
        city: String
    }
}));

  3. ‘Family’에 대한 개체를 만듭니다.

    const family = new Family({
    lastName: "Volum",
    parents: [
        { firstName: "Thomas" },
        { firstName: "Mary Kay" }
    ],
    children: [
        { firstName: "Ryan", gender: "male", grade: 8 },
        { firstName: "Patrick", gender: "male", grade: 7 }
    ],
    pets: [
        { givenName: "Buddy" }
    ],
    address: { country: "USA", state: "WA", city: "Seattle" }
});

  4. 마지막으로, 이 개체를 Azure Cosmos DB에 저장하겠습니다. 그러면 은밀하게 컬렉션이 생성됩니다.

    family.save((err, saveFamily) => {
    console.log(JSON.stringify(saveFamily));
});

  5. 이제 다른 스키마와 개체를 만들겠습니다. 이번에는 가족이 관심을 가질 만한 ‘Vacation Destinations’에 대한 항목을 만들겠습니다.

    1. 이전과 마찬가지로 스키마를 만들겠습니다.

      const VacationDestinations = mongoose.model('VacationDestinations', new mongoose.Schema({
 name: String,
 country: String
}));

    2. 샘플 개체(이 스키마에 여러 개체를 추가할 수 있음)를 만들고 저장합니다.

      const vacaySpot = new VacationDestinations({
 name: "Honolulu",
 country: "USA"
});

vacaySpot.save((err, saveVacay) => {
 console.log(JSON.stringify(saveVacay));
});

  6. 이제 Azure Portal로 이동하면 Azure Cosmos DB에 두 개의 컬렉션이 생성된 것을 확인할 수 있습니다.

    Node.js 자습서 - 컬렉션 이름을 강조 표시한 Azure Cosmos DB 계정을 표시하는 Azure Portal 스크린샷 - 노드 데이터베이스

  7. 마지막으로, Azure Cosmos DB에서 데이터를 읽겠습니다. 기본 Mongoose 운영 모델을 사용하고 있으므로 읽기는 Mongoose를 사용한 다른 읽기와 동일합니다.

    Family.find({ 'children.gender' : "male"}, function(err, foundFamily){
    foundFamily.forEach(fam => console.log("Found Family: " + JSON.stringify(fam)));
});

Mongoose 판별자를 사용하여 단일 컬렉션에 데이터 저장

이 방법에서는 Mongoose 판별자를 사용하여 각 컬렉션의 비용을 최적화합니다. 판별자를 사용하면 차별화 ‘키’를 정의할 수 있으며, 이 키를 통해 여러 개체 모델을 저장, 구별 및 필터링할 수 있습니다.

이 예제에서는 기본 개체 모델을 만들고, 차별화 ‘키’를 정의하고, ‘Family’ 및 ‘VacationDestinations’를 기본 모델의 확장으로 추가합니다.

  1. 기본 구성을 설정하고 판별자 키를 정의하겠습니다.

    const baseConfig = {
    discriminatorKey: "_type", //If you've got a lot of different data types, you could also consider setting up a secondary index here.
    collection: "alldata"   //Name of the Common Collection
};

  2. 그런 다음 공통 개체 모델을 정의하겠습니다.

    const commonModel = mongoose.model('Common', new mongoose.Schema({}, baseConfig));

  3. 이제 ‘Family’ 모델을 정의합니다. 이 예제에서는 mongoose.model 대신 commonModel.discriminator를 사용합니다. 또한 mongoose 스키마에 기본 구성을 추가합니다. 따라서 이 예제의 discriminatorKey는 FamilyType입니다.

    const Family_common = commonModel.discriminator('FamilyType', new     mongoose.Schema({
    lastName: String,
    parents: [{
        familyName: String,
        firstName: String,
        gender: String
    }],
    children: [{
        familyName: String,
        firstName: String,
       gender: String,
        grade: Number
    }],
    pets:[{
        givenName: String
    }],
    address: {
        country: String,
        state: String,
        city: String
    }
}, baseConfig));

  4. 마찬가지로, 이번에는 ‘VacationDestinations’에 대한 다른 스키마를 추가하겠습니다. 여기서 DiscriminatorKey는 VacationDestinationsType입니다.

    const Vacation_common = commonModel.discriminator('VacationDestinationsType', new mongoose.Schema({
    name: String,
    country: String
}, baseConfig));

  5. 마지막으로, 모델에 대한 개체를 만들고 저장합니다.

    1. ‘Family’ 모델에 개체를 추가하겠습니다.

      const family_common = new Family_common({
 lastName: "Volum",
 parents: [
     { firstName: "Thomas" },
     { firstName: "Mary Kay" }
 ],
 children: [
     { firstName: "Ryan", gender: "male", grade: 8 },
     { firstName: "Patrick", gender: "male", grade: 7 }
 ],
 pets: [
     { givenName: "Buddy" }
 ],
 address: { country: "USA", state: "WA", city: "Seattle" }
});

family_common.save((err, saveFamily) => {
 console.log("Saved: " + JSON.stringify(saveFamily));
});

    2. 그런 다음 ‘VacationDestinations’ 모델에 개체를 추가하고 저장하겠습니다.

      const vacay_common = new Vacation_common({
 name: "Honolulu",
 country: "USA"
});

vacay_common.save((err, saveVacay) => {
 console.log("Saved: " + JSON.stringify(saveVacay));
});

  6. 이제 Azure Portal로 돌아가면 ‘Family’ 및 ‘VacationDestinations’ 데이터가 둘 다 포함된 alldata라는 하나의 컬렉션만 표시됩니다.

    Node.js 자습서 - 컬렉션 이름이 강조 표시된 Azure Cosmos DB 계정을 보여 주는 Azure Portal의 스크린샷 - 노드 데이터베이스

  7. 또한 각 개체에 __type이라는 다른 특성이 있습니다. 이 특성은 두 가지 개체 모델을 구별하는 데 도움이 됩니다.

  8. 마지막으로, Azure Cosmos DB에 저장된 데이터를 읽겠습니다. Mongoose는 모델을 기준으로 데이터 필터링을 처리합니다. 따라서 데이터를 읽을 때는 다른 특별한 조치가 필요하지 않습니다. 모델(이 예제에서는 Family_common)을 지정하면 Mongoose가 ‘DiscriminatorKey’를 기준으로 필터링을 처리합니다.

    Family_common.find({ 'children.gender' : "male"}, function(err, foundFamily){
    foundFamily.forEach(fam => console.log("Found Family (using discriminator): " + JSON.stringify(fam)));
});

보시다시피 Mongoose 판별자를 쉽게 이용할 수 있습니다. 따라서 Mongoose 프레임워크를 사용하는 앱이 있는 경우 이 자습서에 따라 과도한 변경 없이 Azure Cosmos DB의 API for MongoDB를 사용하여 애플리케이션을 작동하고 실행할 수 있습니다.

리소스 정리

앱과 Azure Cosmos DB 계정을 모두 사용했으면 추가로 비용을 지불하지 않도록 만든 Azure 리소스를 삭제할 수 있습니다. 리소스를 삭제하려면:

  1. Azure Portal 검색 창에서 리소스 그룹을 검색하고 선택합니다.

  2. 목록에서 이 빠른 시작에서 만든 리소스 그룹을 선택합니다.

    삭제할 리소스 그룹 선택

  3. 리소스 그룹 개요 페이지에서 리소스 그룹 삭제를 선택합니다.

    리소스 그룹 삭제

  4. 새 창에서 삭제할 리소스 그룹의 이름을 입력한 다음, 삭제를 선택합니다.

다음 단계

  • Azure Cosmos DB의 API for MongoDB와 함께 Studio 3T를 사용하는 방법을 알아봅니다.
  • Azure Cosmos DB의 API for MongoDB와 함께 Robo 3T를 사용하는 방법을 알아봅니다.
  • Azure Cosmos DB의 API for MongoDB를 사용하여 MongoDB 샘플을 살펴봅니다.
  • Azure Cosmos DB로 마이그레이션하기 위한 용량 계획을 수행하려고 하시나요? 용량 계획을 위해 기존 데이터베이스 클러스터에 대한 정보를 사용할 수 있습니다.