고지 사항

Python 2.7에 대한 Azure SDK Python 패키지 지원은 2022년 1월 1일에 종료되었습니다. 자세한 내용과 질문은 을 참조하세요. https://github.com/Azure/azure-sdk-for-python/issues/20691

Python용 Azure Cosmos DB SQL API 클라이언트 라이브러리 - 버전 4.5.1

Azure Cosmos DB는 문서, 키-값, 넓은 열 및 그래프 데이터베이스를 지원하는 전세계로 분산된 다중 모델 데이터베이스 서비스입니다.

Python용 Azure Cosmos DB SQL API SDK를 사용하여 이 NoSQL 데이터베이스 서비스에 포함된 데이터베이스 및 JSON 문서를 관리합니다. 높은 수준의 기능은 다음과 같습니다.

• Cosmos DB 데이터베이스 만들기 및 설정 수정
• JSON 문서의 컬렉션을 저장하도록 컨테이너 만들기 및 수정
• 컨테이너에서 항목 만들기, 읽기, 업데이트 및 삭제(JSON 문서)
• SQL과 유사한 구문을 사용하여 데이터베이스의 문서 쿼리

SDK 소스 코드 | 패키지(PyPI) | 패키지(Conda) | API 참조 설명서 | 제품 설명서 | 샘플

이 SDK는 SQL API에 사용됩니다. 다른 모든 API의 경우 Azure Cosmos DB 설명서를 검사 프로젝트에 가장 적합한 SDK를 평가하세요.

시작

Python 2.x의 중요 업데이트 지원

이 SDK의 새 릴리스는 2022년 1월 1일부터 Python 2.x를 지원하지 않습니다. 자세한 내용은 CHANGELOG를 확인하세요.

사전 요구 사항

• Azure 구독 -체험 계정 만들기
• Azure Cosmos DB 계정 - SQL API
• Python 3.6+

Cosmos DB SQL API 계정이 필요한 경우 다음 Azure CLI 명령을 사용하여 계정을 만들 수 있습니다.

az cosmosdb create --resource-group <resource-group-name> --name <cosmos-account-name>

패키지 설치

pip install azure-cosmos

가상 환경 구성(선택 사항)

필수는 아니지만, 가상 환경을 사용하는 경우 기본 시스템 및 Azure SDK 환경을 서로 격리할 수 있습니다. 다음 명령을 실행하여 구성한 다음 , venv를 사용하여 가상 환경을 입력합니다.

python3 -m venv azure-cosmosdb-sdk-environment
source azure-cosmosdb-sdk-environment/bin/activate

클라이언트 인증

Cosmos DB와의 상호 작용은 CosmosClient 클래스의 instance 시작합니다. 클라이언트 개체를 인스턴스화하려면 계정, 해당 URI 및 해당 계정 키 중 하나가 필요합니다.

아래 Azure CLI 코드 조각을 사용하여 데이터베이스 계정 URI 및 기본 master 키로 두 환경 변수를 채웁니다(Azure Portal 이러한 값을 찾을 수도 있음). 조각은 Bash 셸에 대해 서식이 지정됩니다.

RES_GROUP=<resource-group-name>
ACCT_NAME=<cosmos-db-account-name>

export ACCOUNT_URI=$(az cosmosdb show --resource-group $RES_GROUP --name $ACCT_NAME --query documentEndpoint --output tsv)
export ACCOUNT_KEY=$(az cosmosdb list-keys --resource-group $RES_GROUP --name $ACCT_NAME --query primaryMasterKey --output tsv)

클라이언트 만들기

및 ACCOUNT_KEY 환경 변수를 ACCOUNT_URI 채우면 CosmosClient를 만들 수 있습니다.

from azure.cosmos import CosmosClient

import os
URL = os.environ['ACCOUNT_URI']
KEY = os.environ['ACCOUNT_KEY']
client = CosmosClient(URL, credential=KEY)

AAD 인증

서비스 주체의 AAD 자격 증명 및 Azure ID 패키지를 사용하여 클라이언트를 인증할 수도 있습니다. 자격 증명 정보를 ClientSecretCredential에 직접 전달하거나 DefaultAzureCredential을 사용할 수 있습니다.

