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

CosmosClient 类

Azure Cosmos DB 帐户的客户端逻辑表示形式。

使用此客户端配置和执行对 Azure Cosmos DB 服务的请求。

建议在应用程序的生存期内维护 CosmosClient 的单个实例，从而实现高效的连接管理和性能。

CosmosClient 初始化是一项繁重的操作 - 不要使用初始化 CosmosClient 实例作为凭据或网络连接验证。

实例化新的 CosmosClient。

继承

builtins.object

CosmosClient

构造函数

CosmosClient(url: str, credential: Any, consistency_level: str | None = None, **kwargs: Any)

参数

url

str

必需

Cosmos DB 帐户的 URL。

credential

Union[str, Dict[str, str], TokenCredential]

必需

可以是帐户密钥，也可以是资源令牌字典。

consistency_level

str

默认值: None

用于会话的一致性级别。 默认值为 None (帐户级别) 。 有关一致性级别和可能值的详细信息： https://aka.ms/cosmos-consistency-levels

timeout

int

对于组合的 HTTP 请求和响应处理，绝对超时（以秒为单位）。

connection_timeout

int

HTTP 请求超时（以秒为单位）。

connection_mode

str

客户端的连接模式 - 目前仅支持“网关”。

proxy_config

ProxyConfiguration

连接代理配置。

ssl_config

SSLConfiguration

连接 SSL 配置。

connection_verify

bool

是否验证连接，默认值为 True。

connection_cert

str

用于验证连接的备用证书。

retry_total

int

最大重试尝试次数。

retry_backoff_max

int

最大重试等待时间（以秒为单位）。

retry_fixed_interval

int

修复了重试间隔（以毫秒为单位）。

retry_read

int

套接字读取重试的最大次数。

retry_connect

int

连接错误重试的最大次数。

retry_status

int

错误状态代码的最大重试尝试次数。

retry_on_status_codes

list[int]

要重试的特定状态代码的列表。

retry_backoff_factor

float

计算重试尝试之间的等待时间的因素。

enable_endpoint_discovery

bool

为异地复制的数据库帐户启用终结点发现。 （默认值：True）

preferred_locations

list[str]

异地复制数据库帐户的首选位置。

enable_diagnostics_logging

bool

启用 CosmosHttpLogging 策略。 必须与记录器一起使用才能正常工作。

logger

Logger

用于收集请求诊断的记录器。 可以在客户端级别传入 (，以记录) 或单个请求级别的所有请求。 请求将在信息级别记录。

示例

创建 Cosmos DB 客户端的新实例：

   from azure.cosmos import exceptions, CosmosClient, PartitionKey

   import os

   url = os.environ["ACCOUNT_URI"]
   key = os.environ["ACCOUNT_KEY"]
   client = CosmosClient(url, key)

方法

create_database	创建具有给定 ID 的新数据库 (名称) 。
create_database_if_not_exists	创建数据库（如果尚不存在）。 如果数据库已存在，则返回现有设置。 ..注意：此函数不会检查或更新现有数据库设置，如果它们与传入的数据库设置不同，则不会提供吞吐量。
delete_database	删除具有给定 ID (名称) 的数据库。
from_connection_string	从连接字符串创建 CosmosClient 实例。 可以从Azure 门户检索。有关可选关键字 (keyword) 参数的完整列表，请参阅 CosmosClient 构造函数。
get_database_account	检索数据库帐户信息。
get_database_client	检索 ID 为 (名称) ID 的现有数据库。
list_databases	列出 Cosmos DB SQL 数据库帐户中的数据库。
query_databases	查询 Cosmos DB SQL 数据库帐户中的数据库。

create_database

创建具有给定 ID 的新数据库 (名称) 。

create_database(id: str, populate_query_metrics: bool | None = None, offer_throughput: int | ThroughputProperties | None = None, **kwargs: Any) -> DatabaseProxy

参数

id

必需

ID (要创建的数据库的名称) 。

offer_throughput

必需

此套餐的预配吞吐量。

session_token

str

用于会话一致性的令牌。

initial_headers

dict[str,str]

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

etag

str

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

match_condition

MatchConditions

在 etag 上使用的匹配条件。

response_hook

Callable

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

返回

表示新数据库的 DatabaseProxy 实例。

返回类型

DatabaseProxy

例外

CosmosResourceExistsError

具有给定 ID 的数据库已存在。

示例

