CosmosClient 클래스

Azure Cosmos DB 계정의 클라이언트 쪽 논리적 표현입니다.

이 클라이언트를 사용하여 Azure Cosmos DB 서비스에 대한 요청을 구성하고 실행합니다.

효율적인 연결 관리 및 성능을 가능하게 하는 애플리케이션의 수명당 CosmosClient의 단일 instance 유지하는 것이 좋습니다.

CosmosClient 초기화는 많은 작업입니다. 초기화 CosmosClient 인스턴스를 자격 증명 또는 네트워크 연결 유효성 검사로 사용하지 마세요.

새 CosmosClient를 인스턴스화합니다.

상속

builtins.object

CosmosClient

생성자

CosmosClient(url: str, credential: Any, consistency_level: str | None = None, **kwargs: Any)

매개 변수

url

str

필수

Cosmos DB 계정의 URL입니다.

credential

Union[str, Dict[str, str], TokenCredential]

필수

계정 키 또는 리소스 토큰의 사전일 수 있습니다.

consistency_level

str

기본값: None

세션에 사용할 일관성 수준입니다. 기본값은 None(계정 수준)입니다. 일관성 수준 및 가능한 값에 대한 자세한 내용: https://aka.ms/cosmos-consistency-levels

timeout

int

결합된 HTTP 요청 및 응답 처리에 대한 절대 시간 제한(초)입니다.

connection_timeout

int

HTTP 요청 시간 제한(초)입니다.

connection_mode

str

클라이언트에 대한 연결 모드 - 현재 '게이트웨이'만 지원합니다.

proxy_config

ProxyConfiguration

연결 프록시 구성.

ssl_config

SSLConfiguration

연결 SSL 구성.

connection_verify

bool

연결을 확인할지 여부에 관계없이 기본값은 True입니다.

connection_cert

str

연결을 확인하는 대체 인증서입니다.

retry_total

int

최대 재시도 횟수입니다.

retry_backoff_max

int

최대 재시도 대기 시간(초)입니다.

retry_fixed_interval

int

재시도 간격을 밀리초 단위로 수정했습니다.

retry_read

int

소켓 읽기 재시도 최대 횟수입니다.

retry_connect

int

최대 연결 오류 재시도 횟수입니다.

retry_status

int

오류 상태 코드에 대한 최대 재시도 횟수입니다.

retry_on_status_codes

list[int]

다시 시도할 특정 상태 코드 목록입니다.

retry_backoff_factor

float

다시 시도 사이의 대기 시간을 계산하는 요인입니다.

enable_endpoint_discovery

bool

지역에서 복제된 데이터베이스 계정에 엔드포인트 검색을 사용하도록 설정합니다. (기본값: True)

preferred_locations

list[str]

지역에서 복제된 데이터베이스 계정에 대한 기본 설정 위치입니다.

enable_diagnostics_logging

bool

CosmosHttpLogging 정책을 사용하도록 설정합니다. 작동하려면 로거와 함께 사용해야 합니다.

logger

Logger

요청 진단 수집하는 데 사용할 로거입니다. 클라이언트 수준(모든 요청을 기록하기 위해) 또는 단일 요청 수준에서 전달할 수 있습니다. 요청은 INFO 수준에서 기록됩니다.

예제

Cosmos DB 클라이언트의 새 instance 만듭니다.

   from azure.cosmos import exceptions, CosmosClient, PartitionKey

   import os

   url = os.environ["ACCOUNT_URI"]
   key = os.environ["ACCOUNT_KEY"]
   client = CosmosClient(url, key)

메서드

create_database	지정된 ID(이름)를 사용하여 새 데이터베이스를 만듭니다.
create_database_if_not_exists	데이터베이스가 아직 없는 경우 만듭니다. 데이터베이스가 이미 있는 경우 기존 설정이 반환됩니다. .. 참고:: 이 함수는 기존 데이터베이스 설정을 검사 업데이트하거나 전달된 것과 다른 경우 처리량을 제공하지 않습니다.
delete_database	지정된 ID(이름)를 사용하여 데이터베이스를 삭제합니다.
from_connection_string	연결 문자열에서 CosmosClient instance 만듭니다. Azure Portal 검색할 수 있습니다. 선택적 키워드(keyword) 인수의 전체 목록은 CosmosClient 생성자를 참조하세요.
get_database_account	데이터베이스 계정 정보를 검색합니다.
get_database_client	ID(이름) ID를 사용하여 기존 데이터베이스를 검색합니다.
list_databases	Cosmos DB SQL 데이터베이스 계정의 데이터베이스를 나열합니다.
query_databases	Cosmos DB SQL 데이터베이스 계정의 데이터베이스를 쿼리합니다.

