다음을 통해 공유

DatabaseProxy 클래스

  • 참조

특정 데이터베이스와 상호 작용하는 인터페이스입니다.

이 클래스는 직접 인스턴스화해서는 안 됩니다. 대신 메서드를 get_database_client 사용합니다.

데이터베이스에는 하나 이상의 컨테이너가 포함되며, 각 컨테이너에는 항목, 저장 프로시저, 트리거 및 사용자 정의 함수가 포함될 수 있습니다.

또한 데이터베이스에는 연결된 사용자가 있을 수 있으며, 각 사용자는 특정 컨테이너, 저장 프로시저, 트리거, 사용자 정의 함수 또는 항목에 액세스하기 위한 권한 집합으로 구성됩니다.

Azure Cosmos DB SQL API 데이터베이스에는 다음과 같은 시스템 생성 속성이 있습니다. 이러한 속성은 읽기 전용입니다.

  • _rid: 리소스 ID입니다.

  • _ts: 리소스가 마지막으로 업데이트된 시기입니다. 값은 타임스탬프입니다.

  • _self: 리소스에 대한 고유한 주소 지정 가능한 URI입니다.

  • _etag: 낙관적 동시성 제어에 필요한 리소스 etag입니다.

  • _colls: 컬렉션 리소스의 주소 지정 가능한 경로입니다.

  • _users: 사용자 리소스의 주소 지정 가능한 경로입니다.

상속
builtins.object
DatabaseProxy

생성자

DatabaseProxy(client_connection: CosmosClientConnection, id: str, properties: Dict[str, Any] = None)

매개 변수

client_connection
<xref:ClientSession>
필수

이 데이터베이스가 검색된 클라이언트입니다.

id
str
필수

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

properties
기본값: None

변수

id

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

메서드

create_container

지정된 ID(이름)를 사용하여 새 컨테이너를 만듭니다.

지정된 ID가 있는 컨테이너가 이미 있는 경우 CosmosResourceExistsError가 발생합니다.
create_container_if_not_exists

컨테이너가 아직 없는 경우 컨테이너를 만듭니다.

컨테이너가 이미 있는 경우 기존 설정이 반환됩니다. 참고: 메서드에 전달된 것과 다른 경우 기존 컨테이너 설정을 검사 업데이트하거나 처리량을 제공하지 않습니다.
create_user

컨테이너에 새 사용자를 만듭니다.

기존 사용자를 업데이트하거나 바꾸려면 메서드를 <xref:ContainerProxy.upsert_user> 사용합니다.
delete_container

컨테이너를 삭제합니다.
delete_user

컨테이너에서 지정된 사용자를 삭제합니다.
get_container_client

지정된 ID(이름)가 있는 컨테이너에 대한 ContainerProxy 를 가져옵니다.
get_throughput

이 데이터베이스에 대한 ThroughputProperties 개체를 가져옵니다. 데이터베이스에 대한 ThroughputProperties가 아직 없으면 예외가 발생합니다. :키워드(keyword) Callable response_hook: 응답 메타데이터를 사용하여 호출된 호출 가능한 입니다. :returns: 데이터베이스에 대한 ThroughputProperties입니다. :raises ~azure.cosmos.exceptions.CosmosHttpResponseError: 컨테이너에 대한 처리량 속성이 없거나

처리량 속성을 검색할 수 없습니다.
get_user_client

지정된 ID를 가진 사용자에 대한 UserProxy 를 가져옵니다.
list_containers

데이터베이스의 컨테이너를 나열합니다.
list_users

컨테이너의 모든 사용자를 나열합니다.
query_containers

현재 데이터베이스의 컨테이너 속성을 나열합니다.
query_users

지정된 쿼리와 일치하는 모든 사용자를 반환 합니다.
read

데이터베이스 속성을 읽습니다.
read_offer

이 데이터베이스에 대한 ThroughputProperties 개체를 가져옵니다. 데이터베이스에 대한 ThroughputProperties가 아직 없으면 예외가 발생합니다. :키워드(keyword) Callable response_hook: 응답 메타데이터를 사용하여 호출된 호출 가능한 입니다. :returns: 데이터베이스에 대한 ThroughputProperties입니다. :raises ~azure.cosmos.exceptions.CosmosHttpResponseError: 컨테이너에 대한 처리량 속성이 없거나

