NoSQL용 Azure Cosmos DB의 Python SDK 모범 사례

  • 적용 대상: ✅ NoSQL

이 가이드에는 최신 버전의 Azure Cosmos DB for NoSQL용 Python SDK를 사용하여 빌드된 솔루션에 대한 모범 사례가 포함되어 있습니다. 여기에 포함된 모범 사례는 대기 시간을 개선하고 가용성을 개선하며 솔루션의 전반적인 성능을 향상시키는 데 도움이 됩니다.

계정 구성

계정 구성 매개 변수

매개 변수 기본 또는 제약 조건 사용 시기
지역 코로케이션 앱 지역과 동일 대기 시간 감소
다중 지역 복제 기본적으로 사용 안 함 가용성을 위해 2개 이상의 지역 사용
서비스 관리형 장애 조치 Optional 프로덕션 워크로드에 대비해 활성화 
from azure.cosmos import CosmosClient
client = CosmosClient(url, credential)
print(client.client_connection._global_endpoint_manager.write_endpoint)
# Expected: write endpoint resolves to configured write region

Python SDK를 사용하여 여러 지역을 추가하는 방법에 대한 자세한 내용은 글로벌 배포 자습서 참조하세요.

SDK 사용

SDK 사용 매개 변수

매개 변수 기본 또는 제약 조건 사용 시기
SDK 버전 최신 버전 사용 가능 항상 최적의 성능을 위해
CosmosClient 인스턴스 앱당 하나 앱 수명 동안 다시 사용
선호 위치 None 읽기 및 장애 조치 최적화 
client = CosmosClient(
    url,
    credential,
    preferred_locations=["East US", "West US"]
)
print(client.client_connection._preferred_locations)
# Expected: ['East US', 'West US']

일시적인 오류는 근본 원인을 바탕으로 자체적으로 해결되는 오류입니다. 데이터베이스에 연결하는 애플리케이션은 이러한 일시적인 오류를 예상하도록 빌드되어야 합니다. 이를 처리하기 위해 사용자에게 애플리케이션 오류로 표시되는 대신 해당 코드에서 다시 시도 논리를 구현합니다. SDK에는 읽기 또는 쿼리와 같은 재시도 가능한 작업 요청에서 발생하는 일시적인 오류를 처리하는 로직이 기본적으로 포함되어 있습니다. 쓰기가 idempotent가 아니기 때문에 SDK는 일시적 오류에 대해 쓰기를 다시 시도할 수 없습니다. SDK를 통해 사용자가 제한 사항에 대한 재시도 로직을 설정할 수 있습니다. 다시 시도할 오류에 대한 자세한 내용은 복원력 있는 애플리케이션 지침을 참조하세요.

SDK 로깅을 사용하여 진단 정보를 캡처 하고 대기 시간 문제를 해결합니다.

비동기 클라이언트

비동기 클라이언트 요구 사항

요구 사항 기본 또는 제약 조건 사용 시기
가져오기 경로 azure.cosmos.aio.CosmosClient 비동기 프레임워크 및 이벤트 루프에서 사용
aiohttp 종속성 기본적으로 설치되지 않음 명시적으로 설치: pip install aiohttp
클라이언트 수명 주기 명시적으로 닫아야 합니다. async with 또는 await client.close()을(를) 사용하세요. 
from azure.cosmos.aio import CosmosClient

# Preferred: use async with to manage lifecycle automatically
async with CosmosClient(url, credential) as client:
    database = client.get_database_client("mydb")
    container = database.get_container_client("mycontainer")
    item = await container.read_item(item="id1", partition_key="pk1")

# Alternative: manage lifecycle manually
client = CosmosClient(url, credential)
try:
    database = client.get_database_client("mydb")
    container = database.get_container_client("mycontainer")
    item = await container.read_item(item="id1", partition_key="pk1")
finally:
    await client.close()

비동기 및 동기화를 사용하는 경우

Scenario 권장 클라이언트
웹 프레임워크(FastAPI, Quart) azure.cosmos.aio.CosmosClient
서버리스(Azure Functions 비동기) azure.cosmos.aio.CosmosClient
스크립트 및 일괄 처리 작업 azure.cosmos.CosmosClient
간단한 CLI 도구 azure.cosmos.CosmosClient

Warning

비동기 이벤트 루프 내에서 동기화 CosmosClient 를 사용하지 마세요. 동기화 클라이언트는 이벤트 루프를 차단하는 I/O 호출을 차단하여 성능을 저하시키고 애플리케이션에서 교착 상태를 일으킬 수 있습니다.

자세한 내용은 Python SDK README 비동기 섹션을 참조하십시오.

데이터 디자인

데이터 디자인 매개 변수

매개 변수 기본 또는 제약 조건 사용 시기
문서 크기 N/A RU 비용을 줄이기 위해 작게 유지
식별자 문자 특수 문자 없음 예기치 않은 동작 방지
인덱싱 경로 인덱싱된 모든 경로 더 빠른 쓰기를 위해 사용되지 않는 경로 제외 
container_properties = {
    "id": "items",
    "indexingPolicy": {
        "excludedPaths": [{"path": "/*"}]
    }
}
print(container_properties["indexingPolicy"])
# Expected: excludedPaths configured

자세한 내용은 SDK 샘플을 사용하여 인덱스 만들기를 참조하세요.

호스트 특성

호스트 특성 매개 변수

매개 변수 기본 또는 제약 조건 사용 시기
CPU 사용률 <70% 권장 높으면 강화 또는 확장
가속화된 네트워킹 비활성화 트래픽이 많은 VM에서 활성화
쿼리 페이지 크기 100개 항목/4MB 왕복을 줄이기 위해 늘리기 
items = container.query_items(
    query="SELECT * FROM c",
    max_item_count=500
)
print("Page size set to 500")
# Expected: fewer round trips

다음 단계

Python SDK의 성능 팁에 대한 자세한 내용은 Azure Cosmos DB Python SDK에 대한 성능 팁을 참조하세요.

확장성 및 고성능을 위한 애플리케이션 설계 방법에 대한 자세한 내용은 Azure Cosmos DB의 분할 및 크기 조정을 참조하세요.

Azure Cosmos DB로 마이그레이션하기 위한 용량 계획을 수행하려고 하시나요? 용량 계획을 위해 기존 데이터베이스 클러스터에 대한 정보를 사용할 수 있습니다.

  • Last updated on