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

ContainerProxy 类

用于与特定数据库容器交互的接口。

此类不应直接实例化。 请改用 <xref:azure.cosmos.aio.database.DatabaseProxy.get_container_client> 方法获取现有容器，或使用 <xref:azure.cosmos.aio.database.DatabaseProxy.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，则会引发异常。
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]

必需

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

pre_trigger_include

str

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

post_trigger_include

str

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

indexing_directive

Union[int, IndexingDirective]

枚举可能的值，以指示是否应从索引中省略文档。 可能的值包括：0 表示 Default，1 表示 Exclude，或 2 表示 Include。

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

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

返回

表示新项的 dict。

返回类型

Dict[str, Any]

例外

CosmosHttpResponseError

具有给定 ID 的项已存在。

delete_all_items_by_partition_key

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

async 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

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

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

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

参数

conflict

Union[str, Dict[str, Any]]

必需

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

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

必需

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

partition_key

Union[str, int, float, bool]

必需

指定项的分区键值。

pre_trigger_include

str

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

post_trigger_include

str

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

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

必需

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

partition_key

Union[str, int, float, bool]

必需

要检索的冲突的分区键。

response_hook

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

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

返回

表示检索到的冲突的 dict。

返回类型

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

具有给定 ID 的项已存在。

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

必需

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

例外

CosmosHttpResponseError

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

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

具有给定 ID 的项已存在。

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

具有给定 ID 的项已存在。

示例

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

           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

具有给定 ID 的项已存在。

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。

返回类型

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

具有给定 ID 的项已存在。

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

必需

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

partition_key

Union[str, int, float, bool]

必需

要检索的项的分区键。

post_trigger_include

str

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

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。

返回类型

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

必需

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

body

Dict[str, Any]

必需

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

pre_trigger_include

str

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

post_trigger_include

str

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

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

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

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]

必需

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

pre_trigger_include

str

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

post_trigger_include

str

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

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。

返回类型

Dict[str, Any]

例外

CosmosHttpResponseError

无法重新插入给定项。

属性

is_system_key

scripts