이 빠른 시작에서는 Node.js사용하여 기본 Azure Cosmos DB for MongoDB 애플리케이션을 배포합니다. Azure Cosmos DB for MongoDB vCore는 애플리케이션이 MongoDB 라이브러리를 사용하여 클라우드에 구조화되지 않은 문서를 저장할 수 있는 스키마 없는 데이터 저장소입니다. Node.js사용하여 Azure Cosmos DB 리소스 내에서 문서를 만들고 기본 작업을 수행하는 방법을 알아봅니다.
라이브러리 소스 코드 | 패키지(npm) | Azure Developer CLI
필수 조건
Azure 개발자 명령줄 인터페이스 (CLI)
Docker Desktop
Azure 구독
- Azure 구독이 없는 경우, 시작하기 전에 무료 계정을 만드십시오.
- Node.js 22 이상
프로젝트 시작
Azure Developer CLI(azd)를 사용하여 Azure Cosmos DB for MongoDB vCore 클러스터를 만들고 컨테이너화된 샘플 애플리케이션을 배포합니다. 샘플 애플리케이션은 클라이언트 라이브러리를 사용하여 샘플 데이터를 관리, 만들기, 읽기 및 쿼리합니다.
빈 디렉터리에서 터미널을 엽니다.
아직 인증되지 않은 경우,
azd auth login를 사용하여 Azure Developer CLI에 인증하세요. 원하는 Azure 자격 증명을 사용하여 CLI에 인증하려면 도구에 지정된 단계를 따릅니다.azd auth login프로젝트를 초기화하려면
azd init를 사용합니다.azd init --template cosmos-db-mongodb-vcore-nodejs-quickstart초기화하는 동안 고유한 환경 이름을 구성합니다.
를 사용하여 클러스터를 배포합니다
azd up. Bicep 템플릿은 샘플 웹 애플리케이션도 배포합니다.azd up프로비전 프로세스 중에 구독, 원하는 위치 및 대상 리소스 그룹을 선택합니다. 프로비전 프로세스가 완료되기를 기다립니다. 프로세스는 약 10분 정도 걸릴 수 있습니다.
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을 사용하여 브라우저에서 웹 애플리케이션으로 이동합니다. 실행 중인 앱의 출력을 관찰합니다.
클라이언트 라이브러리 설치
클라이언트 라이브러리는 mongodb 패키지를 통해 npm에서 사용할 수 있습니다.
터미널을 열고
/src/ts폴더로 이동합니다.cd ./src/ts아직 설치되지 않은 경우
mongodb을 사용하여npm install패키지를 설치합니다.npm install --save mongodb아직 설치되지 않은 경우
@azure/identity을 사용하여npm install패키지를 설치합니다.npm install --save @azure/identitysrc/ts/package.json 파일을 열고 검토하여 두 패키지 항목이 모두 존재하는지 확인합니다.
터미널을 열고
/src/js폴더로 이동합니다.cd ./src/js아직 설치되지 않은 경우
mongodb을 사용하여npm install패키지를 설치합니다.npm install --save mongodb아직 설치되지 않은 경우
@azure/identity을 사용하여npm install패키지를 설치합니다.npm install --save @azure/identitysrc/js/package.json 파일을 열고 검토하여 두 패키지 항목이 모두 존재하는지 확인합니다.
라이브러리 가져오기
애플리케이션 코드로 다음 네임스페이스를 가져옵니다.
| 패키지 | 출처 | |
|---|---|---|
TokenCredential |
@azure/identity |
JavaScript용 Azure SDK |
DefaultAzureCredential |
@azure/identity |
JavaScript용 Azure SDK |
MongoClient |
mongodb |
Node.js 공식 MongoDB 드라이버 |
import { DefaultAzureCredential, TokenCredential } from '@azure/identity';
import { MongoClient } from 'mongodb';
다음을 포함하지만 제한되지 않는 모든 필수 형식을 애플리케이션 코드로 가져옵니다.
| 패키지 | 출처 | |
|---|---|---|
TokenCredential |
@azure/identity |
JavaScript용 Azure SDK |
DefaultAzureCredential |
@azure/identity |
JavaScript용 Azure SDK |
MongoClient |
mongodb |
Node.js 공식 MongoDB 드라이버 |
import { AccessToken, DefaultAzureCredential, TokenCredential } from '@azure/identity';
import { Collection, Db, Filter, FindCursor, MongoClient, OIDCCallbackParams, OIDCResponse, UpdateFilter, UpdateOptions, UpdateResult, WithId } from 'mongodb';
개체 모델
| 이름 | 설명 |
|---|---|
| MongoClient | MongoDB에 연결하는 데 사용되는 형식입니다. |
Database |
클러스터의 데이터베이스를 나타냅니다. |
Collection |
클러스터의 데이터베이스 내 컬렉션을 나타냅니다. |
코드 예제
템플릿의 샘플 코드는 cosmicworks 데이터베이스와 products(이)라는 컬렉션을 사용합니다.
products 컬렉션에는 각 제품에 대한 이름, 범주, 수량 및 고유 식별자와 같은 세부 정보가 포함됩니다. 컬렉션은 /category 속성을 분할 키로 사용합니다.
클라이언트 인증
Azure Cosmos DB for MongoDB vCore에 대한 Microsoft Entra 인증은 잘 알려진 TokenCredential 형식을 사용할 수 있지만 사용자 지정 토큰 처리기를 구현해야 합니다. 이 샘플 구현은 다양한 ID 유형의 표준 Microsoft Entra 인증을 지원하는 MongoClient를 생성하는 데 사용할 수 있습니다.
먼저
OIDCCallbackParams과TokenCredential를 받아OIDCResponse를 비동기적으로 반환하는AzureIdentityTokenCallback라는 이름의 콜백을 정의합니다.const AzureIdentityTokenCallback = async (params: OIDCCallbackParams, credential: TokenCredential): Promise<OIDCResponse> => { const tokenResponse: AccessToken | null = await credential.getToken(['https://ossrdbms-aad.database.windows.net/.default']); return { accessToken: tokenResponse?.token || '', expiresInSeconds: (tokenResponse?.expiresOnTimestamp || 0) - Math.floor(Date.now() / 1000) }; };클러스터 이름 및 토큰 자격 증명에 대한 변수를 정의합니다.
const clusterName: string = '<azure-cosmos-db-mongodb-vcore-cluster-name>'; const credential: TokenCredential = new DefaultAzureCredential();클러스터 이름 및 MongoDB vCore용 Azure Cosmos DB에 대한 알려진 모범 사례 구성 옵션을 사용하는 인스턴스
MongoClient를 빌드합니다. 또한 사용자 지정 인증 메커니즘을 구성합니다.const client = new MongoClient( `mongodb+srv://${clusterName}.global.mongocluster.cosmos.azure.com/`, { connectTimeoutMS: 120000, tls: true, retryWrites: true, authMechanism: 'MONGODB-OIDC', authMechanismProperties: { OIDC_CALLBACK: (params: OIDCCallbackParams) => AzureIdentityTokenCallback(params, credential), ALLOWED_HOSTS: ['*.azure.com'] } } );
먼저 매개 변수 및 토큰 자격 증명을 사용하는 명명
azureIdentityTokenCallback된 콜백을 정의한 다음 비동기적으로 응답을 반환합니다.const azureIdentityTokenCallback = async (_, credential) => { const tokenResponse = await credential.getToken(['https://ossrdbms-aad.database.windows.net/.default']); if (!tokenResponse || !tokenResponse.token) { throw new Error('Failed to retrieve a valid access token.'); } return { accessToken: tokenResponse.token, expiresInSeconds: Math.floor((tokenResponse.expiresOnTimestamp - Date.now()) / 1000), }; };클러스터 이름 및 토큰 자격 증명에 대한 변수를 정의합니다.
const clusterName = '<azure-cosmos-db-mongodb-vcore-cluster-name>'; const credential = new DefaultAzureCredential();클러스터 이름 및 MongoDB vCore용 Azure Cosmos DB에 대한 알려진 모범 사례 구성 옵션을 사용하는 인스턴스
MongoClient를 빌드합니다. 또한 사용자 지정 인증 메커니즘을 구성합니다.client = new MongoClient(`mongodb+srv://${clusterName}.global.mongocluster.cosmos.azure.com/`, { connectTimeoutMS: 120000, tls: true, retryWrites: true, authMechanism: 'MONGODB-OIDC', authMechanismProperties: { OIDC_CALLBACK: (params) => azureIdentityTokenCallback(params, credential), ALLOWED_HOSTS: ['*.azure.com'] } }); await client.connect();
데이터베이스 가져오기
이 샘플은 Db 형식의 db 함수를 사용하여 MongoClient 형식의 인스턴스를 만듭니다.
const database: Db = client.db("<database-name>");
const database = client.db("<database-name>");
컬렉션 가져오기
이 샘플은 Collection 형식의 collection 함수를 사용하여 Db 형식의 인스턴스를 만듭니다.
이 함수에는 인터페이스에 정의된 형식을 Product 사용하는 제네릭 매개 변수가 있습니다.
const collection: Collection<Product> = database.collection<Product>("<collection-name>");
export interface Product {
_id: string;
category: string;
name: string;
quantity: number;
price: number;
clearance: boolean;
}
const collection = database.collection("<collection-name>");
문서 만들기
collection.updateOne을(를) 사용하여 컬렉션에 문서를 만듭니다. 이 방법은 항목이 이미 존재하는 경우 해당 항목을 효과적으로 바꿔 해당 항목을 "upsert"합니다.
var document: Product = {
_id: 'aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb',
category: 'gear-surf-surfboards',
name: 'Yamba Surfboard',
quantity: 12,
price: 850.00,
clearance: false
};
var query: Filter<Product> = {
_id: 'aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb',
category: 'gear-surf-surfboards'
};
var payload: UpdateFilter<Product> = {
$set: document
};
var options: UpdateOptions = {
upsert: true
};
var response: UpdateResult<Product> = await collection.updateOne(query, payload, options);
var document = {
_id: 'aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb',
category: 'gear-surf-surfboards',
name: 'Yamba Surfboard',
quantity: 12,
price: 850.00,
clearance: false
};
const query = {
_id: 'aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb',
category: 'gear-surf-surfboards'
};
const payload = {
$set: document
};
const options = {
upsert: true,
new: true
};
var response = await collection.updateOne(query, payload, options);
문서 읽기
고유 식별자(id)와 분할 키 필드를 모두 사용하여 지점 읽기 작업을 수행합니다. 특정 항목을 효율적으로 검색하려면 collection.findOne을 사용합니다.
var query: Filter<Product> = {
_id: 'aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb',
category: 'gear-surf-surfboards'
};
var response: WithId<Product> | null = await collection.findOne(query);
var query = {
_id: 'aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb',
category: 'gear-surf-surfboards'
};
var response = await collection.findOne(query);
쿼리 문서
collection.find를 사용하여 컨테이너의 여러 항목에 대해 쿼리를 수행합니다. 이 쿼리는 지정된 범주(분할 키) 내의 모든 항목을 찾습니다.
var query: Filter<Product> = {
category: 'gear-surf-surfboards'
};
var response: FindCursor<WithId<Product>> = collection.find(query);
for await (const item of response) {
// Do something with each item
}
var query = {
category: 'gear-surf-surfboards'
};
var response = collection.find(query);
for await (const item of response) {
// Do something with each item
}
문서 삭제
문서의 고유 식별자에 대한 필터를 전송하여 문서를 삭제합니다. 컬렉션에서 문서를 비동기적으로 제거하는 데 사용합니다 collection.deleteOne<> .
var filter: Filter<Product> = {
_id: 'aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb'
};
await collection.deleteOne(filter);
const filter = {
_id: 'aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb'
};
await collection.deleteOne(filter);
데이터 탐색
Azure Cosmos DB용 Visual Studio Code 확장을 사용하여 MongoDB vCore 데이터를 탐색합니다. 다음을 포함하지만 제한되지 않는 핵심 데이터베이스 작업을 수행할 수 있습니다.
- 스크랩북 또는 쿼리 편집기를 사용하여 쿼리 수행
- 문서 수정, 업데이트, 만들기 및 삭제
- 다른 원본에서 대량 데이터 가져오기
- 데이터베이스 및 컬렉션 관리
자세한 내용은 Visual Studio Code 확장을 사용하여 MongoDB용 Azure Cosmos DB vCore 데이터를 탐색하는 방법을 참조하세요.
리소스 정리
샘플 애플리케이션 또는 리소스가 더 이상 필요하지 않은 경우 해당 배포 및 모든 리소스를 제거합니다.
azd down --force