ContainerProxy 類別

參考

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

不應該直接具現化這個類別。請改用 get_container_client 方法來取得現有的容器，或使用 create_container 方法來建立新的容器。

Azure Cosmos DB SQL API 資料庫中的容器是檔的集合，每個檔都會以專案表示。

繼承: builtins.object

ContainerProxy

建構函式

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

參數

client_connection

database_link

id

properties

預設值: None

變數

id: str

容器的識別碼 (名稱)

session_token: str

容器的會話權杖。

方法

create_item	在容器中建立專案。若要更新或取代現有的專案，請使用 upsert_item 方法。
delete_all_items_by_partition_key	依分割區索引鍵的刪除功能是非同步背景作業，可讓您使用 Cosmos SDK 刪除具有相同邏輯分割區索引鍵值的所有檔。分割區索引鍵作業的刪除限制為每秒容器上最多可用 RU/秒的 10%。這有助於限制此背景工作所使用的資源。
delete_conflict	從容器中刪除指定的衝突。如果容器中還沒有衝突，就會引發例外狀況。
delete_item	從容器中刪除指定的專案。如果專案不存在於容器中，則會引發例外狀況。
get_conflict	取得衝突所識別的衝突。
get_throughput	取得此容器的 ThroughputProperties 物件。如果容器中沒有任何 ThroughputProperties 存在，就會引發例外狀況。：keyword Callable response_hook：使用回應中繼資料叫用的可呼叫專案。：returns：容器的輸送量。：raises ~azure.cosmos.exceptions.CosmosHttpResponseError：容器沒有輸送量屬性或無法擷取輸送量屬性。
list_conflicts	列出容器中的所有衝突。
patch_item	臨時方法如果指定的專案存在於容器中，則會使用提供的作業來修補。如果專案不存在於容器中，則會引發例外狀況。
query_conflicts	傳回符合指定查詢的所有衝突。
query_items	傳回符合指定查詢的所有結果。您可以在 FROM 子句中使用容器名稱的任何值，但通常會使用容器名稱。在下列範例中，容器名稱為「products」，且別名為「p」，以方便在 WHERE 子句中參考。查詢回應中的回應接續權杖。有效值為正整數。值為 0 與未傳遞值相同， (預設沒有限制) 。：keyword int max_integrated_cache_staleness_in_ms：中整合式快取的最大快取過時毫秒。針對設定為使用整合式快取的帳戶，使用會話或最終一致性，回應保證不會超過此值。
query_items_change_feed	依修改專案的順序，取得已變更的專案排序清單。
read	讀取容器屬性。
read_all_items	列出容器中的所有專案。
read_item	取得專案所識別的專案。
read_offer	取得此容器的 ThroughputProperties 物件。如果容器中還沒有 ThroughputProperties，則會引發例外狀況。：keyword 可呼叫response_hook：使用回應中繼資料叫用的可呼叫。：returns：容器的輸送量。：raises ~azure.cosmos.exceptions.CosmosHttpResponseError：容器沒有輸送量屬性或無法擷取輸送量屬性。
replace_item	如果指定的專案存在於容器中，則會取代它。如果容器中還沒有任何專案存在，則會引發例外狀況。
replace_throughput	取代容器的輸送量。如果容器中還沒有 ThroughputProperties，則會引發例外狀況。
upsert_item	插入或更新指定的專案。如果專案已存在於容器中，則會加以取代。如果專案不存在，則會插入該專案。

create_item

在容器中建立專案。

若要更新或取代現有的專案，請使用 upsert_item 方法。

create_item(body: Dict[str, Any], populate_query_metrics: bool | None = None, pre_trigger_include: str | None = None, post_trigger_include: str | None = None, indexing_directive: Any | None = None, **kwargs: Any) -> Dict[str, Any]

參數

body

必要

類似聽寫的物件，表示要建立的專案。

pre_trigger_include

必要

要作為作業前置觸發程式的觸發程式識別碼。

post_trigger_include

必要

要作為後續作業觸發程式的觸發程式識別碼。

indexing_directive

必要

指出是否應該從索引編制中省略檔。

enable_automatic_id_generation: bool

如果沒有識別碼，請啟用自動產生識別碼。

session_token: str

用於會話一致性的權杖。

initial_headers: dict[str,str]

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

etag: str

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

match_condition: MatchConditions

要用於 etag 的比對條件。

response_hook: Callable

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

傳回

表示新專案的聽寫。

傳回類型

dict[str, Any]

例外狀況

CosmosHttpResponseError

具有指定識別碼的專案已經存在。