from azure.cosmos import CosmosClient
from azure.identity import ClientSecretCredential, DefaultAzureCredential

import os
url = os.environ['ACCOUNT_URI']
tenant_id = os.environ['TENANT_ID']
client_id = os.environ['CLIENT_ID']
client_secret = os.environ['CLIENT_SECRET']

# Using ClientSecretCredential
aad_credentials = ClientSecretCredential(
    tenant_id=tenant_id,
    client_id=client_id,
    client_secret=client_secret)

# Using DefaultAzureCredential (recommended)
aad_credentials = DefaultAzureCredential()

client = CosmosClient(url, aad_credentials)

항상 AAD 인증 readMetadata 에 사용하는 관리 ID에 권한이 있는지 확인합니다.
AAD 인증을 설정하는 방법에 대한 자세한 정보: AAD 인증을 위한 RBAC 설정
AAD 인증 클라이언트에 허용되는 작업에 대한 자세한 정보: RBAC 권한 모델

주요 개념

CosmosClient를 초기화한 후에는 Cosmos DB의 기본 리소스 종류와 상호 작용할 수 있습니다.

• 데이터베이스: Cosmos DB 계정은 여러 데이터베이스를 포함할 수 있습니다. 데이터베이스를 만드는 경우 문서와 상호 작용할 때 사용할 API를 지정합니다. SQL, MongoDB, Gremlin, Cassandra 또는 Azure Table. DatabaseProxy 개체를 사용하여 컨테이너를 관리합니다.

• 컨테이너: 컨테이너는 JSON 문서의 컬렉션입니다. ContainerProxy 개체의 메서드를 사용하여 컨테이너에서 항목을 만들거나, 읽고, 업데이트하고, 삭제합니다.

• 항목: 항목은 컨테이너에 저장된 JSON 문서의 사전과 유사한 표현입니다. 컨테이너에 추가하는 각 항목에는 컨테이너 내에서 항목을 고유하게 식별하는 값이 있는 키가 포함되어 id 야 합니다.

이러한 리소스에 대한 자세한 내용은 Azure Cosmos 데이터베이스, 컨테이너, 항목 작업을 참조하세요.

사용 방법 enable_cross_partition_query

키워드(keyword) 인수 enable_cross_partition_query 는 (기본값) 또는 True의 두 가지 옵션을 None 허용합니다.

ID별 쿼리 사용에 대한 참고 사항

ID 값을 기반으로 항목을 찾으려는 쿼리를 사용하는 경우 항상 문자열 형식 변수를 전달해야 합니다. Azure Cosmos DB는 문자열 ID 값만 허용하며 다른 데이터 형식을 사용하는 경우 이 SDK는 결과와 오류 메시지를 반환하지 않습니다.

클라이언트 일관성 수준에 대한 참고 사항

릴리스 버전 4.3.0b3을 기준으로 사용자가 명시적 일관성 수준을 클라이언트 초기화에 전달하지 않으면 클라이언트는 데이터베이스 계정의 기본 수준을 사용합니다. 이전에는 기본값이 일관성으로 Session 설정되었습니다. 어떤 이유로 이 작업을 계속하려면 다음과 같이 명시적 매개 변수를 포함하도록 클라이언트 초기화를 변경할 수 있습니다.

from azure.cosmos import CosmosClient

import os
URL = os.environ['ACCOUNT_URI']
KEY = os.environ['ACCOUNT_KEY']
client = CosmosClient(URL, credential=KEY, consistency_level='Session')

제한 사항

현재 아래 기능은 지원되지 않습니다. 대체 옵션의 경우 아래 해결 방법 섹션을 검사.

데이터 평면 제한 사항:

• 그룹화 기준 쿼리
• DISTINCT 하위 쿼리의 COUNT가 있는 쿼리: SELECT COUNT (1) FROM (SELECT DISTINCT C.ID FROM C)
• 대량/트랜잭션 일괄 처리
• 직접 TCP 모드 액세스
• 정렬, 계산 및 고유와 같은 집계 파티션 간 쿼리에 대한 연속 토큰 지원. 와 같은SELECT * FROM WHERE 스트리밍 가능한 쿼리는 연속 토큰을 지원합니다.
• 변경 피드: 프로세서
• 변경 피드: 여러 파티션 키 값 읽기
• 변경 피드: 특정 시간 읽기
• 변경 피드: 처음부터 읽기
• 변경 피드: 끌어오기 모델
• 혼합 형식에 대한 파티션 간 ORDER BY
• 비동기 쿼리 형식 메서드에 진단 사용

