共用方式為

ContainerProxy 類別

  • 參考

與特定 DB 容器互動的介面。

此類別不應該直接具現化。 請改用 <xref:azure.cosmos.aio.database.DatabaseProxy.get_container_client> 方法來取得現有的容器，或 <xref:azure.cosmos.aio.database.DatabaseProxy.create_container> 建立新容器的方法。

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

繼承
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 存在，就會引發例外狀況。
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

取得專案所識別 的專案。
replace_item

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

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

取代容器的輸送量。

如果容器中沒有任何 ThroughputProperties 存在，就會引發例外狀況。
upsert_item

插入或更新指定的專案。

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

create_item

在容器中建立專案。

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

async create_item(body: Dict[str, Any], **kwargs: Any) -> Dict[str, Any]

參數

body
dict[str, str]
必要

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

pre_trigger_include
str

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

post_trigger_include
str

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

indexing_directive
Union[int, IndexingDirective]

列舉可能的值，指出是否應該從編制索引中省略檔。 可能的值為：0 表示 Default、1 表示 Exclude，或 2 表示 Include。

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, str], Dict[str, Any]], None]

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

傳回

表示新專案的聽寫。

傳回類型

Dict[str, Any]

例外狀況

CosmosHttpResponseError

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

delete_all_items_by_partition_key

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

async 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

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

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

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

參數

conflict
Union[str, Dict[str, Any]]
必要

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

partition_key
Union[str, int, float, bool]
必要

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

response_hook
Callable[[Dict[str, str], None], None]

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

傳回類型

None

例外狀況

CosmosHttpResponseError

衝突未成功刪除。

CosmosResourceNotFoundError

衝突不存在於容器中。

delete_item

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

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

async delete_item(item: str | Dict[str, Any], partition_key: str | int | float | bool, **kwargs: Any) -> None

參數

item
Union[str, Dict[str, Any]]
必要

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

partition_key
Union[str, int, float, bool]
必要

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

pre_trigger_include
str

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

post_trigger_include
str

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

session_token
str

用於會話一致性的權杖。

initial_headers
dict[str, str]

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

etag
str

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

match_condition
MatchConditions

要用於 etag 的比對條件。

response_hook
Callable[[Dict[str, str], None], None]

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

傳回類型

None

例外狀況

CosmosHttpResponseError

專案未成功刪除。

CosmosResourceNotFoundError

專案不存在於容器中。

get_conflict

取得衝突所識別的 衝突。

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

參數

conflict
Union[str, Dict[str, Any]]
必要

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

partition_key
Union[str, int, float, bool]
必要

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

response_hook
Callable[[Dict[str, str], Dict[str, Any]], None]

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

傳回

表示所擷取衝突的聽寫。

傳回類型

Dict[str, Any]

例外狀況

CosmosHttpResponseError

無法擷取指定的衝突。

get_throughput

取得此容器的 ThroughputProperties 物件。

如果容器中沒有任何 ThroughputProperties 存在，就會引發例外狀況。

async get_throughput(**kwargs: Any) -> ThroughputProperties

參數

response_hook
Callable[[Dict[str, str], List[Dict[str, Any]]], None]

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

傳回

容器的 ThroughputProperties。

傳回類型

ThroughputProperties

例外狀況

CosmosHttpResponseError

容器沒有輸送量屬性，或無法擷取輸送量屬性。

list_conflicts

列出容器中的所有衝突。

list_conflicts(**kwargs: Any) -> AsyncItemPaged[Dict[str, Any]]

參數

max_item_count
int

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

response_hook
Callable[[Dict[str, str], <xref:AsyncItemPaged>[Dict[str, Any]]], None]

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

傳回

(聽寫) 衝突的 AsyncItemPaged。

傳回類型

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

例外狀況

CosmosHttpResponseError

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

patch_item

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

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

async 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 | Dict[str, Any], **kwargs: Any) -> AsyncItemPaged[Dict[str, Any]]

參數

query
Union[str, Dict[str, Any]]
必要

要執行的 Azure Cosmos DB SQL 查詢。

parameters
List[Dict[str, Any]]

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

partition_key
Union[str, int, float, bool]

指定專案的分割區索引鍵值。 如果未傳入任何資料分割，則會執行跨分割區查詢。

max_item_count
int

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

response_hook
Callable[[Dict[str, str], <xref:AsyncItemPaged>[Dict[str, Any]]], None]

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

傳回

(聽寫) 衝突的 AsyncItemPaged。

傳回類型

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

例外狀況

CosmosHttpResponseError

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

query_items

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

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

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

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