create_database

지정된 ID(이름)를 사용하여 새 데이터베이스를 만듭니다.

create_database(id: str, populate_query_metrics: bool | None = None, offer_throughput: int | ThroughputProperties | None = None, **kwargs: Any) -> DatabaseProxy

매개 변수

id

필수

만들 데이터베이스의 ID(이름)입니다.

offer_throughput

필수

이 제품에 대해 프로비전된 처리량입니다.

session_token

str

세션 일관성에 사용할 토큰입니다.

initial_headers

dict[str,str]

요청의 일부로 보낼 초기 헤더입니다.

etag

str

ETag 값 또는 와일드카드 문자(*)입니다. 리소스가 변경되었는지 검사 match_condition 매개 변수에 지정된 조건에 따라 작동합니다.

match_condition

MatchConditions

etag에 사용할 일치 조건입니다.

response_hook

Callable

응답 메타데이터를 사용하여 호출된 호출 가능한 입니다.

반환

새 데이터베이스를 나타내는 DatabaseProxy instance.

반환 형식

DatabaseProxy

예외

CosmosResourceExistsError

지정된 ID가 있는 데이터베이스가 이미 있습니다.

예제

Cosmos DB 계정에 데이터베이스를 만듭니다.

   database_name = "testDatabase"
   try:
       database = client.create_database(id=database_name)
   except exceptions.CosmosResourceExistsError:
       database = client.get_database_client(database=database_name)

create_database_if_not_exists

데이터베이스가 아직 없는 경우 만듭니다.

데이터베이스가 이미 있는 경우 기존 설정이 반환됩니다.

.. 참고:: 이 함수는 기존 데이터베이스 설정을 검사 업데이트하거나 전달된 것과 다른 경우 처리량을 제공하지 않습니다.

create_database_if_not_exists(id: str, populate_query_metrics: bool | None = None, offer_throughput: int | ThroughputProperties | None = None, **kwargs: Any) -> DatabaseProxy

매개 변수

id

필수

읽거나 만들 데이터베이스의 ID(이름)입니다.

populate_query_metrics

bool

필수

응답 헤더에서 쿼리 메트릭 반환을 사용하도록 설정합니다.

offer_throughput

int 또는 <xref:azure.cosmos.ThroughputProperties.>

필수

이 제품에 대해 프로비전된 처리량입니다.

session_token

str

세션 일관성에 사용할 토큰입니다.

initial_headers

dict[str,str]

요청의 일부로 보낼 초기 헤더입니다.

etag

str

ETag 값 또는 와일드카드 문자(*)입니다. 리소스가 변경되었는지 검사 match_condition 매개 변수에 지정된 조건에 따라 작동합니다.

match_condition

MatchConditions

etag에 사용할 일치 조건입니다.

response_hook

Callable

응답 메타데이터를 사용하여 호출된 호출 가능한 입니다.

반환

데이터베이스를 나타내는 DatabaseProxy instance.

반환 형식

DatabaseProxy

예외

CosmosHttpResponseError

데이터베이스 읽기 또는 만들기에 실패했습니다.

delete_database

지정된 ID(이름)를 사용하여 데이터베이스를 삭제합니다.

delete_database(database: str | DatabaseProxy | Dict[str, Any], populate_query_metrics: bool | None = None, **kwargs: Any) -> None

매개 변수

database

str 또는 dict(str, str) 또는 DatabaseProxy

필수

삭제할 데이터베이스의 속성 또는 DatabaseProxy instance 나타내는 ID(이름)입니다.

session_token

str

세션 일관성에 사용할 토큰입니다.

initial_headers

dict[str,str]

요청의 일부로 보낼 초기 헤더입니다.

etag

str

ETag 값 또는 와일드카드 문자(*)입니다. 리소스가 변경되었는지 검사 match_condition 매개 변수에 지정된 조건에 따라 작동합니다.

match_condition

MatchConditions

etag에 사용할 일치 조건입니다.

response_hook

Callable

응답 메타데이터를 사용하여 호출된 호출 가능한 입니다.