컨트롤 플레인 제한 사항:

• CollectionSizeUsage, DatabaseUsage 및 DocumentUsage 메트릭 가져오기
• 지리 공간적 인덱스 만들기
• 연결 문자열 가져오기
• 컨테이너의 최소 RU/s 가져오기

해결 방법

대량 처리 제한 해결 방법

Python SDK를 사용하여 Cosmos DB에 대량 삽입을 수행하려는 경우 저장 프로시저 를 사용하여 동일한 파티션 키를 사용하여 여러 항목을 작성하는 것이 가장 좋습니다.

컨트롤 플레인 제한 해결 방법

일반적으로 지원되지 않는 컨트롤 플레인 제한에는 Azure Portal, Azure Cosmos DB 리소스 공급자 REST API, Azure CLI 또는 PowerShell 을 사용할 수 있습니다.

Boolean 데이터 형식

Python 언어는 부울 형식에 "True" 및 "False"를 사용 하지만 Cosmos DB는 "true" 및 "false"만 허용합니다 . 즉, Python 언어는 첫 번째 대문자와 다른 모든 소문자와 함께 부울 값을 사용하고 Cosmos DB 및 해당 SQL 언어는 동일한 부울 값에 소문자만 사용합니다. 이 문제를 해결하는 방법

• Python으로 만든 JSON 문서는 언어 유효성 검사를 통과하려면 "True" 및 "False"를 사용해야 합니다. SDK는 이를 "true" 및 "false"로 변환합니다. "true" 및 "false"는 Cosmos DB에 저장됩니다.
• Cosmos DB 포털의 Data Explorer 사용하여 해당 문서를 검색하면 "true" 및 "false"가 표시됩니다.
• 이 Python SDK를 사용하여 해당 문서를 검색하면 "true" 및 "false" 값이 자동으로 "True" 및 "False"로 변환됩니다.

SQL 쿼리 x FROM 절 하위 항목

이 SDK는 query_items 메서드를 사용하여 Azure Cosmos DB에 SQL 쿼리를 제출합니다.

Cosmos DB SQL 언어를 사용하면 FROM 절을 사용하여 하위 항목을 가져와 원본을 더 작은 하위 집합으로 줄일 수 있습니다. 예를 들어 대신 select * from Families를 사용할 select * from Families.children 수 있습니다. 하지만 다음 사항에 유의하세요.

• 메서드를 사용하는 SQL 쿼리의 query_items 경우 이 SDK는 플래그를 partition_key 지정하거나 플래그를 enable_cross_partition_query 사용해야 합니다.
• 하위 항목을 가져오고 을 지정하는 partition_key경우 파티션 키가 하위 항목에 포함되어 있는지 확인합니다. 이 키는 대부분의 경우에 해당되지 않습니다.

최대 항목 수

이는 query_items 메서드의 매개 변수로, 페이지당 반환될 최대 항목 수를 나타내는 정수입니다. 서비스가 None 최적의 항목 수를 결정할 수 있도록 값을 지정할 수 있습니다. 이는 권장되는 구성 값이며 설정되지 않은 경우 이 SDK의 기본 동작입니다.

예제

다음 섹션에서는 다음을 비롯한 가장 일반적인 Cosmos DB 작업 몇 가지에 대한 여러 코드 조각을 제공합니다.

• 데이터베이스 만들기
• 컨테이너 만들기
• 분석 저장소 사용 컨테이너 만들기
• 기존 컨테이너 가져오기
• 데이터 삽입
• 데이터 삭제
• 데이터베이스 쿼리
• 데이터베이스 속성 가져오기
• 데이터베이스 및 컨테이너 처리량 가져오기
• 컨테이너 속성 수정
• 비동기 클라이언트 사용

데이터베이스 만들기

CosmosClient를 인증한 후 계정의 모든 리소스로 작업할 수 있습니다. 아래 코드 조각은 SQL API 데이터베이스를 만듭니다. 이 데이터베이스는 create_database 호출될 때 API가 지정되지 않은 경우 기본값입니다.