query_items(query: str | Dict[str, Any], **kwargs: Any) -> AsyncItemPaged[Dict[str, Any]]

傳回

專案的 AsyncItemPaged (聽寫) 。

傳回類型

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

例外狀況

CosmosHttpResponseError

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

範例

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


           import json

           async for item in container.query_items(
                   query='SELECT * FROM products p WHERE p.productModel <> "DISCONTINUED"'
           ):
               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")],
           )
           async for item in discontinued_items:
               print(json.dumps(item, indent=True))

query_items_change_feed

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

query_items_change_feed(**kwargs: Any) -> AsyncItemPaged[Dict[str, Any]]

參數

is_start_from_beginning
bool

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

partition_key_range_id
str

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

continuation
str

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

max_item_count
int

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

partition_key
Union[str, int, float, bool]

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

response_hook
Callable[[Dict[str, str], <xref:AsyncItemPaged>[Dict[str, Any]]], None]

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

傳回

專案的 AsyncItemPaged (聽寫) 。

傳回類型

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

例外狀況

CosmosHttpResponseError

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

read

讀取容器屬性。

async read(**kwargs: Any) -> Dict[str, Any]

參數

populate_partition_key_range_statistics
bool

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

populate_quota_info
bool

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

session_token
str

用於會話一致性的權杖。

initial_headers
dict[str, str]

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

response_hook
Callable[[Dict[str, str], Dict[str, Any]], None]

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

傳回

表示所擷取容器的聽寫。

傳回類型

Dict[str, Any]

例外狀況

CosmosHttpResponseError

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

read_all_items

列出容器中的所有專案。

read_all_items(**kwargs: Any) -> AsyncItemPaged[Dict[str, Any]]

參數

max_item_count
int

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

session_token
str

用於會話一致性的權杖。

initial_headers
dict[str, str]

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

response_hook
Callable[[Dict[str, str], <xref:AsyncItemPaged>[Dict[str, Any]]], None]

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

max_integrated_cache_staleness_in_ms
int

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

傳回

專案的 AsyncItemPaged (聽寫) 。

傳回類型

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

例外狀況

CosmosHttpResponseError

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

read_item

取得專案所識別 的專案。

async read_item(item: str | Dict[str, Any], partition_key: str | int | float | bool, **kwargs: Any) -> Dict[str, Any]

參數

item
Union[str, Dict[str, Any]]
必要

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

partition_key
Union[str, int, float, bool]
必要

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

post_trigger_include
str

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

session_token
str

用於會話一致性的權杖。

initial_headers
dict[str, str]

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

response_hook
Callable[[Dict[str, str], Dict[str, Any]], None]

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

max_integrated_cache_staleness_in_ms
int

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

傳回

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

傳回類型

Dict[str, Any]

例外狀況

CosmosHttpResponseError

無法擷取指定的專案。

範例

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


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

replace_item

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

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

async replace_item(item: str | Dict[str, Any], body: Dict[str, Any], **kwargs: Any) -> Dict[str, Any]

參數

item
Union[str, Dict[str, Any]]
必要

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

body
Dict[str, Any]
必要

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

pre_trigger_include
str

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

post_trigger_include
str

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

session_token
str

用於會話一致性的權杖。

initial_headers
dict[str, str]

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

etag
str

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

match_condition
MatchConditions

要用於 etag 的比對條件。

response_hook
Callable[[Dict[str, str], Dict[str, Any]], None]

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

傳回

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

傳回類型

Dict[str, Any]

例外狀況

CosmosHttpResponseError

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

replace_throughput

取代容器的輸送量。

如果容器中沒有任何 ThroughputProperties 存在，就會引發例外狀況。

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

參數

throughput
Union[int, ThroughputProperties]
必要

要設定的輸送量。

response_hook
Callable[[Dict[str, str], Dict[str, Any]], None]

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

傳回

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

傳回類型

ThroughputProperties

例外狀況

CosmosHttpResponseError

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

upsert_item

插入或更新指定的專案。

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

async upsert_item(body: Dict[str, Any], **kwargs: Any) -> Dict[str, Any]

參數

body
Dict[str, Any]
必要

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

pre_trigger_include
str

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

post_trigger_include
str

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

session_token
str

用於會話一致性的權杖。

initial_headers
dict[str, str]

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

etag
str

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

match_condition
MatchConditions

要用於 etag 的比對條件。

response_hook
Callable[[Dict[str, str], Dict[str, Any]], None]

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

傳回

表示 upserted 專案的聽寫。

傳回類型

Dict[str, Any]

例外狀況

CosmosHttpResponseError

無法向上插入指定的專案。

屬性

is_system_key

scripts