适用于 NoSQL 的 Azure Cosmos DB 中Python SDK 的最佳做法

本指南包含使用最新版本的 Python SDK for Azure Cosmos DB for NoSQL 构建的解决方案的最佳做法。 此处附带的最佳做法有助于提高延迟、提高可用性，并提高解决方案的整体性能。

帐户配置

帐户配置参数

参数	默认或约束	何时使用
区域共置	与应用区域相同	降低延迟
多区域复制	默认已禁用	为可用性启用 2 个以上的区域
服务托管故障转移	可选	为生产工作负载启用

from azure.cosmos import CosmosClient
client = CosmosClient(url, credential)
print(client.client_connection._global_endpoint_manager.write_endpoint)
# Expected: write endpoint resolves to configured write region

有关如何使用 Python SDK 添加多个区域的详细信息，请参阅 global 分发教程。

SDK 用法

SDK 用法参数

参数	默认或约束	何时使用
SDK 版本	最新可用	始终实现最佳性能
CosmosClient 实例	每个应用一个	在应用的生命周期内复用
首选位置	None	优化读取和故障转移

client = CosmosClient(
    url,
    credential,
    preferred_locations=["East US", "West US"]
)
print(client.client_connection._preferred_locations)
# Expected: ['East US', 'West US']

暂时性错误是指根本原因很快就能自行解决的错误。 连接到你的数据库的应用程序应当构建为能预见这些暂时性错误。 为了处理这些错误，可在代码中实现重试逻辑，而不是将它们以应用程序错误的形式呈现给用户。 SDK 提供内置逻辑来处理可重试请求（如读取或查询操作）的这些暂时性故障。 由于写入操作不是幂等的，因此 SDK 无法针对暂时性故障重试写入。 SDK 允许用户为限制配置重试逻辑。 有关要重试的错误的详细信息，请参阅 可复原的应用程序指南。

使用 SDK 日志记录 捕获诊断信息 并排查延迟问题。

异步客户端

异步客户端要求

要求	默认或约束	何时使用
导入路径	azure.cosmos.aio.CosmosClient	在异步框架和事件循环中使用
aiohttp 依赖	默认情况下未安装	显式安装： pip install aiohttp
客户端生命周期	必须显式关闭	使用 async with 或调用 await client.close()

from azure.cosmos.aio import CosmosClient

# Preferred: use async with to manage lifecycle automatically
async with CosmosClient(url, credential) as client:
    database = client.get_database_client("mydb")
    container = database.get_container_client("mycontainer")
    item = await container.read_item(item="id1", partition_key="pk1")

# Alternative: manage lifecycle manually
client = CosmosClient(url, credential)
try:
    database = client.get_database_client("mydb")
    container = database.get_container_client("mycontainer")
    item = await container.read_item(item="id1", partition_key="pk1")
finally:
    await client.close()

何时使用异步与同步

情景	建议的客户端
Web 框架 （FastAPI， Quart）	azure.cosmos.aio.CosmosClient
无服务器（Azure Functions异步）	azure.cosmos.aio.CosmosClient
脚本和批处理作业	azure.cosmos.CosmosClient
简单 CLI 工具	azure.cosmos.CosmosClient

警告

请勿在异步事件循环中使用同步 CosmosClient 。 同步客户端进行阻塞 I/O 调用，这些调用会阻塞事件循环，从而降低性能，并可能导致应用程序中出现死锁。

有关详细信息，请参阅 Python SDK 自述文件异步部分。

数据设计

数据设计参数

参数	默认或约束	何时使用
文档大小	N/A	保持小规模以降低 RU 成本
标识符字符	无特殊字符	避免意外行为
索引路径	索引的所有路径	排除未使用的路径以加快写入速度

container_properties = {
    "id": "items",
    "indexingPolicy": {
        "excludedPaths": [{"path": "/*"}]
    }
}
print(container_properties["indexingPolicy"])
# Expected: excludedPaths configured

有关详细信息，请参阅 使用 SDK 示例创建索引。

主机特征

主机特征参数

参数	默认或约束	何时使用
CPU 使用率	<建议使用 70%	如果负载较高，则纵向扩展或横向扩展
加速网络	Disabled	在虚拟机上启用以支持高流量
查询页面大小	100 个项目/4 MB	增加以减少往返次数

items = container.query_items(
    query="SELECT * FROM c",
    max_item_count=500
)
print("Page size set to 500")
# Expected: fewer round trips

后续步骤

若要详细了解 Python SDK 的性能提示，请参阅 Azure Cosmos DB Python SDK 的性能提示。

若要详细了解如何设计应用程序以实现缩放和高性能，请参阅 Azure Cosmos DB 中的分区和缩放。

尝试对迁移到 Azure Cosmos DB 进行容量规划？ 可以使用有关现有数据库群集的信息进行容量规划。

• 如果你只知道现有数据库群集中的 vCore 和服务器数量，请阅读根据 vCore 或 vCPU 数量估算请求单位数
• 如果知道当前数据库工作负荷的典型请求速率，请阅读有关使用Azure Cosmos DB容量规划器来估计请求单位