처리량 속성을 검색할 수 없습니다.
replace_container

컨테이너의 속성을 다시 설정합니다.

속성 변경 내용은 즉시 유지됩니다. 지정되지 않은 모든 속성은 기본값으로 다시 설정됩니다.
replace_throughput

데이터베이스 수준 처리량을 대체합니다.
replace_user

컨테이너에 있는 경우 지정된 사용자를 바꿉니다.
upsert_user

지정된 사용자를 삽입하거나 업데이트합니다.

사용자가 컨테이너에 이미 있는 경우 대체됩니다. 사용자가 아직 없는 경우 삽입됩니다.

create_container

지정된 ID(이름)를 사용하여 새 컨테이너를 만듭니다.

지정된 ID가 있는 컨테이너가 이미 있는 경우 CosmosResourceExistsError가 발생합니다.

create_container(id: str, partition_key: Any, indexing_policy: Dict[str, Any] | None = None, default_ttl: int | None = None, populate_query_metrics: bool | None = None, offer_throughput: int | ThroughputProperties | None = None, unique_key_policy: Dict[str, Any] | None = None, conflict_resolution_policy: Dict[str, Any] | None = None, **kwargs: Any) -> ContainerProxy

매개 변수

id
필수

만들 컨테이너의 ID(이름)입니다.

partition_key
필수

컨테이너에 사용할 파티션 키입니다.

indexing_policy
필수

컨테이너에 적용할 인덱싱 정책입니다.

default_ttl
필수

컨테이너의 항목에 대한 TTL(기본 TTL) 시간입니다. 지정하지 않으면 항목이 만료되지 않습니다.

offer_throughput
int 또는 <xref:azure.cosmos.ThroughputProperties.>
필수

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

unique_key_policy
필수

컨테이너에 적용할 고유 키 정책입니다.

conflict_resolution_policy
필수

컨테이너에 적용할 충돌 해결 정책입니다.

session_token
str

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

initial_headers
dict[str,str]

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

etag
str

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

match_condition
MatchConditions

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

response_hook
Callable

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

analytical_storage_ttl
int

컨테이너의 항목에 대한 TTL(Analytical Store Time to Live)입니다. None 값은 분석 스토리지를 해제하고 -1 값은 TTL 없이 분석 스토리지를 켭니다. 분석 스토리지는 Synapse Link 사용하도록 설정된 계정에서만 사용하도록 설정할 수 있습니다.

반환

새 컨테이너를 나타내는 ContainerProxy instance.

반환 형식

ContainerProxy

예외

CosmosHttpResponseError

컨테이너를 만들지 못했습니다.

예제

기본 설정을 사용하여 컨테이너를 만듭니다.


   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)

특정 설정을 사용하여 컨테이너를 만듭니다. 이 경우 사용자 지정 파티션 키는 다음과 같습니다.


   customer_container_name = "customers"
   try:
       customer_container = database.create_container(
           id=customer_container_name,
           partition_key=PartitionKey(path="/city"),
           default_ttl=200,
       )
   except exceptions.CosmosResourceExistsError:
       customer_container = database.get_container_client(customer_container_name)

create_container_if_not_exists

컨테이너가 아직 없는 경우 컨테이너를 만듭니다.

컨테이너가 이미 있는 경우 기존 설정이 반환됩니다. 참고: 메서드에 전달된 것과 다른 경우 기존 컨테이너 설정을 검사 업데이트하거나 처리량을 제공하지 않습니다.

create_container_if_not_exists(id: str, partition_key: Any, indexing_policy: Dict[str, Any] | None = None, default_ttl: int | None = None, populate_query_metrics: bool | None = None, offer_throughput: int | ThroughputProperties | None = None, unique_key_policy: Dict[str, Any] | None = None, conflict_resolution_policy: Dict[str, Any] | None = None, **kwargs: Any) -> ContainerProxy

매개 변수

id
필수

읽거나 만들 컨테이너의 ID(이름)입니다.

partition_key
필수

컨테이너에 사용할 파티션 키입니다.

indexing_policy
필수

컨테이너에 적용할 인덱싱 정책입니다.

default_ttl
필수