delete_all_items_by_partition_key

依分割區索引鍵的刪除功能是非同步背景作業，可讓您使用 Cosmos SDK 刪除具有相同邏輯分割區索引鍵值的所有檔。分割區索引鍵作業的刪除限制為每秒容器上最多可用 RU/秒的 10%。這有助於限制此背景工作所使用的資源。

delete_all_items_by_partition_key(partition_key: str | int | float | bool, **kwargs: Any) -> None

參數

partition_key: Any

必要

要刪除之專案的分割區索引鍵。

pre_trigger_include: str

要作為作業前置觸發程式的觸發程式識別碼。

post_trigger_include: str

要作為後續作業觸發程式的觸發程式識別碼。

session_token: str

用於會話一致性的權杖。

etag: str

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

match_condition: MatchConditions

要用於 etag 的比對條件。

response_hook: Callable

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

傳回類型

None

例外狀況

CosmosHttpResponseError

具有指定識別碼的專案已經存在。

delete_conflict

從容器中刪除指定的衝突。

如果容器中還沒有衝突，就會引發例外狀況。

delete_conflict(conflict: str | Dict[str, Any], partition_key: Any, **kwargs: Any) -> None

參數

conflict

必要

識別碼 (名稱) 或聽寫，代表要刪除的衝突。

partition_key

必要

要刪除之衝突的資料分割索引鍵。

response_hook: Callable

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

傳回類型

None

例外狀況

CosmosHttpResponseError

衝突未成功刪除。

CosmosResourceNotFoundError

衝突不存在於容器中。

delete_item

從容器中刪除指定的專案。

如果專案不存在於容器中，則會引發例外狀況。

delete_item(item: Dict[str, Any] | str, partition_key: Any, populate_query_metrics: bool | None = None, pre_trigger_include: str | None = None, post_trigger_include: str | None = None, **kwargs: Any) -> None

參數

item

必要

識別碼 (名稱) 或聽寫，代表要刪除的專案。

partition_key

必要

指定專案的分割區索引鍵值。

pre_trigger_include

必要

要作為作業前置觸發程式的觸發程式識別碼。

post_trigger_include

必要

要作為後續作業觸發程式的觸發程式識別碼。

session_token: str

用於會話一致性的權杖。

initial_headers: dict[str,str]

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

etag: str

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

match_condition: MatchConditions

要用於 etag 的比對條件。

response_hook: Callable

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

傳回類型

None

例外狀況

CosmosHttpResponseError

專案未成功刪除。

CosmosResourceNotFoundError

專案不存在於容器中。

get_conflict

取得衝突所識別的衝突。

get_conflict(conflict: str | Dict[str, Any], partition_key: Any, **kwargs: Any) -> Dict[str, Any]

參數

conflict

必要

識別碼 (名稱) 或聽寫，代表要擷取的衝突。

partition_key

必要

要擷取之衝突的資料分割索引鍵。

response_hook: Callable

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

傳回

表示所擷取衝突的聽寫。

傳回類型

dict[str, Any]

例外狀況

CosmosHttpResponseError

無法擷取指定的衝突。

get_throughput

取得此容器的 ThroughputProperties 物件。

如果容器中沒有任何 ThroughputProperties 存在，就會引發例外狀況。：keyword Callable response_hook：使用回應中繼資料叫用的可呼叫專案。：returns：容器的輸送量。：raises ~azure.cosmos.exceptions.CosmosHttpResponseError：容器沒有輸送量屬性或

無法擷取輸送量屬性。

get_throughput(**kwargs: Any) -> ThroughputProperties

傳回類型

ThroughputProperties

例外狀況

CosmosHttpResponseError

具有指定識別碼的專案已經存在。

list_conflicts

列出容器中的所有衝突。

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

參數

max_item_count

必要

列舉作業中要傳回的專案數目上限。

response_hook: Callable

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

傳回

可反覆運算 (聽寫) 衝突。

傳回類型

Iterable[dict[str, Any]]

例外狀況

CosmosHttpResponseError

具有指定識別碼的專案已經存在。

patch_item

臨時方法 如果指定的專案存在於容器中，則會使用提供的作業來修補。

如果專案不存在於容器中，則會引發例外狀況。

patch_item(item: str | Dict[str, Any], partition_key: str | int | float | bool, patch_operations: List[Dict[str, Any]], **kwargs: Any) -> Dict[str, Any]

參數

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

必要

識別碼 (名稱) 或聽寫，代表要修補的專案。

partition_key: Union[str, int, float, bool]

必要

