JavaScript를 사용하여 Azure Cosmos DB for MongoDB 시작

적용 대상: MongoDB

이 문서에서는 네이티브 MongoDB npm 패키지를 사용하여 Azure Cosmos DB for MongoDB에 연결하는 방법을 보여줍니다. 연결되면 데이터베이스, 컬렉션 및 문서에 대한 작업을 수행할 수 있습니다.

참고 항목

예제 코드 조각은 GitHub에서 JavaScript 프로젝트로 사용할 수 있습니다.

API for MongoDB 참조 설명서 | MongoDB 패키지(npm)

필수 조건

• 활성 구독이 있는 Azure 계정. 체험 계정을 만듭니다.
• Node.js LTS
• Azure CLI(명령줄 인터페이스) 또는 Azure PowerShell
• Azure Cosmos DB for MongoDB 리소스

새 JavaScript 앱 만들기

1. 원하는 터미널을 사용하여 새 JavaScript 애플리케이션을 빈 폴더에 만듭니다. npm init 명령을 사용하여 package.json 파일을 만들라는 프롬프트를 시작합니다. 프롬프트에 대한 기본값을 적용합니다.

   npm init
   

2. JavaScript 프로젝트에 MongoDB npm 패키지를 추가합니다. npm 패키지의 이름을 지정한 npm install package 명령을 사용합니다. dotenv 패키지는 로컬 개발 중에 .env 파일에서 환경 변수를 읽는 데 사용됩니다.

   npm install mongodb dotenv
   

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

   node index.js
   

Azure Cosmos DB for MongoDB에 MongoDB 네이티브 드라이버로 연결

Azure Cosmos DB에 MongoDB 네이티브 드라이버를 연결하려면 MongoClient 클래스의 인스턴스를 만듭니다. 이 클래스는 데이터베이스에 대한 모든 작업을 수행하기 위한 시작점입니다.

MongoClient의 가장 일반적인 생성자에는 다음 두 개의 매개 변수가 있습니다.

매개 변수	예제 값	설명
url	COSMOS_CONNECTION_STRING환경 변수	모든 요청에 사용할 API for MongoDB 연결 문자열
options	{ssl: true, tls: true, }	연결을 위한 MongoDB 옵션.

연결 문제는 문제 해결 가이드를 참조하세요.

리소스 이름 가져오기

Azure CLI

1. resourceGroupName에 대한 셸 변수를 만듭니다.

   # Variable for resource group name
   resourceGroupName="msdocs-cosmos"
   

2. az cosmosdb list 명령을 사용하여 리소스 그룹에서 첫 번째 Azure Cosmos DB 계정의 이름을 검색하여 accountName 셸 변수에 저장합니다.

   # Retrieve most recently created account name
   accountName=$(
       az cosmosdb list \
           --resource-group $resourceGroupName \
           --query "[0].name" \
           --output tsv
   )
   

PowerShell

1. RESOURCE_GROUP_NAME에 대한 셸 변수를 만듭니다.

   # Variable for resource group name
   $RESOURCE_GROUP_NAME = "msdocs-cosmos"
   

2. Get-AzCosmosDBAccountKey cmdlet을 사용하여 리소스 그룹에서 첫 번째 Azure Cosmos DB 계정의 이름을 검색하여 accountName 셸 변수에 저장합니다.

   # Get the name of the first Azure Cosmos DB account in your resource group
   $ACCOUNT_NAME = (Get-AzCosmosDBAccount -ResourceGroupName $RESOURCE_GROUP_NAME)[0].Name
   

포털

이 단계를 건너뛰고 다음 단계에서 포털에 대한 정보를 사용합니다.

연결 문자열 검색

Azure CLI

1. az cosmosdb keys list 명령을 사용하여 계정에 대한 연결 문자열 목록에서 MongoDB용 API 연결 문자열을 찾습니다.

   az cosmosdb keys list --type connection-strings \
       --resource-group $resourceGroupName \
       --name $accountName 
   