컨테이너의 항목에 대한 TTL(기본 TTL) 시간입니다. 지정하지 않으면 항목이 만료되지 않습니다.

populate_query_metrics
필수

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

offer_throughput
필수

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

unique_key_policy
필수

컨테이너에 적용할 고유 키 정책입니다.

conflict_resolution_policy
필수

컨테이너에 적용할 충돌 해결 정책입니다.

session_token
str

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

initial_headers
dict[str,str]

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

etag
str

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

match_condition
MatchConditions

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

response_hook
Callable

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

analytical_storage_ttl
int

컨테이너의 항목에 대한 TTL(Analytical Store Time to Live)입니다. None 값은 분석 스토리지를 해제하고 -1 값은 TTL 없이 분석 스토리지를 켭니다. 분석 스토리지는 Synapse Link 사용하도록 설정된 계정에서만 사용하도록 설정할 수 있습니다.

반환

컨테이너를 나타내는 ContainerProxy instance.

반환 형식

ContainerProxy

예외

CosmosHttpResponseError

컨테이너를 읽거나 만들지 못했습니다.

create_user

컨테이너에 새 사용자를 만듭니다.

기존 사용자를 업데이트하거나 바꾸려면 메서드를 <xref:ContainerProxy.upsert_user> 사용합니다.

create_user(body: Dict[str, Any], **kwargs: Any) -> UserProxy

매개 변수

body
필수

만들 사용자를 나타내는 ID 키와 값이 있는 dict와 유사한 개체입니다. 사용자 ID는 데이터베이스 내에서 고유해야 하며 255자 이하로 구성되어야 합니다.

response_hook
Callable

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

반환

새 사용자를 나타내는 UserProxy instance.

반환 형식

UserProxy

예외

CosmosHttpResponseError

지정된 사용자를 만들 수 없는 경우.

예제

데이터베이스 사용자 만들기:


   try:
       database.create_user(dict(id="Walter Harp"))
   except exceptions.CosmosResourceExistsError:
       print("A user with that ID already exists.")
   except exceptions.CosmosHttpResponseError as failure:
       print("Failed to create user. Status code:{}".format(failure.status_code))

delete_container

컨테이너를 삭제합니다.

delete_container(container: str | ContainerProxy | Dict[str, Any], populate_query_metrics: bool | None = None, **kwargs: Any) -> None

매개 변수

container
필수

삭제할 컨테이너의 ID(이름)입니다. 삭제할 컨테이너의 ID, ContainerProxy instance 또는 컨테이너의 속성을 나타내는 받아쓰기를 전달할 수 있습니다.

session_token
str

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

initial_headers
dict[str,str]

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

etag
str

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

match_condition
MatchConditions

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

response_hook
Callable

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

반환 형식

None

예외

CosmosHttpResponseError

컨테이너를 삭제할 수 없는 경우

delete_user

컨테이너에서 지정된 사용자를 삭제합니다.

delete_user(user: str | UserProxy | Dict[str, Any], **kwargs: Any) -> None

매개 변수

user
필수

삭제할 사용자의 속성 또는 UserProxy instance 나타내는 ID(이름), 받아쓰기입니다.

response_hook
Callable

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

반환 형식

None

예외

CosmosHttpResponseError

사용자가 성공적으로 삭제되지 않았습니다.

CosmosResourceNotFoundError

사용자가 컨테이너에 없습니다.

get_container_client

지정된 ID(이름)가 있는 컨테이너에 대한 ContainerProxy 를 가져옵니다.

get_container_client(container: str | ContainerProxy | Dict[str, Any]) -> ContainerProxy

매개 변수

container
필수

검색할 컨테이너의 속성을 나타내는 컨테이너, ContainerProxy instance 또는 받아쓰기의 ID(이름)입니다.

반환

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

반환 형식

ContainerProxy

예외

CosmosHttpResponseError

컨테이너를 만들지 못했습니다.

예제

기존 컨테이너를 가져와 오류가 발생한 경우 처리합니다.


   database = client.get_database_client(database_name)
   container = database.get_container_client(container_name)

get_throughput