from azure.cosmos import CosmosClient, exceptions
import os

URL = os.environ['ACCOUNT_URI']
KEY = os.environ['ACCOUNT_KEY']
client = CosmosClient(URL, credential=KEY)
DATABASE_NAME = 'testDatabase'
try:
    database = client.create_database(DATABASE_NAME)
except exceptions.CosmosResourceExistsError:
    database = client.get_database_client(DATABASE_NAME)

컨테이너 만들기

이 예제에서는 기본 설정을 사용하여 컨테이너를 만듭니다. 이름이 같은 컨테이너가 데이터베이스에 이미 있는 경우(오류 생성 409 Conflict ) 기존 컨테이너를 대신 가져옵니다.

from azure.cosmos import CosmosClient, PartitionKey, exceptions
import os

URL = os.environ['ACCOUNT_URI']
KEY = os.environ['ACCOUNT_KEY']
client = CosmosClient(URL, credential=KEY)
DATABASE_NAME = 'testDatabase'
database = client.get_database_client(DATABASE_NAME)
CONTAINER_NAME = 'products'

try:
    container = database.create_container(id=CONTAINER_NAME, partition_key=PartitionKey(path="/productName"))
except exceptions.CosmosResourceExistsError:
    container = database.get_container_client(CONTAINER_NAME)
except exceptions.CosmosHttpResponseError:
    raise

분석 저장소 지원 컨테이너 생성

이 예제에서는 Azure Synapse Link를 사용하여 보고, BI, AI 및 Advanced Analytics에 대해 분석 저장소를 사용하도록 설정된 컨테이너를 만듭니다.

analytical_storage_ttl 옵션은 다음과 같습니다.

• 0 또는 Null 또는 알 수 없음: 사용하도록 설정되지 않았습니다.
• -1: 데이터가 무한히 저장됩니다.
• 다른 숫자: 실제 ttl(초)입니다.

CONTAINER_NAME = 'products'
try:
    container = database.create_container(id=CONTAINER_NAME, partition_key=PartitionKey(path="/productName"),analytical_storage_ttl=-1)
except exceptions.CosmosResourceExistsError:
    container = database.get_container_client(CONTAINER_NAME)
except exceptions.CosmosHttpResponseError:
    raise

위의 코드 조각은 컨테이너 만들기에 실패한 경우 CosmosHttpResponseError 예외도 처리합니다. 오류 처리 및 문제 해결에 대한 자세한 내용은 참조하세요.

기존 컨테이너 가져오기

데이터베이스에서 기존 컨테이너를 검색합니다.

from azure.cosmos import CosmosClient
import os

URL = os.environ['ACCOUNT_URI']
KEY = os.environ['ACCOUNT_KEY']
client = CosmosClient(URL, credential=KEY)
DATABASE_NAME = 'testDatabase'
database = client.get_database_client(DATABASE_NAME)
CONTAINER_NAME = 'products'
container = database.get_container_client(CONTAINER_NAME)

데이터 삽입

컨테이너에 항목을 삽입하려면 데이터가 포함된 사전을 ContainerProxy.upsert_item 전달합니다. 컨테이너에 추가하는 각 항목에는 컨테이너 내의 id 항목을 고유하게 식별하는 값이 있는 키가 포함되어야 합니다.

다음은 컨테이너에 여러 항목을 삽입하는 예제입니다. 각 항목은 고유한 id입니다.

from azure.cosmos import CosmosClient
import os

URL = os.environ['ACCOUNT_URI']
KEY = os.environ['ACCOUNT_KEY']
client = CosmosClient(URL, credential=KEY)
DATABASE_NAME = 'testDatabase'
database = client.get_database_client(DATABASE_NAME)
CONTAINER_NAME = 'products'
container = database.get_container_client(CONTAINER_NAME)

for i in range(1, 10):
    container.upsert_item({
            'id': 'item{0}'.format(i),
            'productName': 'Widget',
            'productModel': 'Model {0}'.format(i)
        }
    )

데이터 삭제

컨테이너에서 항목을 삭제하려면 ContainerProxy.delete_item 사용합니다. Cosmos DB의 SQL API는 SQL DELETE 문을 지원하지 않습니다.

