빠른 시작: Node.js용 Azure Cosmos DB for MongoDB 드라이버
적용 대상: 
MongoDB
MongoDB npm 패키지를 시작하여 Azure Cosmos DB 리소스 내에서 데이터베이스, 컬렉션 및 문서를 만듭니다. 다음 단계에 따라 패키지를 설치하고 기본 작업에 대한 예제 코드를 사용해 보세요.
API for MongoDB 참조 설명서 | MongoDB 패키지(NuGet) packages/Microsoft.Azure.Cosmos) | Azure Developer CLI
필수 조건
- 활성 구독이 있는 Azure 계정. 체험 계정을 만듭니다.
- GitHub 계정
- 활성 구독이 있는 Azure 계정. 체험 계정을 만듭니다.
- Azure Developer CLI
- Docker Desktop
설정
이 프로젝트의 개발 컨테이너를 환경에 배포합니다. 그런 다음, Azure 개발자 CLI(azd)를 사용하여 Azure Cosmos DB for MongoDB 계정을 만들고 컨테이너화된 샘플 애플리케이션을 배포합니다. 샘플 애플리케이션은 클라이언트 라이브러리를 사용하여 샘플 데이터를 관리, 만들기, 읽기 및 쿼리합니다.
Important
GitHub 계정에는 무료로 스토리지 및 핵심 시간에 대한 권한이 포함됩니다. 자세한 내용은 GitHub 계정에 포함된 스토리지 및 핵심 시간을 참조하세요.
프로젝트의 루트 디렉터리에서 터미널을 엽니다.
azd auth login을 사용하여 Azure 개발자 CLI에 인증합니다. 원하는 Azure 자격 증명을 사용하여 CLI에 인증하려면 도구에 지정된 단계를 따릅니다.azd auth login프로젝트를 초기화하려면
azd init를 사용합니다.azd init --template cosmos-db-mongodb-nodejs-quickstart참고 항목
이 빠른 시작은 azure-samples/cosmos-db-mongodb-nodejs-quickstart 템플릿 GitHub 리포지토리를 사용합니다. Azure 개발자 CLI는 이 프로젝트가 아직 없는 경우 컴퓨터에 자동으로 복제합니다.
초기화 중에 고유한 환경 이름을 구성합니다.
팁
환경 이름은 대상 리소스 그룹 이름으로도 사용됩니다. 이 빠른 시작에서는
msdocs-cosmos-db사용을 고려해보세요.azd up을 사용하여 Azure Cosmos DB 계정을 배포합니다. Bicep 템플릿은 샘플 웹 애플리케이션도 배포합니다.azd up프로비전 과정에서 구독과 원하는 위치를 선택합니다. 프로비저닝 프로세스가 완료될 때까지 기다립니다. 이 과정은 약 5분 정도 소요됩니다.
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.콘솔의 URL을 사용하여 브라우저에서 웹 애플리케이션으로 이동합니다. 실행 중인 앱의 출력을 관찰합니다.
패키지 설치
JavaScript 프로젝트에 MongoDB npm 패키지를 추가합니다. npm 패키지의 이름을 지정한 npm install package 명령을 사용합니다. dotenv 패키지는 로컬 개발 중에 .env 파일에서 환경 변수를 읽는 데 사용됩니다.
npm install mongodb dotenv
개체 모델
애플리케이션 빌드를 시작하기 전에 Azure Cosmos DB의 리소스 계층 구조를 살펴보겠습니다. Azure Cosmos DB에는 리소스를 만들고 액세스하는 데 사용되는 특정 개체 모델이 있습니다. Azure Cosmos DB는 리소스를 계정, 데이터베이스, 컬렉션 및 문서로 구성된 계층 구조에 만듭니다.
맨 위에 있는 Azure Cosmos DB 계정을 보여 주는 계층 다이어그램. 계정에는 두 개의 분할된 자식 데이터베이스가 있습니다. 분할된 데이터베이스 중 하나에는 두 개의 자식 컬렉션 분할된 데이터베이스가 포함됩니다. 다른 분할된 데이터베이스에는 단일 자식 컬렉션 노드가 포함됩니다. 단일 컬렉션 분할된 데이터베이스에는 세 개의 자식 문서 분할된 데이터베이스가 있습니다.
다음 MongoDB 클래스를 사용하여 이러한 리소스와 상호 작용합니다.
MongoClient- 이 클래스는 Azure Cosmos DB에서 API for MongoDB 계층에 대한 클라이언트 쪽 논리적 표현을 제공합니다. 이 클라이언트 개체는 서비스에 대한 요청을 구성하고 실행하는 데 사용됩니다.Db- 이 클래스는 서비스에 있거나 아직 없을 수도 있는 데이터베이스에 대한 참조입니다. 데이터베이스에 액세스하거나 이에 대한 작업을 수행하려고 하면 서버 쪽에서 데이터베이스의 유효성이 검사됩니다.Collection- 이 클래스는 아직 서비스에 없을 수도 있는 컬렉션에 대한 참조입니다. 관련 작업을 시도하면 서버 쪽에서 컬렉션의 유효성이 검사됩니다.
코드 예제
이 문서에서 설명하는 샘플 코드에서는 products라는 컬렉션을 사용하여 adventureworks라는 데이터베이스를 만듭니다. products 컬렉션은 이름, 범주, 수량 및 판매 지표와 같은 제품 세부 정보를 포함하도록 설계되었습니다. 각 제품에는 고유 식별자도 포함됩니다.
이 절차의 경우 데이터베이스는 분할을 사용하지 않습니다.
클라이언트 인증
프로젝트 디렉터리에서 index.js 파일을 만듭니다. 편집기에서 MongoDB 및 DotEnv npm 패키지를 참조하는 명령문을 추가해야 합니다.
// Read .env file and set environment variables require('dotenv').config(); const random = Math.floor(Math.random() * 100); // Use official mongodb driver to connect to the server const { MongoClient, ObjectId } = require('mongodb');생성자를 사용하는
MongoClient,클래스의 새 인스턴스 및 이전에 만든 환경 변수를 읽는process.env.를 정의합니다.// New instance of MongoClient with connection string // for Cosmos DB const url = process.env.COSMOS_CONNECTION_STRING; const client = new MongoClient(url);
MongoClient 인스턴스를 만드는 다양한 방법에 대한 자세한 내용은 MongoDB NodeJS 드라이버 빠른 시작을 참조하세요.
비동기 작업 설정
index.js 파일에서 비동기 작업을 지원하는 다음 코드를 추가합니다.
async function main(){
// The remaining operations are added here
// in the main function
}
main()
.then(console.log)
.catch(console.error)
.finally(() => client.close());
다음 코드 조각은 비동기/await 구문을 처리하기 위해 주 함수에 추가되어야 합니다.
데이터베이스에 연결
MongoClient.connect 메서드를 사용하여 Azure Cosmos DB for MongoDB 리소스에 연결합니다. 연결 메서드는 데이터베이스에 대한 참조를 반환합니다.
// Use connect method to connect to the server
await client.connect();
데이터베이스 인스턴스 가져오기
MongoClient.db를 사용하여 데이터베이스에 대한 참조를 가져옵니다.
// Database reference with creation if it does not already exist
const db = client.db(`adventureworks`);
console.log(`New database:\t${db.databaseName}\n`);
컬렉션 인스턴스 가져오기
MongoClient.Db.collection은 컬렉션에 대한 참조를 가져옵니다.
// Collection reference with creation if it does not already exist
const collection = db.collection('products');
console.log(`New collection:\t${collection.collectionName}\n`);
연결된 인스턴스
클라이언트, 데이터베이스 및 컬렉션을 함께 연결할 수 있습니다. 체인은 여러 데이터베이스 또는 컬렉션에 액세스해야 하는 경우 더 편리합니다.
const db = await client.db(`adventureworks`).collection('products').updateOne(query, update, options)
인덱스 만들기
Collection.createIndex를 사용하여 MongoDB의 FindCursor.sort 메서드로 정렬하는 데 사용할 문서의 속성에 대한 인덱스를 만듭니다.
// create index to sort by name
const indexResult = await collection.createIndex({ name: 1 });
console.log(`indexResult: ${JSON.stringify(indexResult)}\n`);
문서 만들기
adventureworks 데이터베이스에 대한 product 속성으로 문서를 만듭니다.
- 제품의 고유 식별자의 대한 _id 속성입니다.
- category 속성입니다. 이 속성은 논리 파티션 키로 사용할 수 있습니다.
- name 속성입니다.
- 인벤토리 quantity 속성입니다.
- 제품이 판매 중인지 여부를 나타내는 sale 속성입니다.
// Create new doc and upsert (create or replace) to collection
const product = {
category: "gear-surf-surfboards",
name: `Yamba Surfboard-${random}`,
quantity: 12,
sale: false
};
const query = { name: product.name};
const update = { $set: product };
const options = {upsert: true, new: true};
// Insert via upsert (create or replace) doc to collection directly
const upsertResult1 = await collection.updateOne(query, update, options);
console.log(`upsertResult1: ${JSON.stringify(upsertResult1)}\n`);
// Update via upsert on chained instance
const query2 = { _id: ObjectId(upsertResult1.upsertedId) };
const update2 = { $set: { quantity: 20 } };
const upsertResult2 = await client.db(`adventureworks`).collection('products').updateOne(query2, update2, options);
console.log(`upsertResult2: ${JSON.stringify(upsertResult2)}\n`);
Collection.UpdateOne을 호출하여 컬렉션에 문서를 만듭니다. 이 예제에서는 이 샘플 코드를 두 번 이상 실행하는 경우에 대비하여 새 문서를 만드는 대신 upsert하도록 선택했습니다.
문서 가져오기
Azure Cosmos DB에서는 고유 식별자(_id)와 파티션 키(category)를 모두 사용하여 비용이 저렴한 지점 읽기 작업을 수행할 수 있습니다.
// Point read doc from collection:
// - without sharding, should use {_id}
// - with sharding, should use {_id, partitionKey }, ex: {_id, category}
const foundProduct = await collection.findOne({
_id: ObjectId(upsertResult1.upsertedId),
category: "gear-surf-surfboards"
});
console.log(`foundProduct: ${JSON.stringify(foundProduct)}\n`);
문서 쿼리
문서가 삽입되면 특정 필터와 일치하는 모든 문서를 가져오는 쿼리를 실행할 수 있습니다. 이 예제에서는 특정 범주 gear-surf-surfboards와 일치하는 모든 문서를 찾습니다. 쿼리가 정의되면 Collection.find를 호출하여 FindCursor 결과를 가져옵니다. JavaScript 배열 메서드를 사용하도록 커서를 배열로 변환합니다.
// select all from product category
const allProductsQuery = {
category: "gear-surf-surfboards"
};
// get all documents, sorted by name, convert cursor into array
const products = await collection.find(allProductsQuery).sort({name:1}).toArray();
products.map((product, i ) => console.log(`${++i} ${JSON.stringify(product)}`));
문제 해결:
The index path corresponding to the specified order-by item is excluded.와 같은 오류가 발생하는 경우 인덱스가 만들어졌는지 확인합니다.
코드 실행
이 앱은 API for MongoDB 데이터베이스 및 컬렉션을 만들고 문서를 만든 다음, 정확히 동일한 문서를 다시 읽습니다. 마지막으로 이 예에서 해당 단일 문서만 반환해야 하는 쿼리를 실행합니다. 각 단계에서 예는 수행한 단계에 대한 정보를 콘솔에 출력합니다.
앱을 실행하려면 터미널을 사용하여 애플리케이션 디렉터리로 이동하고 애플리케이션을 실행합니다.
node index.js
앱의 출력은 다음 예제와 비슷합니다.
New database: adventureworks
New collection: products
upsertResult1: {"acknowledged":true,"modifiedCount":0,"upsertedId":"62b1f492ff69395b30a03169","upsertedCount":1,"matchedCount":0}
upsertResult2: {"acknowledged":true,"modifiedCount":1,"upsertedId":null,"upsertedCount":0,"matchedCount":1}
foundProduct: {"_id":"62b1f492ff69395b30a03169","name":"Yamba Surfboard-93","category":"gear-surf-surfboards","quantity":20,"sale":false}
indexResult: "name_1"
1 {"_id":"62b1f47dacbf04e86c8abf25","name":"Yamba Surfboard-11","category":"gear-surf-surfboards","quantity":20,"sale":false}
done
리소스 정리
Azure Cosmos DB for MongoDB 계정이 더 이상 필요하지 않으면 해당 리소스 그룹을 삭제할 수 있습니다.
az group delete 명령을 사용하여 리소스 그룹을 삭제합니다.
az group delete --name $resourceGroupName
다음 단계
이 빠른 시작에서는 Azure Cosmos DB for MongoDB 계정을 만들고, 데이터베이스를 만들고, MongoDB 드라이버를 사용하여 컬렉션을 만드는 방법을 알아보았습니다. 이제 더 많은 데이터를 가져오고, 복잡한 쿼리를 수행하고, Azure Cosmos DB MongoDB 리소스를 관리하기 위해 Azure Cosmos DB for MongoDB에 대해 자세히 알아볼 수 있습니다.