共用方式為


DatabaseProxy 類別

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

不應該直接具現化這個類別。 請改用 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 可呼叫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 可呼叫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 實例。

傳回類型

例外狀況

容器建立失敗。

範例

建立具有預設設定的容器:


   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 實例。

傳回類型

例外狀況

容器讀取或建立失敗。

create_user

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

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

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

參數

body
必要

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

response_hook
Callable

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

傳回

代表新使用者的 UserProxy 實例。

傳回類型

例外狀況

如果無法建立指定的使用者。

範例

建立資料庫使用者:


   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
必要

要刪除之容器) 識別碼 (名稱。 您可以傳入容器的識別碼,以刪除、 ContainerProxy 實例或代表容器屬性的聽寫。

session_token
str

用於會話一致性的權杖。

initial_headers
dict[str,str]

要作為要求一部分傳送的初始標頭。

etag
str

ETag 值,或萬用字元 (*)。 用來檢查資源是否已變更,並根據 match_condition 參數所指定的條件採取行動。

match_condition
MatchConditions

要用於 etag 的比對條件。

response_hook
Callable

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

傳回類型

例外狀況

如果無法刪除容器。

delete_user

從容器中刪除指定的使用者。

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

參數

user
必要

識別碼 (名稱) ,代表要刪除之使用者的屬性或 UserProxy 實例。

response_hook
Callable

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

傳回類型

例外狀況

使用者未成功刪除。

使用者不存在於容器中。

get_container_client

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

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

參數

container
必要

容器、 ContainerProxy 實例或聽寫的識別碼 (名稱) ,代表要擷取之容器的屬性。

傳回

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

傳回類型

例外狀況

容器建立失敗。

範例

取得現有的容器,如果遇到下列狀況,則會處理失敗:


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

get_throughput

取得此資料庫的 ThroughputProperties 物件。 如果資料庫尚未存在 ThroughputProperties,則會引發例外狀況。 :keyword 可呼叫response_hook:使用回應中繼資料叫用的可呼叫。 :returns: 資料庫的 ThroughputProperties。 :raises ~azure.cosmos.exceptions.CosmosHttpResponseError:容器沒有輸送量屬性或

無法擷取輸送量屬性。

get_throughput(**kwargs: Any) -> ThroughputProperties

傳回類型

例外狀況

容器建立失敗。

get_user_client

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

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

參數

user
必要

識別碼 (名稱) ,代表要擷取之使用者的屬性或 UserProxy 實例的聽寫。

傳回

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

傳回類型

例外狀況

容器建立失敗。

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

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

傳回

可反覆運算容器屬性 (聽寫) 。

傳回類型

例外狀況

容器建立失敗。

範例

列出資料庫中的所有容器:


   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

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

傳回

可反覆運算 (聽寫) 的使用者屬性。

傳回類型

例外狀況

容器建立失敗。

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

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

傳回

可反覆運算容器屬性 (聽寫) 。

傳回類型

例外狀況

容器建立失敗。

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

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

傳回

可反覆運算 (聽寫) 的使用者屬性。

傳回類型

例外狀況

容器建立失敗。

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]

例外狀況

如果無法擷取指定的資料庫。

read_offer

取得此資料庫的 ThroughputProperties 物件。 如果資料庫尚未存在 ThroughputProperties,則會引發例外狀況。 :keyword 可呼叫response_hook:使用回應中繼資料叫用的可呼叫。 :returns: 資料庫的 ThroughputProperties。 :raises ~azure.cosmos.exceptions.CosmosHttpResponseError:容器沒有輸送量屬性或

無法擷取輸送量屬性。

read_offer(**kwargs: Any) -> ThroughputProperties

傳回類型

例外狀況

容器建立失敗。

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 實例。

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實例,代表取代完成後的容器。

傳回類型

例外狀況

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

範例

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

傳回類型

例外狀況

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

replace_user

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

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

參數

user
必要

識別碼 (名稱) ,代表要取代之使用者的屬性或 UserProxy 實例的聽寫。

body
必要

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

response_hook
Callable

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

傳回

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

傳回類型

例外狀況

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

upsert_user

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

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

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

參數

body
必要

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

response_hook
Callable

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

傳回

代表 upserted 使用者的 UserProxy 實例。

傳回類型

例外狀況

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