通过

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

DatabaseProxy 类

  • 参考

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

不应直接实例化此类。 请改用 <xref:CosmosClient.get_database_client> 方法。

数据库包含一个或多个容器，每个容器可以包含项、存储过程、触发器和用户定义的函数。

数据库还可以具有关联的用户，其中每个用户都配置了一组用于访问某些容器、存储过程、触发器、用户定义函数或项的权限。

Azure Cosmos DB SQL API 数据库具有以下系统生成的属性。 这些属性是只读的：

  • _rid：资源 ID。

  • _ts：上次更新资源的时间。 高值是一个时间戳。

  • _self：资源的唯一可寻址 URI。

  • _etag：乐观并发控制所需的资源 etag。

  • _colls：集合资源的可寻址路径。

  • _users：用户资源的可寻址路径。

继承
builtins.object
DatabaseProxy

构造函数

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

参数

client_connection
<xref:ClientSession>
必需

从中检索此数据库的客户端。

id
str
必需

ID (数据库的名称) 。

properties
默认值: None

变量

id

数据库的 ID (名称) 。

方法

create_container

使用给定 ID 创建新容器 (名称) 。

如果具有给定 ID 的容器已存在，则会引发 CosmosResourceExistsError。
create_container_if_not_exists

创建容器（如果尚不存在）。

如果容器已存在，则返回现有设置。 注意：它不会检查或更新现有容器设置，也不会提供吞吐量（如果这些设置与传递到 方法中的设置不同）。
create_user

在容器中创建新用户。

若要更新或替换现有用户，请使用 <xref:ContainerProxy.upsert_user> 方法。
delete_container

删除容器。
delete_user

从容器中删除指定的用户。
get_container_client

获取具有指定 ID 的容器的 ContainerProxy (名称) 。
get_throughput

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

无法检索吞吐量属性。
get_user_client

获取具有指定 ID 的用户的 UserProxy 。
list_containers

列出数据库中的容器。
list_users

列出容器中的所有用户。
query_containers

列出当前数据库中容器的属性。
query_users

返回与给定 查询匹配的所有用户。
read

读取数据库属性。
read_offer

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

无法检索吞吐量属性。
replace_container

重置容器的属性。

属性更改会立即持久保存。 未指定的任何属性都将重置为其默认值。
replace_throughput

替换数据库级吞吐量。
replace_user

如果指定的用户存在于容器中，则替换该用户。
upsert_user

插入或更新指定的用户。

如果该用户已存在于容器中，则会替换该用户。 如果用户尚不存在，则插入该用户。

create_container

使用给定 ID 创建新容器 (名称) 。

如果具有给定 ID 的容器已存在，则会引发 CosmosResourceExistsError。

create_container(id: str, partition_key: Any, indexing_policy: Dict[str, Any] | None = None, default_ttl: int | None = None, populate_query_metrics: bool | None = None, offer_throughput: int | ThroughputProperties | None = None, unique_key_policy: Dict[str, Any] | None = None, conflict_resolution_policy: Dict[str, Any] | None = None, **kwargs: Any) -> ContainerProxy

参数

id
必需

要创建的容器的 ID (名称) 。

partition_key
必需

要用于容器的分区键。

indexing_policy
必需

要应用于容器的索引策略。

default_ttl
必需

容器中项的默认生存时间 (TTL) 。 如果未指定，则项目不会过期。

offer_throughput
int 或 <xref:azure.cosmos.ThroughputProperties.>
必需

此产品/服务的预配吞吐量。

unique_key_policy
必需

要应用于容器的唯一密钥策略。

conflict_resolution_policy
必需

要应用于容器的冲突解决策略。

session_token
str

用于会话一致性的令牌。

initial_headers
dict[str,str]

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

etag
str

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

match_condition
MatchConditions

要对 etag 使用的匹配条件。

response_hook
Callable

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

analytical_storage_ttl
int