要修補之物件的分割區索引鍵。

patch_operations: List[Dict[str, Any]]

必要

要套用至專案的修補程式作業清單。

filter_predicate: str

要套用至修補程式作業的條件式篩選。

pre_trigger_include: str

要作為作業前置觸發程式的觸發程式識別碼。

post_trigger_include: str

要作為後續作業觸發程式的觸發程式識別碼。

session_token: str

用於會話一致性的權杖。

etag: str

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

match_condition: MatchConditions

要用於 etag 的比對條件。

response_hook: Callable

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

傳回

聽寫，表示修補作業完成之後的專案。

傳回類型

dict[str, Any]

例外狀況

CosmosHttpResponseError

修補程式作業失敗，或具有指定識別碼的專案不存在。

query_conflicts

傳回符合指定查詢的所有衝突。

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

參數

query

必要

要執行的 Azure Cosmos DB SQL 查詢。

parameters

必要

查詢的參數選擇性陣列。如果未提供任何查詢，則會忽略。

enable_cross_partition_query

必要

允許傳送多個要求，以在 Azure Cosmos DB 服務中執行查詢。如果查詢的範圍未限定為單一資料分割索引鍵值，則需要多個要求。

partition_key

必要

指定專案的分割區索引鍵值。

max_item_count

必要

列舉作業中要傳回的專案數目上限。

response_hook: Callable

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

傳回

可反覆運算 (聽寫) 衝突。

傳回類型

Iterable[dict[str, Any]]

例外狀況

CosmosHttpResponseError

具有指定識別碼的專案已經存在。

query_items

傳回符合指定查詢的所有結果。

您可以在 FROM 子句中使用容器名稱的任何值，但通常會使用容器名稱。在下列範例中，容器名稱為「products」，且別名為「p」，以方便在 WHERE 子句中參考。

查詢回應中的回應接續權杖。有效值為正整數。值為 0 與未傳遞值相同， (預設沒有限制) 。：keyword int max_integrated_cache_staleness_in_ms：中整合式快取的最大快取過時

毫秒。針對設定為使用整合式快取的帳戶，使用會話或最終一致性，回應保證不會超過此值。

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

傳回

可反覆運算 (聽寫) 的專案。

傳回類型

<xref:ItemPaged>[Dict[str, Any]]

例外狀況

CosmosHttpResponseError

具有指定識別碼的專案已經存在。

範例

取得尚未停止的所有產品：


   import json

   for item in container.query_items(
       query='SELECT * FROM products p WHERE p.productModel <> "DISCONTINUED"',
       enable_cross_partition_query=True,
   ):
       print(json.dumps(item, indent=True))

參數化查詢，以取得已停止的所有產品：


   discontinued_items = container.query_items(
       query='SELECT * FROM products p WHERE p.productModel = @model AND p.productName="Widget"',
       parameters=[dict(name="@model", value="DISCONTINUED")],
   )
   for item in discontinued_items:
       print(json.dumps(item, indent=True))

query_items_change_feed

依修改專案的順序，取得已變更的專案排序清單。

query_items_change_feed(partition_key_range_id: str | None = None, is_start_from_beginning: bool = False, continuation: str | None = None, max_item_count: int | None = None, **kwargs: Any) -> Iterable[Dict[str, Any]]

參數

partition_key_range_id

必要

ChangeFeed 要求可以針對特定的資料分割索引鍵範圍執行。這可用來平行處理多個取用者之間的變更摘要。

partition_key

必要

以 ChangeFeed 要求為目標的分割區索引鍵。

is_start_from_beginning

必要

取得變更摘要應該從開頭開始 (true) ，還是從目前的 (false) 開始。根據預設，它會從目前的 (false) 開始。

continuation

必要

e_tag值做為讀取變更摘要的接續。

max_item_count

必要

列舉作業中要傳回的專案數目上限。

response_hook: Callable

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

傳回

可反覆運算 (聽寫) 的專案。

傳回類型

Iterable[dict[str, Any]]

例外狀況

CosmosHttpResponseError

具有指定識別碼的專案已經存在。

read

讀取容器屬性。

read(*, populate_partition_key_range_statistics: bool | None = None, populate_quota_info: bool | None = None, **kwargs)

參數

populate_partition_key_range_statistics: bool

在回應標頭中啟用傳回分割區索引鍵範圍統計資料。

populate_quota_info: bool

在回應標頭中啟用傳回集合儲存體配額資訊。

session_token: str

用於會話一致性的權杖。

initial_headers: dict[str,str]

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

response_hook: Callable

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

傳回