from azure.cosmos import CosmosClient
import os

URL = os.environ['ACCOUNT_URI']
KEY = os.environ['ACCOUNT_KEY']
client = CosmosClient(URL, credential=KEY)
DATABASE_NAME = 'testDatabase'
database = client.get_database_client(DATABASE_NAME)
CONTAINER_NAME = 'products'
container = database.get_container_client(CONTAINER_NAME)

for item in container.query_items(
        query='SELECT * FROM products p WHERE p.productModel = "Model 2"',
        enable_cross_partition_query=True):
    container.delete_item(item, partition_key='Widget')

참고: 분할된 컬렉션을 사용하는 경우 위의 예제 코드에 있는 의 partitionKey 값을 컬렉션의 파티션 키 열 이름이 아닌 이 특정 항목의 파티션 키 값으로 설정해야 합니다. 이는 지점 읽기 및 삭제 모두에 대해 true입니다.

데이터베이스 쿼리

Cosmos DB SQL API 데이터베이스는 SQL과 유사한 구문을 사용하여 ContainerProxy.query_items 사용하여 컨테이너의 항목 쿼리를 지원합니다.

이 예제에서는 특정 id를 사용하는 항목에 대해 컨테이너를 쿼리합니다.

from azure.cosmos import CosmosClient
import os

URL = os.environ['ACCOUNT_URI']
KEY = os.environ['ACCOUNT_KEY']
client = CosmosClient(URL, credential=KEY)
DATABASE_NAME = 'testDatabase'
database = client.get_database_client(DATABASE_NAME)
CONTAINER_NAME = 'products'
container = database.get_container_client(CONTAINER_NAME)

# Enumerate the returned items
import json
for item in container.query_items(
        query='SELECT * FROM mycontainer r WHERE r.id="item3"',
        enable_cross_partition_query=True):
    print(json.dumps(item, indent=True))

참고: 절에서 FROM 컨테이너 이름에 대한 값을 지정할 수 있지만 일관성을 위해 컨테이너 이름을 사용하는 것이 좋습니다.

매개 변수와 해당 값이 포함된 사전을 ContainerProxy.query_items 전달하여 매개 변수가 있는 쿼리를 수행합니다.

discontinued_items = container.query_items(
    query='SELECT * FROM products p WHERE p.productModel = @model',
    parameters=[
        dict(name='@model', value='Model 7')
    ],
    enable_cross_partition_query=True
)
for item in discontinued_items:
    print(json.dumps(item, indent=True))

SQL API를 사용하여 Cosmos DB 데이터베이스를 쿼리하는 방법에 대한 자세한 내용은 SQL 쿼리를 사용하여 Azure Cosmos DB 데이터 쿼리를 참조하세요.

데이터베이스 속성 가져오기

데이터베이스의 속성을 가져와서 표시합니다.

from azure.cosmos import CosmosClient
import os
import json

URL = os.environ['ACCOUNT_URI']
KEY = os.environ['ACCOUNT_KEY']
client = CosmosClient(URL, credential=KEY)
DATABASE_NAME = 'testDatabase'
database = client.get_database_client(DATABASE_NAME)
properties = database.read()
print(json.dumps(properties))

데이터베이스 및 컨테이너 처리량 가져오기

전용 처리량이 있는 데이터베이스 및 컨테이너의 처리량 값을 가져와서 표시합니다.

from azure.cosmos import CosmosClient
import os
import json

URL = os.environ['ACCOUNT_URI']
KEY = os.environ['ACCOUNT_KEY']
client = CosmosClient(URL, credential=KEY)

# Database
DATABASE_NAME = 'testDatabase'
database = client.get_database_client(DATABASE_NAME)
db_offer = database.read_offer()
print('Found Offer \'{0}\' for Database \'{1}\' and its throughput is \'{2}\''.format(db_offer.properties['id'], database.id, db_offer.properties['content']['offerThroughput']))

# Container with dedicated throughput only. Will return error "offer not found" for containers without dedicated throughput
CONTAINER_NAME = 'testContainer'
container = database.get_container_client(CONTAINER_NAME)
container_offer = container.read_offer()
print('Found Offer \'{0}\' for Container \'{1}\' and its throughput is \'{2}\''.format(container_offer.properties['id'], container.id, container_offer.properties['content']['offerThroughput']))