容器中项的分析存储生存时间 (TTL) 。 如果值为 None，则关闭分析存储，值为 -1 将打开分析存储且不带 TTL。 请注意，只能在启用Synapse Link帐户上启用分析存储。

返回

表示新容器的 ContainerProxy 实例。

返回类型

ContainerProxy

例外

CosmosHttpResponseError

容器创建失败。

示例

使用默认设置创建容器：


   container_name = "products"
   try:
       container = database.create_container(
           id=container_name, partition_key=PartitionKey(path="/productName")
       )
   except exceptions.CosmosResourceExistsError:
       container = database.get_container_client(container_name)

创建具有特定设置的容器;在本例中，自定义分区键为：


   customer_container_name = "customers"
   try:
       customer_container = database.create_container(
           id=customer_container_name,
           partition_key=PartitionKey(path="/city"),
           default_ttl=200,
       )
   except exceptions.CosmosResourceExistsError:
       customer_container = database.get_container_client(customer_container_name)

create_container_if_not_exists

创建容器（如果尚不存在）。

如果容器已存在，则返回现有设置。 注意：它不会检查或更新现有容器设置，也不会提供吞吐量（如果这些设置与传递到 方法中的设置不同）。

create_container_if_not_exists(id: str, partition_key: Any, indexing_policy: Dict[str, Any] | None = None, default_ttl: int | None = None, populate_query_metrics: bool | None = None, offer_throughput: int | ThroughputProperties | None = None, unique_key_policy: Dict[str, Any] | None = None, conflict_resolution_policy: Dict[str, Any] | None = None, **kwargs: Any) -> ContainerProxy

参数

id
必需

要读取或创建的容器的 ID (名称) 。

partition_key
必需

要用于容器的分区键。

indexing_policy
必需

要应用于容器的索引策略。

default_ttl
必需

容器中项的默认生存时间 (TTL) 。 如果未指定，则项目不会过期。

populate_query_metrics
必需

启用在响应标头中返回查询指标。

offer_throughput
必需

此产品/服务的预配吞吐量。

unique_key_policy
必需

要应用于容器的唯一密钥策略。

conflict_resolution_policy
必需

要应用于容器的冲突解决策略。

session_token
str

用于会话一致性的令牌。

initial_headers
dict[str,str]

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

etag
str

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

match_condition
MatchConditions

要对 etag 使用的匹配条件。

response_hook
Callable

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

analytical_storage_ttl
int

容器中项的分析存储生存时间 (TTL) 。 如果值为 None，则关闭分析存储，值为 -1 将打开分析存储且不带 TTL。 请注意，只能在启用Synapse Link帐户上启用分析存储。

返回

表示 容器的 ContainerProxy 实例。

返回类型

ContainerProxy

例外

CosmosHttpResponseError

容器读取或创建失败。

create_user

在容器中创建新用户。

若要更新或替换现有用户，请使用 <xref:ContainerProxy.upsert_user> 方法。

create_user(body: Dict[str, Any], **kwargs: Any) -> UserProxy

参数

body
必需

具有 ID 键和值（表示要创建的用户）的类似 dict 的对象。 用户 ID 在数据库中必须是唯一的，并且不能超过 255 个字符。

response_hook
Callable

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

返回

一个代表新用户的 UserProxy 实例。

返回类型

UserProxy

例外

CosmosHttpResponseError

如果无法创建给定的用户。

示例

创建数据库用户：


   try:
       database.create_user(dict(id="Walter Harp"))
   except exceptions.CosmosResourceExistsError:
       print("A user with that ID already exists.")
   except exceptions.CosmosHttpResponseError as failure:
       print("Failed to create user. Status code:{}".format(failure.status_code))

delete_container

删除容器。

delete_container(container: str | ContainerProxy | Dict[str, Any], populate_query_metrics: bool | None = None, **kwargs: Any) -> None

参数

container
必需

