CosmosClient 클래스

참조

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

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

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

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

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

상속: builtins.object

CosmosClient

생성자

CosmosClient(url: str, credential: str | Dict[str, str] | TokenCredential, *, consistency_level: str | None = None, **kwargs: Any)

매개 변수

url: str

필수

Cosmos DB 계정의 URL입니다.

credential: Union[str, Dict[str, str], AsyncTokenCredential]

필수

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

consistency_level: str

세션에 사용할 일관성 수준입니다. 기본값은 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 만듭니다.


       async with CosmosClient(url, key) as client:

메서드

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

close

CosmosClient의 이 instance 닫습니다.

async close() -> None

create_database

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

async create_database(id: str, **kwargs: Any) -> DatabaseProxy

매개 변수

id: str

필수

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

offer_throughput: Union[int, ThroughputProperties]

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

session_token: str

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

initial_headers: dict[str, str]

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

etag: str

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

match_condition: MatchConditions

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

response_hook: Callable[[Dict[str, str], Dict[str, Any]], None]

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

반환

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

반환 형식

DatabaseProxy

예외

CosmosResourceExistsError

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

예제

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


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

create_database_if_not_exists

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

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

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

async create_database_if_not_exists(id: str, **kwargs: Any) -> DatabaseProxy

매개 변수

id: str

필수

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

offer_throughput: Union[int, ThroughputProperties]

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

session_token: str

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

initial_headers: dict[str, str]

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

etag: str

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

match_condition: MatchConditions

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

response_hook: Callable[[Dict[str, str], Dict[str, Any]], None]

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

반환

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

반환 형식

DatabaseProxy

예외

CosmosHttpResponseError

데이터베이스를 읽거나 만들지 못했습니다.

delete_database

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

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

매개 변수

database: Union[str, DatabaseProxy, Dict[str, Any]]

필수

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

session_token: str

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

initial_headers: dict[str, str]

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

etag: str

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

match_condition: MatchConditions

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

response_hook: Callable[[Dict[str, str]], None]

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

반환 형식

None

예외

CosmosHttpResponseError

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

from_connection_string

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

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

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

매개 변수

conn_str: str

필수

연결 문자열입니다.

credential: Union[str, Dict[str, str]]

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

consistency_level: str

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

반환

CosmosClient instance

반환 형식

CosmosClient

get_database_client

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

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

매개 변수

database: Union[str, DatabaseProxy, Dict[str, Any]]

필수

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

반환

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

반환 형식

DatabaseProxy

list_databases

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

list_databases(**kwargs: Any) -> AsyncItemPaged[Dict[str, Any]]

매개 변수

max_item_count: int

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

session_token: str

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

initial_headers: dict[str, str]

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

response_hook: Callable[[Dict[str, str]], None]

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

반환

데이터베이스 속성(dicts)의 AsyncItemPaged입니다.

반환 형식

<xref:AsyncItemPaged>[Dict[str, str]]

query_databases

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

query_databases(**kwargs: Any) -> AsyncItemPaged[Dict[str, Any]]

매개 변수

query: Union[str, Dict[str, Any]]

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

parameters: List[Dict[str, Any]]

쿼리에 대한 매개 변수의 선택적 배열입니다. 각 매개 변수는 'name' 및 'value' 키가 있는 dict()입니다.

max_item_count: int

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

session_token: str

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

initial_headers: dict[str, str]

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

response_hook: Callable[[Dict[str, str]], None]

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

반환

데이터베이스 속성(dicts)의 AsyncItemPaged입니다.

반환 형식

<xref:AsyncItemPaged>[Dict[str, str]]

다음을 통해 공유

CosmosClient 클래스

생성자

매개 변수

예제

메서드

close

create_database

매개 변수

반환

반환 형식

예외

예제

create_database_if_not_exists

매개 변수

반환

반환 형식

예외

delete_database

매개 변수

반환 형식

예외

from_connection_string

매개 변수

반환

반환 형식

get_database_client

매개 변수

반환

반환 형식

list_databases

매개 변수

반환

반환 형식

query_databases

매개 변수

반환

반환 형식

추가 리소스