컨테이너 속성 수정

기존 컨테이너의 특정 속성을 수정할 수 있습니다. 다음은 컨테이너의 항목에 대한 TTL(기본 TTL)을 10초로 설정하는 예제입니다.

from azure.cosmos import CosmosClient, PartitionKey
import os
import json

URL = os.environ['ACCOUNT_URI']
KEY = os.environ['ACCOUNT_KEY']
client = CosmosClient(URL, credential=KEY)
DATABASE_NAME = 'testDatabase'
database = client.get_database_client(DATABASE_NAME)
CONTAINER_NAME = 'products'
container = database.get_container_client(CONTAINER_NAME)

database.replace_container(
    container,
    partition_key=PartitionKey(path="/productName"),
    default_ttl=10,
)
# Display the new TTL setting for the container
container_props = container.read()
print(json.dumps(container_props['defaultTtl']))

TTL에 대한 자세한 내용은 Azure Cosmos DB 데이터에 대한 Time to Live를 참조하세요.

비동기 클라이언트 사용

비동기 cosmos 클라이언트는 기존 동기 클라이언트와 비슷한 방식으로 보이고 작동하는 별도의 클라이언트입니다. 그러나 비동기 클라이언트를 별도로 가져와야 하며 해당 메서드를 비동기/await 키워드와 함께 사용해야 합니다. 비동기 클라이언트는 수동으로 또는 컨텍스트 관리자를 사용하여 수행할 수 있는 사용 후 초기화 및 닫아야 합니다. 아래 예제에서는 수동으로 수행하는 방법을 보여줍니다.

from azure.cosmos.aio import CosmosClient
import os

URL = os.environ['ACCOUNT_URI']
KEY = os.environ['ACCOUNT_KEY']
DATABASE_NAME = 'testDatabase'
CONTAINER_NAME = 'products'    

async def create_products():
    client = CosmosClient(URL, credential=KEY)
    database = client.get_database_client(DATABASE_NAME)
    container = database.get_container_client(CONTAINER_NAME)
    for i in range(10):
        await container.upsert_item({
                'id': 'item{0}'.format(i),
                'productName': 'Widget',
                'productModel': 'Model {0}'.format(i)
            }
        )
    await client.close() # the async client must be closed manually if it's not initialized in a with statement

클라이언트를 수동으로 열고 닫는 대신 키워드를 사용하는 async with 것이 좋습니다. 문에서 벗어나면 클라이언트를 초기화하고 나중에 닫는 컨텍스트 관리자를 만듭니다. 아래 예제에서는 이 작업을 수행하는 방법을 보여 주세요.

from azure.cosmos.aio import CosmosClient
import os

URL = os.environ['ACCOUNT_URI']
KEY = os.environ['ACCOUNT_KEY']
DATABASE_NAME = 'testDatabase'
CONTAINER_NAME = 'products'

async def create_products():
    async with CosmosClient(URL, credential=KEY) as client: # the with statement will automatically initialize and close the async client
        database = client.get_database_client(DATABASE_NAME)
        container = database.get_container_client(CONTAINER_NAME)
        for i in range(10):
            await container.upsert_item({
                    'id': 'item{0}'.format(i),
                    'productName': 'Widget',
                    'productModel': 'Model {0}'.format(i)
                }
            )

비동기 클라이언트를 사용하는 쿼리

동기 클라이언트와 달리 비동기 클라이언트에는 enable_cross_partition 요청에 플래그가 없습니다. 지정된 파티션 키 값이 없는 쿼리는 기본적으로 파티션 간 쿼리를 수행하려고 시도합니다.

쿼리 결과를 반복할 수 있지만 쿼리의 원시 출력은 비동기 반복기를 반환합니다. 즉, 반복기의 각 개체는 대기 가능한 개체이며 아직 실제 쿼리 결과를 포함하지 않습니다. 쿼리 결과를 얻으려면 개체를 반복할 때 각 결과를 대기하는 비동기 for 루프를 사용하거나 비동기 반복기를 반복할 때 각 쿼리 결과를 수동으로 대기할 수 있습니다.

