DatabaseProxy 類別

與特定資料庫互動的介面。

此類別不應直接具現化。 請改用 <xref:CosmosClient.get_database_client> 方法。

資料庫包含一或多個容器，每個容器都可以包含專案、預存程式、觸發程式和使用者定義函式。

資料庫也可以有相關聯的使用者，每個使用者都會設定一組許可權來存取特定容器、預存程式、觸發程式、使用者定義函式或專案。

Azure Cosmos DB SQL API 資料庫具有下列系統產生的屬性。 這些屬性是唯讀的：

• _rid：資源識別碼。

• _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

必要

資料庫的識別碼 (名稱) 。

properties

預設值: None

變數

id

資料庫的識別碼 (名稱) 。

方法

create_container	建立具有指定識別碼的新容器 (名稱) 。 如果具有指定識別碼的容器已經存在，則會引發 CosmosResourceExistsError。
create_container_if_not_exists	如果容器不存在，請建立容器。 如果容器已經存在，則會傳回現有的設定。 注意：如果現有容器設定與傳遞至 方法的內容不同，則不會檢查或更新現有的容器設定或提供輸送量。
create_user	在容器中建立新的使用者。 若要更新或取代現有的使用者，請使用 <xref:ContainerProxy.upsert_user> 方法。
delete_container	刪除容器。
delete_user	從容器中刪除指定的使用者。
get_container_client	取得具有指定識別碼之容器的 ContainerProxy (名稱) 。
get_throughput	取得此資料庫的 ThroughputProperties 物件。 如果資料庫沒有任何 ThroughputProperties 存在，就會引發例外狀況。 ：keyword Callable response_hook：使用回應中繼資料叫用的可呼叫專案。 ：returns：資料庫的 ThroughputProperties。 ：raises ~azure.cosmos.exceptions.CosmosHttpResponseError：容器沒有輸送量屬性或 無法擷取輸送量屬性。
get_user_client	取得具有指定識別碼之使用者的 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

建立具有指定識別碼的新容器 (名稱) 。

如果具有指定識別碼的容器已經存在，則會引發 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

必要

要建立之容器的識別碼 (名稱) 。

partition_key

必要

要用於容器的資料分割索引鍵。

indexing_policy

必要

要套用至容器的索引編制原則。

default_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) 。 [無] 的值會離開分析儲存體，而 -1 的值會開啟沒有 TTL 的分析儲存體。 請注意，分析儲存體只能在Synapse Link啟用的帳戶上啟用。

傳回

代表新容器的 ContainerProxy 實例。

傳回類型

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

必要

要讀取或建立之容器的識別碼 (名稱) 。

partition_key

必要

要用於容器的資料分割索引鍵。

indexing_policy

必要

要套用至容器的索引編制原則。

default_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) 。 [無] 的值會離開分析儲存體，而 -1 的值會開啟沒有 TTL 的分析儲存體。 請注意，分析儲存體只能在Synapse Link啟用的帳戶上啟用。

傳回

代表容器的 ContainerProxy 實例。

傳回類型

ContainerProxy

例外狀況

CosmosHttpResponseError

容器讀取或建立失敗。

create_user

在容器中建立新的使用者。

若要更新或取代現有的使用者，請使用 <xref:ContainerProxy.upsert_user> 方法。

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

參數

body

必要

具有 識別碼 索引鍵和值的類似聽寫物件，代表要建立的使用者。 使用者識別碼在資料庫內必須是唯一的，且不超過 255 個字元。

response_hook

Callable

使用回應中繼資料叫用的可呼叫專案。

傳回

代表新使用者的 UserProxy 實例。

傳回類型

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

必要

要刪除之容器的識別碼 (名稱) 。 您可以傳入容器的識別碼，以刪除、 <xref:azure.cosmos.database.ContainerProxy> 實例或表示容器屬性的聽寫。

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

必要

識別碼 (名稱) ，代表要刪除之使用者的屬性或 <xref:azure.cosmos.database.UserProxy> 實例。

response_hook

Callable

使用回應中繼資料叫用的可呼叫專案。

傳回類型

None

例外狀況

CosmosHttpResponseError

使用者未成功刪除。

CosmosResourceNotFoundError

使用者不存在於容器中。

get_container_client

取得具有指定識別碼之容器的 ContainerProxy (名稱) 。

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

參數

container

必要

容器、 <xref:azure.cosmos.database.ContainerProxy> 實例或聽寫的識別碼 (名稱) ，代表要擷取之容器的屬性。

傳回

代表所擷取資料庫的 ContainerProxy 實例。

傳回類型

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

取得具有指定識別碼之使用者的 UserProxy 。

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

參數

user

必要

識別碼 (名稱) ，表示要擷取之使用者的屬性或 <xref:azure.cosmos.database.UserProxy> 實例。

傳回

代表所擷取使用者的 UserProxy 實例。

傳回類型

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

必要

識別碼 (名稱) ，代表要取代之容器的屬性或 <xref:azure.cosmos.database.ContainerProxy> 實例的聽寫。

partition_key

必要

要用於容器的資料分割索引鍵。

indexing_policy

必要

要套用至容器的索引編制原則。

default_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) 。 [無] 的值會離開分析儲存體，而 -1 的值會開啟沒有 TTL 的分析儲存體。 請注意，分析儲存體只能在Synapse Link啟用的帳戶上啟用。

傳回

ContainerProxy實例，代表取代完成後的容器。

傳回類型

ContainerProxy

例外狀況

CosmosHttpResponseError

如果無法取代容器，則引發 。 這包括如果具有指定識別碼的容器不存在。

範例

重設容器上的 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，以新的輸送量更新。

傳回類型

ThroughputProperties

例外狀況

CosmosHttpResponseError

如果資料庫沒有輸送量屬性，或無法更新輸送量屬性，則為 。

replace_user

如果指定的使用者存在於容器中，則會取代指定的使用者。

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

參數

user

必要

識別碼 (名稱) ，代表要取代之使用者的屬性或 <xref:azure.cosmos.database.UserProxy> 實例。

body

必要

類似聽寫的物件，代表要取代的使用者。

response_hook

Callable

使用回應中繼資料叫用的可呼叫專案。

傳回

UserProxy實例，代表取代之後的使用者。

傳回類型

UserProxy

例外狀況

CosmosHttpResponseError

如果取代失敗，或具有指定識別碼的使用者不存在。

upsert_user

插入或更新指定的使用者。

如果使用者已存在於容器中，則會加以取代。 如果使用者尚未存在，則會插入。

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

參數

body

必要

類似聽寫的物件，代表要更新或插入的使用者。

response_hook

Callable

使用回應中繼資料叫用的可呼叫專案。

傳回

代表已插入使用者的 UserProxy 實例。

傳回類型

UserProxy

例外狀況

CosmosHttpResponseError

如果指定的使用者無法向上插入。