Python을 사용하여 Azure Cosmos DB for NoSQL 시작
적용 대상: 
NoSQL
이 문서에서는 Python SDK를 사용하여 Azure Cosmos DB for NoSQL에 연결하는 방법을 보여 줍니다. 연결되면 데이터베이스, 컨테이너 및 항목에 대한 작업을 수행할 수 있습니다.
패키지(PyPi) | 샘플 | API 참조 | 라이브러리 소스 코드 | 제공 피드백
필수 조건
- 활성 구독이 있는 Azure 계정. 체험 계정을 만듭니다.
- Azure Cosmos DB for NoSQL 계정. API for NoSQL 계정을 만듭니다.
- Python 3.7 이상
- Azure CLI(명령줄 인터페이스) 또는 Azure PowerShell
프로젝트 설정
Python 코드를 실행할 수 있는 환경을 만듭니다.
가상 환경을 사용하면 시스템의 나머지 부분에 영향을 주지 않고 격리된 환경에 Python 패키지를 설치할 수 있습니다.
가상 환경에 Azure Cosmos DB for NoSQL Python SDK를 설치합니다.
pip install azure-cosmos
Python 애플리케이션 만들기
사용자 환경에서 새 app.py 파일을 만들고 다음 코드를 추가합니다.
import json
import os
import sys
import uuid
from azure.core.exceptions import AzureError
from azure.cosmos import CosmosClient, PartitionKey
앞의 코드는 문서의 나머지 부분에 사용할 모듈을 가져옵니다.
Azure Cosmos DB for NoSQL에 연결
Azure Cosmos DB의 API for NoSQL에 연결하려면 CosmosClient 클래스의 인스턴스를 만듭니다. 이 클래스는 데이터베이스에 대한 모든 작업을 수행하기 위한 시작점입니다.
Microsoft Entra를 사용하여 NoSQL용 API 계정에 연결하려면 보안 주체를 사용합니다. 보안 주체의 정확한 유형은 애플리케이션 코드를 호스트하는 위치에 따라 달라집니다. 아래 표는 빠른 참조 가이드 역할을 합니다.
| 애플리케이션이 실행되는 위치 | 할당할 수 있습니다. |
|---|---|
| 로컬 컴퓨터(개발 및 테스트) | 사용자 ID 또는 서비스 주체 |
| Azure | 관리 ID |
| Azure 외부의 서버 또는 클라이언트 | 서비스 사용자 |
Azure.ID 가져오기
azure-identity 패키지에는 모든 Azure SDK 라이브러리 간의 공유되는 핵심 인증 기능이 포함되어 있습니다.
azure-identity 패키지를 사용자 환경으로 가져옵니다.
pip install azure-identity
기본 자격 증명 구현을 사용하여 CosmosClient 만들기
로컬 컴퓨터에서 테스트하거나 애플리케이션이 관리 ID를 직접 지원하는 Azure 서비스에서 실행되는 경우 DefaultAzureCredential 인스턴스를 만들어 OAuth 토큰을 얻습니다.
app.py:
엔드포인트를 가져와 계정에 연결하고 이를 환경 변수
COSMOS_ENDPOINT로 설정합니다.DefaultAzureCredential을 가져와서 인스턴스 만듭니다.
ENDPOINT 및 credential을 매개 변수로 사용하여 CosmosClient 클래스의 새 인스턴스를 만듭니다.
from azure.identity import DefaultAzureCredential
ENDPOINT = os.environ["COSMOS_ENDPOINT"]
credential = DefaultAzureCredential()
client = CosmosClient(ENDPOINT, credential)
Important
DefaultAzureCredential이 작동하도록 올바른 역할을 추가하는 방법에 대한 자세한 내용은 Azure Cosmos DB 계정에 대해 Microsoft Entra ID를 사용하여 역할 기반 액세스 제어 구성을 참조하세요. 특히 역할을 만들고 보안 주체 ID에 할당하는 방법에 대한 섹션을 참조하세요.
애플리케이션 빌드
애플리케이션을 빌드할 때 코드는 주로 다음 4가지 종류의 리소스와 상호 작용합니다.
API for NoSQL 계정 - Azure Cosmos DB 데이터에 대한 고유한 최상위 네임스페이스입니다.
계정의 컨테이너를 구성하는 데이터베이스
데이터베이스의 개별 항목 세트를 포함하는 컨테이너
컨테이너의 JSON 문서를 나타내는 항목
다음 다이어그램에서는 리소스 간의 관계를 보여줍니다.
맨 위에 있는 Azure Cosmos DB 계정을 보여 주는 계층 다이어그램. 계정에는 두 개의 자식 데이터베이스 노드가 있습니다. 데이터베이스 노드 중 하나에는 두 개의 자식 컨테이너 노드가 포함되어 있습니다. 다른 데이터베이스 노드에는 단일 자식 컨테이너 노드가 포함됩니다. 단일 컨테이너 노드에는 세 개의 자식 항목 노드가 있습니다.
각 리소스 형식은 하나 이상의 연결된 Python 클래스로 표시됩니다. 다음은 가장 일반적인 동기 프로그래밍 클래스 목록입니다. (azure.cosmos.aio 네임스페이스 아래에 비동기 프로그래밍에 대한 유사한 클래스가 있음).
| 클래스 | 설명 |
|---|---|
CosmosClient |
이 클래스는 Azure Cosmos DB 서비스의 클라이언트 쪽 논리적 표현을 제공합니다. 이 클라이언트 개체는 서비스에 대한 요청을 구성하고 실행하는 데 사용됩니다. |
DatabaseProxy |
아직 서비스에 있을 수도 있고, 없을 수도 있는 데이터베이스에 대한 인터페이스입니다. 이 클래스는 직접 인스턴스화하면 안 됩니다. 대신 CosmosClient get_database_client 메서드를 사용해야 합니다. |
ContainerProxy |
특정 Cosmos DB 컨테이너와 상호 작용하는 인터페이스입니다. 이 클래스는 직접 인스턴스화하면 안 됩니다. 대신 DatabaseProxy get_container_client 메서드를 사용하여 기존 컨테이너를 얻거나 create_container 메서드를 사용하여 새 컨테이너를 만듭니다. |
다음 가이드에서는 이러한 각 클래스를 사용하여 애플리케이션을 빌드하는 방법을 보여 줍니다.
| 가이드 | 설명 |
|---|---|
| 데이터베이스 만들기 | 데이터베이스 만들기 |
| 컨테이너 만들기 | 컨테이너 만들기 |
| 항목 예제 | 특정 항목 지점 읽기 |