반환 형식

None

예외

CosmosHttpResponseError

데이터베이스를 삭제할 수 없는 경우

from_connection_string

연결 문자열에서 CosmosClient instance 만듭니다.

Azure Portal 검색할 수 있습니다. 선택적 키워드(keyword) 인수의 전체 목록은 CosmosClient 생성자를 참조하세요.

from_connection_string(conn_str: str, credential: Any | None = None, consistency_level: str | None = None, **kwargs: Any) -> CosmosClient

매개 변수

conn_str

str

필수

연결 문자열입니다.

credential

str 또는 dict(str, str)

기본값: None

연결 문자열에 제공된 키 대신 사용할 대체 자격 증명입니다.

consistency_level

Optional[str]

기본값: None

세션에 사용할 일관성 수준입니다. 기본값은 None(계정 수준)입니다.

예외

CosmosResourceExistsError

지정된 ID가 있는 데이터베이스가 이미 있습니다.

get_database_account

데이터베이스 계정 정보를 검색합니다.

get_database_account(**kwargs: Any) -> DatabaseAccount

매개 변수

response_hook

Callable

응답 메타데이터를 사용하여 호출된 호출 가능한 입니다.

반환

Cosmos DB 데이터베이스 계정을 나타내는 DatabaseAccount instance.

반환 형식

DatabaseAccount

예외

CosmosResourceExistsError

지정된 ID가 있는 데이터베이스가 이미 있습니다.

get_database_client

ID(이름) ID를 사용하여 기존 데이터베이스를 검색합니다.

get_database_client(database: str | DatabaseProxy | Dict[str, Any]) -> DatabaseProxy

매개 변수

database

str 또는 dict(str, str) 또는 DatabaseProxy

필수

읽을 데이터베이스의 속성 또는 DatabaseProxy instance 나타내는 ID(이름), 받아쓰기입니다.

반환

검색된 데이터베이스를 나타내는 DatabaseProxy instance.

반환 형식

DatabaseProxy

예외

CosmosResourceExistsError

지정된 ID가 있는 데이터베이스가 이미 있습니다.

list_databases

Cosmos DB SQL 데이터베이스 계정의 데이터베이스를 나열합니다.

list_databases(max_item_count: int | None = None, populate_query_metrics: bool | None = None, **kwargs: Any) -> Iterable[Dict[str, Any]]

매개 변수

max_item_count

int

필수

열거형 작업에서 반환할 최대 항목 수입니다.

session_token

str

세션 일관성에 사용할 토큰입니다.

initial_headers

dict[str,str]

요청의 일부로 보낼 초기 헤더입니다.

response_hook

Callable

응답 메타데이터를 사용하여 호출된 호출 가능한 입니다.

반환

데이터베이스 속성의 반복 가능(받아쓰기)입니다.

반환 형식

Iterable[dict[str, str]]

예외

CosmosResourceExistsError

지정된 ID가 있는 데이터베이스가 이미 있습니다.

query_databases

Cosmos DB SQL 데이터베이스 계정의 데이터베이스를 쿼리합니다.

query_databases(query: str | None = None, parameters: List[Dict[str, Any]] | None = None, enable_cross_partition_query: bool | None = None, max_item_count: int | None = None, populate_query_metrics: bool | None = None, **kwargs: Any) -> Iterable[Dict[str, Any]]

매개 변수

query

str

필수

실행할 Azure Cosmos DB SQL 쿼리입니다.

parameters

List[Dict[str, Any]]

필수

쿼리에 대한 매개 변수의 선택적 배열입니다. 쿼리가 제공되지 않으면 무시됩니다.

enable_cross_partition_query

bool

필수

인덱싱으로 처리할 수 없는 쿼리에 대한 검사 허용이 요청된 경로에서 옵트아웃되었습니다.

max_item_count

int

필수

열거형 작업에서 반환할 최대 항목 수입니다.

session_token

str

세션 일관성에 사용할 토큰입니다.

initial_headers

dict[str,str]

요청의 일부로 보낼 초기 헤더입니다.

response_hook

Callable

응답 메타데이터를 사용하여 호출할 수 있는 입니다.

반환

데이터베이스 속성의 반복 가능(받아쓰기)입니다.

반환 형식

Iterable[dict[str, str]]

예외

CosmosResourceExistsError

지정된 ID가 있는 데이터베이스가 이미 있습니다.