Azure Cosmos DB Python 技能
帮助 Python 开发者可靠地构建和操作 Azure Cosmos DB NoSQL 应用。
文档优先推荐 DefaultAzureCredential、避免密钥，并强调参数化查询和客户端资源释放，体现了部分最小权限与数据流安全意识；但创建、替换、删除、吞吐量调整等外部副作用没有用户确认、回滚或恢复说明，也未覆盖敏感数据处理、依赖安全和完整来源归因，因此扣分。
涵盖同步/异步生命周期、常见错误状态和重试提示，快乐路径基本连贯；但核心示例缺少 PartitionKey 导入，若干高级示例存在并发、API 兼容性或边界处理不充分的问题，且没有针对该技能的测试复现证据，静态评估不超过10分。
触发词、Python SDK、CRUD、查询、分区键等适用场景较清楚，也说明了部分高成本跨分区查询的非优选情形；但输入前提、非适用边界、版本兼容范围和失败时的选择条件不完整，文档仅英文，未提供中文支持或中国大陆网络可达性说明，因此扣分。
结构包含安装、环境变量、认证、工作流、引用文档和脚本入口，带有 MIT 许可证、作者和1.0.0版本信息；但缺少技能专属变更日志、明确维护责任/更新流程、FAQ和系统化故障排查，且引用文件与脚本未在本次材料中提供，故未满分。
内容覆盖 CRUD、查询、分页、聚合、事务、变更源和分区设计，能为常见 Cosmos DB 编码任务提供直接参考；但示例不是完整可运行项目，存在缺少导入、环境/权限/服务前提和部分实现风险，输出仍需较多人工核验，静态上限为7分。
技能文件、仓库 README、许可证、安全政策和 CI 文件提供了可审计的一手材料，且仓库声明存在评估与测试流程；但没有该技能路径对应的提交测试、真实执行结果或多源交叉验证，静态上限为5分。
- 执行写入、删除、吞吐量调整或事务示例前，应由用户确认目标账户、数据库、容器、权限和恢复方案。
- 核心建库示例缺少 PartitionKey 导入；不要直接假定所有高级示例与当前 azure-cosmos 版本兼容。
- 应补充 SDK 版本约束、技能专属测试、失败排查、敏感数据处理和中文/中国大陆网络可达性说明。
它能做什么 & 适用场景
该技能面向 Azure Cosmos DB NoSQL API，覆盖客户端生命周期、数据库与容器管理、文档 CRUD、查询、分区键和吞吐量配置。它同时提供同步与异步 Python 客户端示例，并推荐使用 DefaultAzureCredential 进行身份验证。内容强调为客户端和异步凭据使用上下文管理器，以及在操作中明确指定分区键。适合需要将 Cosmos DB 集成到 Python 服务或脚本中的开发者。
提供 azure-cosmos 和 azure-identity 的安装命令；说明 COSMOS_ENDPOINT、COSMOS_DATABASE、COSMOS_CONTAINER 和生产环境 AZURE_TOKEN_CREDENTIALS 的配置；展示 CosmosClient、DatabaseProxy 和 ContainerProxy 的使用；演示数据库及容器创建、文档创建、读取、替换、upsert、删除、参数化查询、跨分区查询、投影查询、吞吐量读取与更新；提供同步、异步和 CosmosHttpResponseError 错误处理示例。
- Python 开发者需要创建或获取 Cosmos DB 数据库和带分区键的容器时。
- 后端开发者需要对 Cosmos DB 文档执行创建、点读取、替换、upsert 和删除时。
- 数据服务开发者需要编写带参数的分区内查询或谨慎执行跨分区查询时。
- 高吞吐 Python 应用需要使用异步 CosmosClient 和异步 DefaultAzureCredential 时。
- 运维或应用开发者需要读取和调整容器的预配吞吐量时。
优缺点一览
- 覆盖同步和异步客户端，并给出完整的常见文档操作示例。
- 明确强调 DefaultAzureCredential、上下文管理器和参数化查询等实践。
- 涵盖分区键、跨分区查询、吞吐量和 404/429 错误处理等实际问题。
- 附带分区、查询模式参考文件和容器设置脚本的索引。
- 内容只针对 Python 的 Azure Cosmos DB NoSQL API，不覆盖其他语言或 API 模型。
- 跨分区查询被标为更昂贵且应谨慎使用，但未提供具体成本或性能基准。
- 源材料没有展示该单个技能的专属测试结果或测试场景。
- 异步示例依赖 azure.identity.aio，并要求异步客户端和凭据分别使用上下文管理器。
如何安装
运行 pip install azure-cosmos azure-identity。若要安装该 Agent Skill 集合，运行 npx skills add microsoft/skills，然后在向导中选择需要的技能；集合会安装到所选 Agent 的目录，例如 .github/skills/。源材料未说明单独安装 azure-cosmos-py 的专用命令。
如何使用
在支持 Agent Skills 的编码代理中提出类似“请使用 azure-cosmos 和 azure-identity，为 Cosmos DB NoSQL 容器实现带 partition key 的文档 CRUD 和参数化查询”的请求。使用前配置 COSMOS_ENDPOINT、COSMOS_DATABASE 和 COSMOS_CONTAINER；若使用生产环境的 DefaultAzureCredential，再配置 AZURE_TOKEN_CREDENTIALS=prod 或指定凭据。
对比同类
与连接字符串、账户密钥或 API 密钥认证相比，该技能优先推荐 DefaultAzureCredential，以便在本地开发和 Azure 环境之间复用代码，并避免绕过 Entra 审计与轮换流程。