이 데이터베이스에 대한 ThroughputProperties 개체를 가져옵니다. 데이터베이스에 대한 ThroughputProperties가 아직 없으면 예외가 발생합니다. :키워드(keyword) Callable response_hook: 응답 메타데이터를 사용하여 호출된 호출 가능한 입니다. :returns: 데이터베이스에 대한 ThroughputProperties입니다. :raises ~azure.cosmos.exceptions.CosmosHttpResponseError: 컨테이너에 대한 처리량 속성이 없거나

처리량 속성을 검색할 수 없습니다.

get_throughput(**kwargs: Any) -> ThroughputProperties

반환 형식

ThroughputProperties

예외

CosmosHttpResponseError

컨테이너를 만들지 못했습니다.

get_user_client

지정된 ID를 가진 사용자에 대한 UserProxy 를 가져옵니다.

get_user_client(user: str | UserProxy | Dict[str, Any]) -> UserProxy

매개 변수

user
필수

검색할 사용자의 속성 또는 UserProxy instance 나타내는 ID(이름) 받아쓰기입니다.

반환

검색된 사용자를 나타내는 UserProxy instance.

반환 형식

UserProxy

예외

CosmosHttpResponseError

컨테이너를 만들지 못했습니다.

list_containers

데이터베이스의 컨테이너를 나열합니다.

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

매개 변수

max_item_count
필수

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

session_token
str

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

initial_headers
dict[str,str]

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

response_hook
Callable

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

반환

컨테이너 속성의 반복 가능(받아쓰기)입니다.

반환 형식

Iterable[dict[str, Any]]

예외

CosmosHttpResponseError

컨테이너를 만들지 못했습니다.

예제

데이터베이스의 모든 컨테이너를 나열합니다.


   database = client.get_database_client(database_name)
   for container in database.list_containers():
       print("Container ID: {}".format(container['id']))

list_users

컨테이너의 모든 사용자를 나열합니다.

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

매개 변수

max_item_count
필수

열거형 작업에서 반환할 최대 사용자 수입니다.

response_hook
Callable

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

반환

사용자 속성의 반복 가능(받아쓰기)입니다.

반환 형식

Iterable[dict[str, Any]]

예외

CosmosHttpResponseError

컨테이너를 만들지 못했습니다.

query_containers

현재 데이터베이스의 컨테이너 속성을 나열합니다.

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

매개 변수

query
필수

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

parameters
필수

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

max_item_count
필수

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

session_token
str

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

initial_headers
dict[str,str]

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

response_hook
Callable

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

반환

컨테이너 속성의 반복 가능(받아쓰기)입니다.

반환 형식

Iterable[dict[str, Any]]

예외

CosmosHttpResponseError

컨테이너를 만들지 못했습니다.

query_users

지정된 쿼리와 일치하는 모든 사용자를 반환 합니다.

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

매개 변수

query
필수

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

parameters
필수

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

max_item_count
필수

열거형 작업에서 반환할 최대 사용자 수입니다.

response_hook
Callable

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

반환

사용자 속성의 반복 가능(받아쓰기)입니다.

반환 형식

Iterable[str, Any]

예외

CosmosHttpResponseError

컨테이너를 만들지 못했습니다.

read

데이터베이스 속성을 읽습니다.

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

매개 변수

session_token
str

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

initial_headers
dict[str,str]

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

response_hook
Callable

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

반환 형식

Dict[<xref:Str>, Any]

예외

CosmosHttpResponseError

지정된 데이터베이스를 검색할 수 없는 경우

read_offer

이 데이터베이스에 대한 ThroughputProperties 개체를 가져옵니다. 데이터베이스에 대한 ThroughputProperties가 아직 없으면 예외가 발생합니다. :키워드(keyword) Callable response_hook: 응답 메타데이터를 사용하여 호출된 호출 가능한 입니다. :returns: 데이터베이스에 대한 ThroughputProperties입니다. :raises ~azure.cosmos.exceptions.CosmosHttpResponseError: 컨테이너에 대한 처리량 속성이 없거나

처리량 속성을 검색할 수 없습니다.

read_offer(**kwargs: Any) -> ThroughputProperties

반환 형식

ThroughputProperties

예외

CosmosHttpResponseError

컨테이너를 만들지 못했습니다.

replace_container

컨테이너의 속성을 다시 설정합니다.

