用途
本技能面向使用 Python 操作 Azure Cosmos DB NoSQL API 的场景。Azure Cosmos DB 是全局分布式、多模型数据库，本技能提供其 Python 客户端库（azure-cosmos）的使用方法，用于文档 CRUD、查询、容器管理以及全局分布式数据访问。
主要能力
- 客户端层级：CosmosClient（账户级操作）、DatabaseProxy（数据库操作）、ContainerProxy（容器与项操作）。
- 数据库与容器管理：创建或获取数据库、创建或获取容器，支持分区键与预配吞吐量。
- 文档操作：创建、读取、替换更新、Upsert、删除。
- 查询：分区内查询、跨分区查询、带投影的查询、读取全部项。
- 分区键：单分区键与分层分区键（预览）。
- 吞吐量：创建时指定、读取当前值、更新吞吐量（RU/s）。
- 异步客户端：azure.cosmos.aio 与 azure.identity.aio。
- 错误处理：捕获 CosmosHttpResponseError，处理 404 与 429 等状态码。
使用方式
安装：
pip install azure-cosmos azure-identity
环境变量：
COSMOS_ENDPOINT=https://<account>.documents.azure.com:443/ COSMOS_DATABASE=mydb COSMOS_CONTAINER=mycontainer
身份验证示例：
from azure.identity import DefaultAzureCredential from azure.cosmos import CosmosClient
credential = DefaultAzureCredential() endpoint = "https://<account>.documents.azure.com:443/"
client = CosmosClient(url=endpoint, credential=credential)
核心工作流包括：创建或获取数据库与容器、创建项、读取项（需 id 与分区键）、替换更新、Upsert、删除、查询（分区内与跨分区）、读取全部项、配置分区键与吞吐量、使用异步客户端、错误处理。
适用场景
- 需要在 Python 中操作 Azure Cosmos DB NoSQL API 的文档数据。
- 需要设计分区键、管理容器与吞吐量的场景。
- 需要同步或异步高吞吐访问的场景。
- 需要处理 Cosmos DB 特定错误（如 404、429）的场景。
限制
- 仅在任务明确匹配上述范围时使用本技能。
- 不得将输出视为环境特定验证、测试或专家审查的替代。
- 若缺少必要输入、权限、安全边界或成功标准，应停止并请求澄清。
- 支持材料可用性：以下路径在当前目录副本中不可用：<support-root>/scripts/setup_cosmos_container.py。不要调用需要该文件的步骤。如需使用，请获取原始材料并审查其依赖、许可与影响后再使用。独立的内联步骤与已捆绑的辅助文件可在用户授权范围内继续。
- 参考文件包括 references/partitioning.md（分区键策略、分层键、热分区检测与缓解）与 references/query-patterns.md（查询优化、聚合、分页、事务、变更源）。
最佳实践
- 点读取与查询始终指定分区键。
- 使用参数化查询以防止注入并提升缓存。
- 尽可能避免跨分区查询。
- 使用 upsert_item 实现幂等写入。
- 高吞吐场景使用异步客户端。
- 设计分区键以实现数据均匀分布。
- 单文档检索使用 read_item 而非查询。