쿼리 결과는 비동기 반복기이므로 목록으로 직접 캐스팅할 수 없습니다. 대신 결과에서 목록을 만들어야 하는 경우 비동기 for 루프 또는 Python의 목록 이해를 사용하여 목록을 채웁니다.

from azure.cosmos.aio import CosmosClient
import os

URL = os.environ['ACCOUNT_URI']
KEY = os.environ['ACCOUNT_KEY']
client = CosmosClient(URL, credential=KEY)
DATABASE_NAME = 'testDatabase'
database = client.get_database_client(DATABASE_NAME)
CONTAINER_NAME = 'products'
container = database.get_container_client(CONTAINER_NAME)

async def create_lists():
    results = container.query_items(
            query='SELECT * FROM products p WHERE p.productModel = "Model 2"')

    # iterates on "results" iterator to asynchronously create a complete list of the actual query results

    item_list = []
    async for item in results:
        item_list.append(item)

    # Asynchronously creates a complete list of the actual query results. This code performs the same action as the for-loop example above.
    item_list = [item async for item in results]
    await client.close()

통합 캐시 사용

통합 캐시는 요청 볼륨이 증가함에 따라 관리 가능한 비용과 짧은 대기 시간을 보장하는 데 도움이 되는 메모리 내 캐시입니다. 통합 캐시에는 지점 읽기에 대한 항목 캐시와 쿼리용 쿼리 캐시의 두 부분이 있습니다. 아래 코드 조각에서는 지점 읽기 및 쿼리 캐시 메서드와 함께 이 기능을 사용하는 방법을 보여 줍니다.

이를 사용하면 통합 캐시에 도달한 지점 읽기 및 쿼리가 RU를 사용하지 않는다는 이점이 있습니다. 즉, 백 엔드에서 읽는 것보다 작업당 비용이 훨씬 낮습니다.

Azure Cosmos DB 통합 캐시를 구성하는 방법(미리 보기)

import azure.cosmos.cosmos_client as cosmos_client
import os

URL = os.environ['ACCOUNT_URI']
KEY = os.environ['ACCOUNT_KEY']
client = cosmos_client.CosmosClient(URL, credential=KEY)
DATABASE_NAME = 'testDatabase'
database = client.get_database_client(DATABASE_NAME)
CONTAINER_NAME = 'testContainer'
container = database.get_container_client(CONTAINER_NAME)

def integrated_cache_snippet():
    item_id = body['id'] 
    query = 'SELECT * FROM c'

    #item cache
    container.read_item(item=item_id, partition_key=item_id, max_integrated_cache_staleness_in_ms=30000)

    #query cache   
    container.query_items(query=query,
         partition_key=item_id, max_integrated_cache_staleness_in_ms=30000)

통합 캐시에 대한 자세한 내용은 Azure Cosmos DB 통합 캐시 - 개요를 참조하세요.

문제 해결

일반

Python SDK를 사용하여 Cosmos DB와 상호 작용하는 경우 서비스에서 반환되는 예외는 REST API 요청에 대해 반환된 동일한 HTTP 상태 코드에 해당합니다.

Azure Cosmos DB에 대한 HTTP 상태 코드

예를 들어 Cosmos DB 데이터베이스 409 에서 이미 사용 중인 ID(이름)를 사용하여 컨테이너를 만들려고 하면 충돌을 나타내는 오류가 반환됩니다. 다음 코드 조각에서 오류는 예외를 catch하고 오류에 대한 추가 정보를 표시하여 적절히 처리됩니다.

try:
    database.create_container(id=CONTAINER_NAME, partition_key=PartitionKey(path="/productName"))
except exceptions.CosmosResourceExistsError:
    print("""Error creating container
HTTP status code 409: The ID (name) provided for the container is already in use.
The container name must be unique within the database.""")

로깅

이 라이브러리는 로깅에 표준 로깅 라이브러리를 사용합니다. HTTP 세션(URL, 헤더 등)에 대한 기본 정보는 INFO 수준에서 기록됩니다.

요청/응답 본문 및 수정되지 않은 헤더를 포함한 자세한 DEBUG 수준 로깅은 인수가 있는 클라이언트 logging_enable 에서 사용하도록 설정할 수 있습니다.

