你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

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

容器的 ID (名称)

session_token

str

容器的会话令牌。

方法

create_item	在容器中创建项。 若要更新或替换现有项，请使用 upsert_item 方法。
delete_all_items_by_partition_key	按分区键删除功能是一项异步后台操作，它允许你使用 Cosmos SDK 删除具有相同逻辑分区键值的所有文档。 按分区键删除操作限制为每秒最多消耗容器中可用 RU/s 总数的 10%。 这有助于限制此后台任务使用的资源。
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

必需

一个类似于 dict 的对象，表示要创建的项。

pre_trigger_include

必需

要用作操作前触发器的触发器 ID。

post_trigger_include

必需

要用作操作后触发器的触发器 ID。

indexing_directive

必需

指示是否应从索引中省略文档。

enable_automatic_id_generation

bool

如果不存在 ID，则启用自动 ID 生成。

session_token

str

用于会话一致性的令牌。

initial_headers

dict[str,str]

作为请求的一部分发送的初始标头。

etag

str

ETag 值或通配符 (*)。 用于检查资源是否已更改，并根据 match_condition 参数指定的条件进行操作。

match_condition

MatchConditions

要对 etag 使用的匹配条件。

response_hook

Callable

使用响应元数据调用的可调用项。

返回

表示新项的 dict。

返回类型

dict[str, Any]

例外

CosmosHttpResponseError

具有给定 ID 的项已存在。

delete_all_items_by_partition_key

按分区键删除功能是一项异步后台操作，它允许你使用 Cosmos SDK 删除具有相同逻辑分区键值的所有文档。 按分区键删除操作限制为每秒最多消耗容器中可用 RU/s 总数的 10%。 这有助于限制此后台任务使用的资源。

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

参数

partition_key

Any

必需

要删除的项的分区键。

pre_trigger_include

str

要用作操作前触发器的触发器 ID。

post_trigger_include

str

要用作操作后触发器的触发器 ID。

session_token

str

用于会话一致性的令牌。

etag

str

ETag 值或通配符 (*)。 用于检查资源是否已更改，并根据 match_condition 参数指定的条件进行操作。

match_condition

MatchConditions

要对 etag 使用的匹配条件。

response_hook

Callable

使用响应元数据调用的可调用项。

返回类型

None

例外

CosmosHttpResponseError

具有给定 ID 的项已存在。

delete_conflict

从容器中删除指定的冲突。

如果容器中尚不存在冲突，则会引发异常。

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

参数

conflict

必需

ID (名称) 或表示要删除的冲突的 dict。

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

必需

ID (名称) 或表示要删除的项的 dict。

partition_key

必需

指定项的分区键值。

pre_trigger_include

必需

要用作操作前触发器的触发器 ID。

post_trigger_include

必需

要用作操作后触发器的触发器 ID。

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

必需

ID (名称) 或表示要检索的冲突的 dict。

partition_key

必需

要检索的冲突的分区键。

response_hook

Callable

使用响应元数据调用的可调用项。

返回

表示检索到的冲突的 dict。

返回类型

dict[str, Any]

例外

CosmosHttpResponseError

无法检索给定的冲突。

get_throughput

获取此容器的 ThroughputProperties 对象。

如果容器不存在任何 ThroughputProperties，则会引发异常。 ：关键字 (keyword) 可调用response_hook：使用响应元数据调用的可调用项。 ：returns：容器的吞吐量。 ：raises ~azure.cosmos.exceptions.CosmosHttpResponseError：不存在容器或的吞吐量属性

无法检索吞吐量属性。

get_throughput(**kwargs: Any) -> ThroughputProperties

返回类型

ThroughputProperties

例外

CosmosHttpResponseError

具有给定 ID 的项已存在。

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

具有给定 ID 的项已存在。

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

必需

ID (名称) 或表示要修补的项的 dict。

partition_key

Union[str, int, float, bool]

必需

要修补的对象的分区键。

patch_operations

List[Dict[str, Any]]

必需

要应用于项的修补操作的列表。

filter_predicate

str

要应用于修补操作的条件筛选器。

pre_trigger_include

str

要用作操作前触发器的触发器 ID。

post_trigger_include

str

要用作操作后触发器的触发器 ID。

session_token

str

用于会话一致性的令牌。

etag

str

ETag 值或通配符 (*)。 用于检查资源是否已更改，并根据 match_condition 参数指定的条件进行操作。

match_condition

MatchConditions

要对 etag 使用的匹配条件。

response_hook

Callable

使用响应元数据调用的可调用项。

返回

一个在修补操作完成之后表示项的 dict。

返回类型

dict[str, Any]

例外

CosmosHttpResponseError

修补操作失败，或者具有给定 ID 的项不存在。

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

具有给定 ID 的项已存在。

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

具有给定 ID 的项已存在。

示例

获取尚未停产的所有产品：

   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

具有给定 ID 的项已存在。

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。

返回类型

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

具有给定 ID 的项已存在。

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

必需

ID (名称) 或表示要检索的项的 dict。

partition_key

必需

要检索的项的分区键。

post_trigger_include

必需

要用作操作后触发器的触发器 ID。

session_token

str

用于会话一致性的令牌。

initial_headers

dict[str,str]

作为请求的一部分发送的初始标头。

response_hook

Callable

使用响应元数据调用的可调用项。

max_integrated_cache_staleness_in_ms

int

集成缓存的最大缓存过期性（以毫秒为单位）。 对于配置为使用集成缓存（使用会话或最终一致性）的帐户，保证响应不会超过此值。

返回

表示要检索的项的 Dict。

返回类型

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

具有给定 ID 的项已存在。

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

必需

表示要替换的项的 ID (名称) 或 dict。

body

必需

一个类似于 dict 的对象，表示要替换的项。

pre_trigger_include

必需

要用作操作前触发器的触发器 ID。

post_trigger_include

必需

要用作操作后触发器的触发器 ID。

session_token

str

用于会话一致性的令牌。

initial_headers

dict[str,str]

作为请求的一部分发送的初始标头。

etag

str

ETag 值或通配符 (*)。 用于检查资源是否已更改，并根据 match_condition 参数指定的条件进行操作。

match_condition

MatchConditions

要对 etag 使用的匹配条件。

response_hook

Callable

使用响应元数据调用的可调用项。

返回

表示替换后的项的 dict。

返回类型

dict[str, Any]

例外

CosmosHttpResponseError

替换失败，或者具有给定 ID 的项不存在。

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

必需

一个类似于 dict 的对象，表示要更新或插入的项。

pre_trigger_include

必需

要用作操作前触发器的触发器 ID。

post_trigger_include

必需

要用作操作后触发器的触发器 ID。

session_token

str

用于会话一致性的令牌。

initial_headers

dict[str,str]

作为请求的一部分发送的初始标头。

etag

str

ETag 值或通配符 (*)。 用于检查资源是否已更改，并根据 match_condition 参数指定的条件进行操作。

match_condition

MatchConditions

要对 etag 使用的匹配条件。

response_hook

Callable

使用响应元数据调用的可调用项。

返回

表示更新插入的项的 dict。

返回类型

dict[str, Any]

例外

CosmosHttpResponseError

无法向上插入给定项。

属性

is_system_key

scripts