Azure Cosmos DB for MongoDB 및 Python 시작

적용 대상: MongoDB

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

참고 항목

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

이 문서에서는 Python용 오픈 소스 MongoDB 클라이언트 드라이버 중 하나인 PyMongo를 사용하여 Azure Cosmos DB의 API for MongoDB와 통신하는 방법을 보여 줍니다.

필수 조건

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

새 Python 앱 만들기

1. 원하는 터미널을 사용하여 빈 폴더를 새로 만들고 디렉터리를 폴더로 변경합니다.

   참고 항목

   완성된 코드를 원하는 경우 전체 예제를 포함하는 예제 코드 조각 리포지토리를 다운로드하거나 포크한 후 복제합니다. Azure Cloud Shell의 리포지토리를 git clone하여 이 빠른 시작에 표시된 단계를 진행할 수도 있습니다.

2. PyMongo 및 python-dotenv 패키지를 나열하는 requirements.txt 파일을 만듭니다. dotenv 패키지는 로컬 개발 중에 .env 파일에서 환경 변수를 읽는 데 사용됩니다.

   # requirements.txt
   pymongo
   python-dotenv
   

3. 가상 환경을 만들고 패키지를 설치합니다.

   Windows

   # py -3 uses the global python interpreter. You can also use python3 -m venv .venv.
   py -3 -m venv .venv
   source .venv/Scripts/activate   
   pip install -r requirements.txt
   

   Linux / macOS

   python3 -m venv .venv
   source .venv/bin/activate
   pip install -r requirements.txt
   

PyMongo 드라이버로 Azure Cosmos DB for MongoDB에 연결

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

MongoClient의 가장 일반적인 생성자에는 host 매개 변수만 필요합니다. 이 문서에서 이 매개 변수는 COSMOS_CONNECTION_STRING 환경 변수로 설정됩니다. 생성자에서 사용할 수 있는 다른 선택적 매개 변수 및 키워드 매개 변수가 있습니다. 많은 선택적 매개 변수를 host 매개 변수로 지정할 수도 있습니다. 동일한 옵션이 host와 함께 매개 변수로 제공되면 매개 변수가 우선합니다.

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

리소스 이름 가져오기

아래 명령에서는 msdocs-cosmos를 리소스 그룹 이름으로 표시합니다. 상황에 맞게 이름을 변경합니다.

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. 연결 문자열 값을 기록합니다. 이러한 자격 증명은 나중에 사용합니다.

포털

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. PyMongo 및 python-dotenv 패키지를 참조하는 종속성을 추가합니다.

   import os
   import sys
   
   import pymongo
   from dotenv import load_dotenv
   

2. 생성자와 환경 변수에서 읽은 연결 문자열을 사용하여 MongoClient 클래스의 새 인스턴스를 정의합니다.

   load_dotenv()
   CONNECTION_STRING = os.environ.get("COSMOS_CONNECTION_STRING")
   client = pymongo.MongoClient(CONNECTION_STRING)
   
   for prop, value in vars(client.options).items():
       print("Property: {}: Value: {} ".format(prop, value))
   

MongoClient 인스턴스를 만드는 다양한 방법에 대한 자세한 내용은 MongoClient와 연결을 참조하세요.

MongoClient 연결 닫기

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

client.close()

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

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

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

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

• MongoClient - PyMongo로 작업할 때 첫 번째 단계는 MongoClient를 만들어 Azure Cosmos DB의 MongoDB용 API에 연결하는 것입니다. 이 클라이언트 개체는 서비스에 대한 요청을 구성하고 실행하는 데 사용됩니다.

• 데이터베이스 - Azure Cosmos DB의 MongoDB용 API는 하나 이상의 독립적인 데이터베이스를 지원할 수 있습니다.

• 컬렉션 - 데이터베이스에 하나 이상의 컬렉션이 포함될 수 있습니다. 컬렉션은 MongoDB에 저장된 문서 그룹이며 관계형 데이터베이스의 테이블과 거의 동일하다고 생각할 수 있습니다.

• 문서 - 문서는 키-값 쌍 집합입니다. 문서에는 동적 스키마가 있습니다. 동적 스키마는 동일한 컬렉션의 문서에 동일한 필드 또는 구조 집합이 필요하지 않음을 의미합니다. 또한 컬렉션 문서의 공통 필드에는 다양한 형식의 데이터가 포함될 수 있습니다.

엔터티 계층 구조를 자세히 알아보려면 Azure Cosmos DB 리소스 모델 문서를 참조하세요.

참고 항목

• PyPI 패키지
• API 참조

다음 단계

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

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