代表擷取容器的聽寫。

傳回類型

dict[str, Any]

例外狀況

CosmosHttpResponseError

無法擷取容器時引發。這包括容器不存在時。

read_all_items

列出容器中的所有專案。

read_all_items(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

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

max_integrated_cache_staleness_in_ms: int

整合式快取的最大快取過期時間，以毫秒為單位。針對設定為使用整合式快取的帳戶，使用會話或最終一致性，回應保證不會超過此值。

傳回

可反覆運算 (聽寫) 的專案。

傳回類型

Iterable[dict[str, Any]]

例外狀況

CosmosHttpResponseError

具有指定識別碼的專案已經存在。

read_item

取得專案所識別 的專案。

read_item(item: str | Dict[str, Any], partition_key: Any, populate_query_metrics: bool | None = None, post_trigger_include: str | None = None, **kwargs: Any) -> Dict[str, Any]

參數

item

必要

識別碼 (名稱) 或代表要擷取之專案的聽寫。

partition_key

必要

要擷取之專案的分割區索引鍵。

post_trigger_include

必要

要作為作業後觸發程式的觸發程式識別碼。

session_token: str

用於會話一致性的權杖。

initial_headers: dict[str,str]

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

response_hook: Callable

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

max_integrated_cache_staleness_in_ms: int

整合式快取的最大快取過期時間，以毫秒為單位。針對設定為使用整合式快取的帳戶，使用會話或最終一致性，回應保證不會超過此值。

傳回

代表要擷取之專案的聽寫。

傳回類型

dict[str, Any]

例外狀況

CosmosHttpResponseError

無法擷取指定的專案。

範例

從資料庫取得專案，並更新其中一個屬性：


   item = container.read_item("item2", partition_key="Widget")
   item["productModel"] = "DISCONTINUED"
   updated_item = container.upsert_item(item)

read_offer

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

無法擷取輸送量屬性。

read_offer(**kwargs: Any) -> Offer

傳回類型

ThroughputProperties

例外狀況

CosmosHttpResponseError

具有指定識別碼的專案已經存在。

replace_item

如果指定的專案存在於容器中，則會取代它。

如果容器中還沒有任何專案存在，則會引發例外狀況。

replace_item(item: str | Dict[str, Any], body: Dict[str, Any], populate_query_metrics: bool | None = None, pre_trigger_include: str | None = None, post_trigger_include: str | None = None, **kwargs: Any) -> Dict[str, Any]

參數

item

必要

代表要取代之專案的識別碼 (名稱) 或聽寫。

body

必要

類似聽寫的物件，表示要取代的專案。

pre_trigger_include

必要

要作為作業前置觸發程式的觸發程式識別碼。

post_trigger_include

必要

要作為作業後觸發程式的觸發程式識別碼。

session_token: str

用於會話一致性的權杖。

initial_headers: dict[str,str]

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

etag: str

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

match_condition: MatchConditions

要用於 etag 的比對條件。

response_hook: Callable

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

傳回

聽寫，表示取代之後的專案。

傳回類型

dict[str, Any]

例外狀況

CosmosHttpResponseError

取代失敗，或具有指定識別碼的專案不存在。

replace_throughput

取代容器的輸送量。

如果容器中還沒有 ThroughputProperties，則會引發例外狀況。

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

參數

throughput

必要

要設定 (整數) 的輸送量。

response_hook: Callable

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

傳回

容器的 ThroughputProperties，以新的輸送量更新。

傳回類型

ThroughputProperties

例外狀況

CosmosHttpResponseError

容器沒有輸送量屬性，或無法更新輸送量屬性。

upsert_item

插入或更新指定的專案。

如果專案已存在於容器中，則會加以取代。如果專案不存在，則會插入該專案。

upsert_item(body: Dict[str, Any], populate_query_metrics: bool | None = None, pre_trigger_include: str | None = None, post_trigger_include: str | None = None, **kwargs: Any) -> Dict[str, Any]

參數

body

必要

類似聽寫的物件，表示要更新或插入的專案。

pre_trigger_include

必要

要作為作業前置觸發程式的觸發程式識別碼。

post_trigger_include

必要

要作為作業後觸發程式的觸發程式識別碼。

session_token: str

用於會話一致性的權杖。

initial_headers: dict[str,str]

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

etag: str

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

match_condition: MatchConditions

要用於 etag 的比對條件。

response_hook: Callable

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

傳回

表示 upserted 專案的聽寫。

傳回類型

dict[str, Any]

例外狀況

CosmosHttpResponseError

無法插入指定的專案。