要删除的容器的 ID (名称) 。 可以传入要删除的容器的 ID、 <xref:azure.cosmos.database.ContainerProxy> 实例或表示容器属性的 dict。

session_token
str

用于会话一致性的令牌。

initial_headers
dict[str,str]

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

etag
str

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

match_condition
MatchConditions

要对 etag 使用的匹配条件。

response_hook
Callable

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

返回类型

None

例外

CosmosHttpResponseError

如果无法删除容器。

delete_user

从容器中删除指定的用户。

delete_user(user: str | UserProxy | Dict[str, Any], **kwargs: Any) -> None

参数

user
必需

ID (名称) ，表示要删除的用户的属性或 <xref:azure.cosmos.database.UserProxy> 实例的 dict。

response_hook
Callable

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

返回类型

None

例外

CosmosHttpResponseError

用户未成功删除。

CosmosResourceNotFoundError

容器中不存在用户。

get_container_client

获取具有指定 ID 的容器的 ContainerProxy (名称) 。

get_container_client(container: str | ContainerProxy | Dict[str, Any]) -> ContainerProxy

参数

container
必需

ID (容器、 <xref:azure.cosmos.database.ContainerProxy> 实例或表示要检索的容器属性的 dict 的名称) 。

返回

表示检索到的数据库的 ContainerProxy 实例。

返回类型

ContainerProxy

例外

CosmosHttpResponseError

容器创建失败。

示例

获取现有容器，如果遇到，则处理故障：


   database = client.get_database_client(database_name)
   container = database.get_container_client(container_name)

get_throughput

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

无法检索吞吐量属性。

get_throughput(**kwargs: Any) -> ThroughputProperties

返回类型

ThroughputProperties

例外

CosmosHttpResponseError

容器创建失败。

get_user_client

获取具有指定 ID 的用户的 UserProxy 。

get_user_client(user: str | UserProxy | Dict[str, Any]) -> UserProxy

参数

user
必需

ID (名称) ，表示要检索的用户的属性或 <xref:azure.cosmos.database.UserProxy> 实例的 dict。

返回

表示检索到的用户的 UserProxy 实例。

返回类型

UserProxy

例外

CosmosHttpResponseError

容器创建失败。

list_containers

列出数据库中的容器。

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

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

返回

容器属性 () 的可迭代项。

返回类型

Iterable[dict[str, Any]]

例外

CosmosHttpResponseError

容器创建失败。

示例

列出数据库中的所有容器：


   database = client.get_database_client(database_name)
   for container in database.list_containers():
       print("Container ID: {}".format(container['id']))

list_users

列出容器中的所有用户。

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

参数

max_item_count
必需

枚举操作中要返回的最大用户数。

response_hook
Callable

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

返回

用户属性的可迭代 (听写) 。

返回类型

Iterable[dict[str, Any]]

例外

CosmosHttpResponseError

容器创建失败。

query_containers

列出当前数据库中容器的属性。

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

参数

query
必需

要执行的 Azure Cosmos DB SQL 查询。

parameters
必需

查询参数的可选数组。 如果未提供查询，则忽略。

max_item_count
必需

枚举操作中要返回的最大项数。

session_token
str

用于会话一致性的令牌。

initial_headers
dict[str,str]

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

response_hook
Callable

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

返回

容器属性 () 的可迭代项。

返回类型

Iterable[dict[str, Any]]

例外

CosmosHttpResponseError

容器创建失败。

query_users

返回与给定 查询匹配的所有用户。

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

参数

query
必需

要执行的 Azure Cosmos DB SQL 查询。

parameters
必需

查询参数的可选数组。 如果未提供查询，则忽略。

max_item_count
必需

枚举操作中要返回的最大用户数。

response_hook
Callable

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

返回

用户属性的可迭代 (听写) 。

返回类型

Iterable[str, Any]

例外

CosmosHttpResponseError

容器创建失败。

read

读取数据库属性。

read(populate_query_metrics: bool | None = None, **kwargs: Any) -> Dict[str, Any]

