共用方式為


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 刪除具有相同邏輯分割區索引鍵值的所有檔。 分割區索引鍵作業的刪除限制,每秒最多耗用 10% 的容器上可用的 RU/秒總數。 這有助於限制此背景工作所使用的資源。

delete_conflict

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

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

delete_item

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

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

get_conflict

取得衝突所識別的 衝突

get_throughput

取得此容器的 ThroughputProperties 物件。

如果容器中還沒有 ThroughputProperties,則會引發例外狀況。 :keyword 可呼叫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

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

傳回

表示新專案的聽寫。

傳回類型

例外狀況

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

delete_all_items_by_partition_key

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

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

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

傳回類型

例外狀況

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

delete_conflict

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

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

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

參數

conflict
必要

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

partition_key
必要

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

response_hook
Callable

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

傳回類型

例外狀況

衝突未成功刪除。

此衝突不存在於容器中。

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

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

傳回類型

例外狀況

專案未成功刪除。

專案不存在於容器中。

get_conflict

取得衝突所識別的 衝突

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

參數

conflict
必要

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

partition_key
必要

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

response_hook
Callable

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

傳回

表示擷取衝突的聽寫。

傳回類型

例外狀況

無法擷取指定的衝突。

get_throughput

取得此容器的 ThroughputProperties 物件。

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

無法擷取輸送量屬性。

get_throughput(**kwargs: Any) -> ThroughputProperties

傳回類型

例外狀況

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

list_conflicts

列出容器中的所有衝突。

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

參數

max_item_count
必要

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

response_hook
Callable

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

傳回

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

傳回類型

例外狀況

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

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

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

傳回

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

傳回類型

例外狀況

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

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

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

傳回

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

傳回類型

例外狀況

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

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]]

例外狀況

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

範例

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


   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

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

傳回

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

傳回類型

例外狀況

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

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

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

傳回

代表擷取容器的聽寫。

傳回類型

例外狀況

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

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

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

傳回

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

傳回類型

例外狀況

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

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

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

傳回

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

傳回類型

例外狀況

無法擷取指定的專案。

範例

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


   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

傳回類型

例外狀況

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

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

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

傳回

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

傳回類型

例外狀況

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

replace_throughput

取代容器的輸送量。

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

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

參數

throughput
必要

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

response_hook
Callable

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

傳回

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

傳回類型

例外狀況

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

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 專案的聽寫。

傳回類型

例外狀況

無法插入指定的專案。

屬性

is_system_key

scripts