import sys
import logging
from azure.cosmos import CosmosClient

# Create a logger for the 'azure' SDK
logger = logging.getLogger('azure')
logger.setLevel(logging.DEBUG)

# Configure a console output
handler = logging.StreamHandler(stream=sys.stdout)
logger.addHandler(handler)

# This client will log detailed information about its HTTP sessions, at DEBUG level
client = CosmosClient(URL, credential=KEY, logging_enable=True)

마찬가지로 logging_enable은 클라이언트에 대해 상세 로깅을 사용하지 않는 경우에도 한 작업에만 사용하게 설정할 수 있습니다.

database = client.create_database(DATABASE_NAME, logging_enable=True)

또는 로거를 인수에 전달하여 Azure Core HttpLoggingPolicy에서 확장하는 CosmosHttpLoggingPolicy를 사용하여 로깅할 logger 수 있습니다. 기본적으로 HttpLoggingPolicy의 동작을 사용합니다. 인수를 enable_diagnostics_logging 전달하면 CosmosHttpLoggingPolicy가 활성화되고 Cosmos 문제 디버깅과 관련된 응답에 추가 정보가 있습니다.

import logging
from azure.cosmos import CosmosClient

#Create a logger for the 'azure' SDK
logger = logging.getLogger('azure')
logger.setLevel(logging.DEBUG)

# Configure a file output
handler = logging.FileHandler(filename="azure")
logger.addHandler(handler)

# This client will log diagnostic information from the HTTP session by using the CosmosHttpLoggingPolicy.
# Since we passed in the logger to the client, it will log information on every request.
client = CosmosClient(URL, credential=KEY, logger=logger, enable_diagnostics_logging=True)

마찬가지로 로거를 단일 요청에 전달하여 단일 작업에 대해 로깅을 사용하도록 설정할 수 있습니다. 그러나 CosmosHttpLoggingPolicy를 사용하여 추가 정보를 enable_diagnostics_logging 가져오려면 클라이언트 생성자에서 인수를 전달해야 합니다.

# This example enables the CosmosHttpLoggingPolicy and uses it with the `logger` passed in to the `create_database` request.
client = CosmosClient(URL, credential=KEY, enable_diagnostics_logging=True)
database = client.create_database(DATABASE_NAME, logger=logger)

원격 분석

Azure Core는 Python SDK가 OpenTelemetry를 사용할 수 있는 기능을 제공합니다. 이 기능을 사용하기 위해 설치해야 하는 유일한 패키지는 다음과 같습니다.

pip install azure-core-tracing-opentelemetry
pip install opentelemetry-sdk

이에 대한 자세한 내용은 Azure Core에서 설정하는 방법을 설명하는 이 문서를 살펴보는 것이 좋습니다. SDK와 함께 사용할 수 있는 방법을 보여 주는 샘플 파일 도 추가되었습니다. 이는 사용 중인 Cosmos 클라이언트에 관계없이 동일한 방식으로 작동합니다.

다음 단계

Cosmos DB 서비스에 대한 보다 광범위한 설명서는 docs.microsoft.com에 있는 Azure Cosmos DB 문서를 참조하세요.

참여

이 프로젝트에 대한 기여와 제안을 환영합니다. 대부분의 경우 기여하려면 권한을 부여하며 실제로 기여를 사용할 권한을 당사에 부여한다고 선언하는 CLA(기여자 라이선스 계약)에 동의해야 합니다. 자세한 내용은 https://cla.microsoft.com 을 참조하세요.

끌어오기 요청을 제출하면 CLA-bot은 CLA를 제공하고 PR을 적절하게 데코레이팅해야 하는지 여부를 자동으로 결정합니다(예: 레이블, 설명). 봇에서 제공하는 지침을 따르기만 하면 됩니다. 이 작업은 CLA를 사용하여 모든 리포지토리에서 한 번만 수행하면 됩니다.

이 프로젝트에는 Microsoft Open Source Code of Conduct(Microsoft 오픈 소스 준수 사항)가 적용됩니다. 자세한 내용은 Code of Conduct FAQ(규정 FAQ)를 참조하세요. 또는 추가 질문이나 의견은 opencode@microsoft.com으로 문의하세요.