Azure Cosmos DB for NoSQL 中的 Python SDK 最佳做法

  • 适用于: ✅ NoSQL

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

帐户配置

帐户配置参数

参数 默认或约束 何时使用
区域共置 与应用区域相同 降低延迟
多区域复制 默认已禁用 为可用性启用 2 个以上的区域
服务托管故障转移 Optional 为生产工作负载启用 
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 添加多个区域的详细信息，请参阅 全局分发教程。

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

何时使用异步与同步

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

Warning

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

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

数据设计

数据设计参数

参数 默认或约束 何时使用
文档大小 不适用 保持小规模以降低 RU 成本
标识符字符 无特殊字符 避免意外行为
索引路径 索引的所有路径 排除未使用的路径以加快写入速度 
container_properties = {
    "id": "items",
    "indexingPolicy": {
        "excludedPaths": [{"path": "/*"}]
    }
}
print(container_properties["indexingPolicy"])
# Expected: excludedPaths configured

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

主机特征

主机特征参数

参数 默认或约束 何时使用
CPU 使用率 <建议使用 70% 如果负载较高，则纵向扩展或横向扩展
网络加速技术 已禁用 在虚拟机上启用以支持高流量
查询页面大小 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 容量规划工具来估计请求单位的文章
  • Last updated on