在 Cosmos DB 帐户中创建数据库：

   database_name = "testDatabase"
   try:
       database = client.create_database(id=database_name)
   except exceptions.CosmosResourceExistsError:
       database = client.get_database_client(database=database_name)

create_database_if_not_exists

创建数据库（如果尚不存在）。

如果数据库已存在，则返回现有设置。

..注意：此函数不会检查或更新现有数据库设置，如果它们与传入的数据库设置不同，则不会提供吞吐量。

create_database_if_not_exists(id: str, populate_query_metrics: bool | None = None, offer_throughput: int | ThroughputProperties | None = None, **kwargs: Any) -> DatabaseProxy

参数

id

必需

ID (要读取或创建的数据库的名称) 。

populate_query_metrics

bool

必需

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

offer_throughput

int 或 <xref:azure.cosmos.ThroughputProperties.>

必需

此套餐的预配吞吐量。

session_token

str

用于会话一致性的令牌。

initial_headers

dict[str,str]

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

etag

str

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

match_condition

MatchConditions

在 etag 上使用的匹配条件。

response_hook

Callable

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

返回

表示数据库的 DatabaseProxy 实例。

返回类型

DatabaseProxy

例外

CosmosHttpResponseError

数据库读取或创建失败。

delete_database

删除具有给定 ID (名称) 的数据库。

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

参数

database

str 或 dict(str, str) 或 DatabaseProxy

必需

ID (名称) ，表示要删除的数据库的属性或 DatabaseProxy 实例的 dict。

session_token

str

用于会话一致性的令牌。

initial_headers

dict[str,str]

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

etag

str

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

match_condition

MatchConditions

在 etag 上使用的匹配条件。

response_hook

Callable

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

返回类型

None

例外

CosmosHttpResponseError

如果无法删除数据库。

from_connection_string

从连接字符串创建 CosmosClient 实例。

可以从Azure 门户检索。有关可选关键字 (keyword) 参数的完整列表，请参阅 CosmosClient 构造函数。

from_connection_string(conn_str: str, credential: Any | None = None, consistency_level: str | None = None, **kwargs: Any) -> CosmosClient

参数

conn_str

str

必需

连接字符串。

credential

str 或 dict(str, str)

默认值: None

要使用的替代凭据，而不是连接字符串中提供的密钥。

consistency_level

Optional[str]

默认值: None

用于会话的一致性级别。 默认值为 None (帐户级别) 。

例外

CosmosResourceExistsError

具有给定 ID 的数据库已存在。

get_database_account

检索数据库帐户信息。

get_database_account(**kwargs: Any) -> DatabaseAccount

参数

response_hook

Callable

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

返回

表示 Cosmos DB 数据库帐户的 DatabaseAccount 实例。

返回类型

DatabaseAccount

例外

CosmosResourceExistsError

具有给定 ID 的数据库已存在。

get_database_client

检索 ID 为 (名称) ID 的现有数据库。

get_database_client(database: str | DatabaseProxy | Dict[str, Any]) -> DatabaseProxy

参数

database

str 或 dict(str, str) 或 DatabaseProxy

必需

ID (名称) ，表示要读取的数据库的属性或 DatabaseProxy 实例的 dict。

返回

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

返回类型

DatabaseProxy

例外

CosmosResourceExistsError

具有给定 ID 的数据库已存在。

list_databases

列出 Cosmos DB SQL 数据库帐户中的数据库。

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

参数

max_item_count

int

必需

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

session_token

str

用于会话一致性的令牌。

initial_headers

dict[str,str]

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

response_hook

Callable

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

返回

数据库属性的可迭代 (听写) 。

返回类型

Iterable[dict[str, str]]

例外

CosmosResourceExistsError

具有给定 ID 的数据库已存在。

query_databases

查询 Cosmos DB SQL 数据库帐户中的数据库。

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

参数

query

str

必需

要执行的 Azure Cosmos DB SQL 查询。

parameters

List[Dict[str, Any]]

必需

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

enable_cross_partition_query

bool

必需

在请求的路径上选择退出无法用作索引的查询的允许扫描。

max_item_count

int

必需

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

session_token

str

用于会话一致性的令牌。

initial_headers

dict[str,str]

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

response_hook

Callable

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

返回

数据库属性的迭代 (听写) 。

返回类型

Iterable[dict[str, str]]

例外

CosmosResourceExistsError

具有给定 ID 的数据库已存在。