속성 변경 내용은 즉시 유지됩니다. 지정되지 않은 모든 속성은 기본값으로 다시 설정됩니다.

replace_container(container: str | ContainerProxy | Dict[str, Any], partition_key: Any, indexing_policy: Dict[str, Any] | None = None, default_ttl: int | None = None, conflict_resolution_policy: Dict[str, Any] | None = None, populate_query_metrics: bool | None = None, **kwargs: Any) -> ContainerProxy

매개 변수

container
필수

바꿀 컨테이너의 속성 또는 ContainerProxy instance 나타내는 ID(이름) 받아쓰기입니다.

partition_key
필수

컨테이너에 사용할 파티션 키입니다.

indexing_policy
필수

컨테이너에 적용할 인덱싱 정책입니다.

default_ttl
필수

컨테이너의 항목에 대한 TTL(기본 TTL) 시간입니다. 지정하지 않으면 항목이 만료되지 않습니다.

conflict_resolution_policy
필수

컨테이너에 적용할 충돌 해결 정책입니다.

populate_query_metrics
필수

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

session_token
str

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

etag
str

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

match_condition
MatchConditions

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

initial_headers
dict[str,str]

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

response_hook
Callable

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

analytical_storage_ttl
int

컨테이너의 항목에 대한 TTL(Analytical Store Time to Live)입니다. None 값은 분석 스토리지를 해제하고 -1 값은 TTL 없이 분석 스토리지를 켭니다. 분석 스토리지는 Synapse Link 사용하도록 설정된 계정에서만 사용하도록 설정할 수 있습니다.

반환

바꾸기가 완료된 후 컨테이너를 나타내는 ContainerProxy instance.

반환 형식

ContainerProxy

예외

CosmosHttpResponseError

컨테이너를 바꿀 수 없는 경우 발생합니다. 여기에는 지정된 ID가 있는 컨테이너가 없는 경우가 포함됩니다.

예제

컨테이너에서 TTL 속성을 재설정하고 업데이트된 속성을 표시합니다.


   # Set the TTL on the container to 3600 seconds (one hour)
   database.replace_container(container, partition_key=PartitionKey(path='/productName'), default_ttl=3600)

   # Display the new TTL setting for the container
   container_props = database.get_container_client(container_name).read()
   print("New container TTL: {}".format(json.dumps(container_props['defaultTtl'])))

replace_throughput

데이터베이스 수준 처리량을 대체합니다.

replace_throughput(throughput: int | ThroughputProperties | None, **kwargs: Any) -> ThroughputProperties

매개 변수

throughput
필수

설정할 처리량(정수)입니다.

response_hook
Callable

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

반환

새 처리량으로 업데이트된 데이터베이스에 대한 처리량속성입니다.

반환 형식

ThroughputProperties

예외

CosmosHttpResponseError

데이터베이스에 대한 처리량 속성이 없거나 처리량 속성을 업데이트할 수 없는 경우

replace_user

컨테이너에 있는 경우 지정된 사용자를 바꿉니다.

replace_user(user: str | UserProxy | Dict[str, Any], body: Dict[str, Any], **kwargs: Any) -> UserProxy

매개 변수

user
필수

바꿀 사용자의 속성 또는 UserProxy instance 나타내는 ID(이름) 받아쓰기입니다.

body
필수

바꿀 사용자를 나타내는 dict와 유사한 개체입니다.

response_hook
Callable

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

반환

바꾸기를 통과한 후 사용자를 나타내는 UserProxy instance.

반환 형식

UserProxy

예외

CosmosHttpResponseError

바꾸기에 실패했거나 지정된 ID를 가진 사용자가 없는 경우.

upsert_user

지정된 사용자를 삽입하거나 업데이트합니다.

사용자가 컨테이너에 이미 있는 경우 대체됩니다. 사용자가 아직 없는 경우 삽입됩니다.

upsert_user(body: Dict[str, Any], **kwargs: Any) -> UserProxy

매개 변수

body
필수

업데이트하거나 삽입할 사용자를 나타내는 dict와 유사한 개체입니다.

response_hook
Callable

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

반환

upserted 사용자를 나타내는 UserProxy instance.

반환 형식

UserProxy

예외

CosmosHttpResponseError

지정된 사용자를 업서트할 수 없는 경우