参数

session_token
str

用于会话一致性的令牌。

initial_headers
dict[str,str]

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

response_hook
Callable

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

返回类型

Dict[<xref:Str>, Any]

例外

CosmosHttpResponseError

如果无法检索给定的数据库。

read_offer

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

无法检索吞吐量属性。

read_offer(**kwargs: Any) -> ThroughputProperties

返回类型

ThroughputProperties

例外

CosmosHttpResponseError

容器创建失败。

replace_container

重置容器的属性。

属性更改会立即持久保存。 未指定的任何属性都将重置为其默认值。

replace_container(container: str | ContainerProxy | Dict[str, Any], partition_key: Any, indexing_policy: Dict[str, Any] | None = None, default_ttl: int | None = None, conflict_resolution_policy: Dict[str, Any] | None = None, populate_query_metrics: bool | None = None, **kwargs: Any) -> ContainerProxy

参数

container
必需

ID (名称) ，表示要替换的容器的属性或 <xref:azure.cosmos.database.ContainerProxy> 实例的 dict。

partition_key
必需

要用于容器的分区键。

indexing_policy
必需

要应用于容器的索引策略。

default_ttl
必需

容器中项的默认生存时间 (TTL) 。 如果未指定，则项目不会过期。

conflict_resolution_policy
必需

要应用于容器的冲突解决策略。

populate_query_metrics
必需

启用在响应标头中返回查询指标。

session_token
str

用于会话一致性的令牌。

etag
str

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

match_condition
MatchConditions

要对 etag 使用的匹配条件。

initial_headers
dict[str,str]

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

response_hook
Callable

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

analytical_storage_ttl
int

容器中项的分析存储生存时间 (TTL) 。 如果值为 None，则关闭分析存储，值为 -1 将打开分析存储且不带 TTL。 请注意，只能在启用Synapse Link帐户上启用分析存储。

返回

一个 ContainerProxy 实例，表示替换完成后的容器。

返回类型

ContainerProxy

例外

CosmosHttpResponseError

如果无法替换容器，则引发。 这包括是否存在具有给定 ID 的容器。

示例

重置容器上的 TTL 属性，并显示更新的属性：


   # Set the TTL on the container to 3600 seconds (one hour)
   database.replace_container(container, partition_key=PartitionKey(path='/productName'), default_ttl=3600)

   # Display the new TTL setting for the container
   container_props = database.get_container_client(container_name).read()
   print("New container TTL: {}".format(json.dumps(container_props['defaultTtl'])))

replace_throughput

替换数据库级吞吐量。

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

参数

throughput
必需

要 (整数) 设置的吞吐量。

response_hook
Callable

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

返回

数据库的 ThroughputProperties，更新了新的吞吐量。

返回类型

ThroughputProperties

例外

CosmosHttpResponseError

如果数据库不存在吞吐量属性，或者无法更新吞吐量属性，

replace_user

如果指定的用户存在于容器中，则替换该用户。

replace_user(user: str | UserProxy | Dict[str, Any], body: Dict[str, Any], **kwargs: Any) -> UserProxy

参数

user
必需

ID (名称) ，表示要替换的用户的属性或 <xref:azure.cosmos.database.UserProxy> 实例的 dict。

body
必需

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

response_hook
Callable

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

返回

在替换通过后表示用户的 UserProxy 实例。

返回类型

UserProxy

例外

CosmosHttpResponseError

如果替换失败，或者具有给定 ID 的用户不存在。

upsert_user

插入或更新指定的用户。

如果该用户已存在于容器中，则会替换该用户。 如果用户尚不存在，则插入该用户。

upsert_user(body: Dict[str, Any], **kwargs: Any) -> UserProxy

参数

body
必需

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

response_hook
Callable

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

返回

一个 UserProxy 实例，表示已更新插入的用户。

返回类型

UserProxy

例外

CosmosHttpResponseError

如果无法更新插入给定的用户。