2. 기본 키 값을 기록합니다. 이러한 자격 증명은 나중에 사용합니다.

PowerShell

1. Get-AzCosmosDBAccountKey cmdlet을 사용하여 계정에 대한 키 및 연결 문자열 목록에서 연결 문자열을 찾습니다.

   $parameters = @{
       ResourceGroupName = $RESOURCE_GROUP_NAME
       Name = $ACCOUNT_NAME
       Type = "ConnectionStrings"
   }    
   Get-AzCosmosDBAccountKey @parameters |
       Select-Object -Property "Primary MongoDB Connection String"    
   

2. 연결 문자열 값을 기록합니다. 이러한 자격 증명은 나중에 사용합니다.

포털

팁

이 가이드에서는 msdocs-cosmos 리소스 그룹 이름을 사용하는 것이 좋습니다.

1. Azure Portal에 로그인합니다.

2. 기존 Azure Cosmos DB for MongoDB 계정 페이지로 이동합니다.

3. Azure Cosmos DB for MongoDB 계정 페이지에서 연결 문자열 탐색 메뉴 옵션을 선택합니다.

4. 기본 연결 문자열 필드의 값을 기록합니다. 이후 단계에서 이 값을 사용합니다.

   

환경 변수 구성

코드 내에서 연결 문자열 값을 사용하려면 애플리케이션을 실행하는 로컬 환경에서 이 값을 설정합니다. 환경 변수를 설정하려면 원하는 터미널을 사용하여 다음 명령을 실행합니다.

Windows

$env:COSMOS_CONNECTION_STRING = "<cosmos-connection-string>"

Linux / macOS

export COSMOS_CONNECTION_STRING="<cosmos-connection-string>"

.env

.env 파일은 프로젝트에 환경 변수를 저장하는 표준 방법입니다. 프로젝트의 루트에 .env 파일을 만듭니다. .env 파일에 다음 줄을 추가합니다.

COSMOS_CONNECTION_STRING="<cosmos-connection-string>"

연결 문자열로 MongoClient 만들기

1. MongoDB 및 DotEnv npm 패키지를 참조하는 종속성을 추가합니다.

   // Read .env file and set environment variables
   require('dotenv').config();
   
   // Use official mongodb driver to connect to the server
   const { MongoClient } = require('mongodb');
   

2. 생성자를 사용하여 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);
   
   // connect to the server
   await client.connect();
   
   // client options
   const options = client.options
   console.log(`Options:\n${Object.keys(options).map(key => `\t${key}: ${options[key]}\n`)}`);
   

MongoClient 인스턴스를 만드는 다양한 방법에 대한 자세한 내용은 MongoDB NodeJS 드라이버 빠른 시작을 참조하세요.

MongoClient 연결 닫기

애플리케이션이 완료되면 연결을 닫아야 합니다. .close() 호출은 모든 데이터베이스 호출이 이루어진 후에 수행해야 합니다.

client.close()

API for MongoDB용 Azure Cosmos DB에서 MongoDB 클라이언트 클래스 사용

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

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

각 리소스 형식은 하나 이상의 연결된 JavaScript 클래스로 표시됩니다. 가장 일반적인 클래스의 목록은 다음과 같습니다.

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

다음 가이드에서는 이러한 각 클래스를 사용하여 애플리케이션을 빌드하는 방법을 보여 줍니다.

가이드:

• 데이터베이스 관리
• 컬렉션 관리
• 문서 관리
• 쿼리를 사용하여 문서 찾기

참고 항목

• 패키지(NuGet)
• API 참조

다음 단계

이제 API for MongoDB 계정에 연결했으므로 다음 가이드를 사용하여 데이터베이스를 만들고 관리합니다.

JavaScript를 사용하여 Azure Cosmos DB for MongoDB에서 데이터베이스 만들기