Azure Cosmos DB TypeScript 技能
为 TypeScript 和 JavaScript 编码代理提供 Cosmos DB 数据操作模式。
文档推荐 Microsoft Entra 身份认证、区分数据面与管理面，并将密钥放入环境变量，降低了凭据暴露风险；但 CRUD、批量删除和容器创建示例没有用户确认、最小权限、数据流披露或回滚方案，连接字符串示例也未说明其敏感性，因此扣分。
主文档覆盖认证、CRUD、查询、分区键、错误处理和并发控制，异常状态码说明较清晰；但批量 API 在主文档使用 executeBulkOperations，而引用文档使用 bulk，版本和接口一致性无法由静态材料确认，也缺少针对该技能的可执行测试，因此按静态上限保守扣分。
触发词、TypeScript/JavaScript 受众以及数据面与管理面边界较明确，覆盖常见 Cosmos DB 场景；但未充分说明不适用场景、输入输出约束、权限前提和环境限制，也没有中文使用 guidance，因此扣分。
具有 YAML 元数据、安装说明、环境变量、分层主题、引用文档、最佳实践、相关 SDK、MIT 许可证和版本字段；但缺少 changelog、明确维护责任与更新流程、FAQ、已知限制及依赖版本锁定说明，因此扣分。
示例可直接作为 CRUD、查询、分页、批处理和 ETag 实现起点，且参数化查询和错误处理具有实际价值；但批量示例存在 API 不一致，部分代码依赖未定义的上下文（如 generateItems），并未证明结果可直接编译运行，因此扣分。
仓库材料提供通用 CI、评估工作流和测试 harness，具备一定审计线索；但提供的证据未显示该技能专属测试、验收标准或第三方执行结果，关键 SDK 声明仍主要依赖文档自身，故仅给有限静态证据分。
- 批量操作引用中的 container.items.bulk 与主文档的 executeBulkOperations 不一致；使用前应以锁定版本的官方 SDK 类型和 API 文档核对。
- 删除、批量写入、容器创建和跨分区查询可能产生不可逆数据或显著成本；文档未规定确认、权限、成本预览或恢复流程。
- 示例未系统说明 Cosmos endpoint、文档内容、查询结果和遥测数据的敏感性及日志脱敏要求。
- 未提供该技能专属验收测试或编译验证；不要将示例视为已验证的生产代码。
这个 Skill 能做什么，适合哪些场景？
该技能面向 Azure Cosmos DB NoSQL API 的数据平面操作，使用 @azure/cosmos SDK。它涵盖文档的创建、读取、替换、更新、删除和部分更新，以及参数化查询、分页、跨分区查询和批量操作。内容还包括 Microsoft Entra 身份验证、密钥身份验证、分区键、ETag 并发控制和错误处理。它不负责通过 ARM 创建或管理 Cosmos DB 账户、数据库和容器。
指导编码代理安装 @azure/cosmos 与 @azure/identity，配置 Cosmos endpoint、数据库、容器及认证环境变量；生成 CosmosClient、数据库和容器初始化代码；执行文档 CRUD、Patch、SQL 查询、分页查询、跨分区查询和批量操作；处理 404、409、412、429 等错误；使用简单或层次化分区键、ETag 条件更新，并在关闭时释放客户端。
- 为使用 Node.js 和 TypeScript 的后端开发者创建 Cosmos DB 文档服务层。
- 为需要参数化 NoSQL 查询和分页读取的应用生成查询代码。
- 为批量写入、读取、替换、删除或 Patch 文档的服务设计批量操作。
- 为使用 Microsoft Entra 身份验证或密钥身份验证的 Cosmos DB 应用配置客户端。
- 为多租户或多层级数据模型设计简单或层次化分区键，并避免不必要的跨分区查询。
这个 Skill 有哪些优点和局限？
- 覆盖从客户端初始化到 CRUD、查询、批量操作和并发控制的完整数据平面流程。
- 同时提供 Microsoft Entra、密钥和连接字符串认证示例。
- 包含参数化查询、分区键、429 错误和 ETag 等实际开发注意事项。
- 明确区分数据平面 SDK 与 ARM 管理平面 SDK。
- 仅针对 JavaScript/TypeScript 的 @azure/cosmos 数据平面操作，不覆盖 ARM 资源管理。
- 需要 Node.js 20 或更高版本及 Azure Cosmos DB 环境。
- 源材料未提供该单项技能的独立测试覆盖或运行验证结果。
- 示例依赖用户自行准备 Cosmos endpoint、数据库、容器和认证信息。
如何安装这个 Skill？
在 Copilot CLI 或兼容的技能安装流程中运行：npx skills add microsoft/skills，然后在向导中选择 azure-cosmos-ts。技能会安装到所选编码代理的目录，例如 GitHub Copilot 使用 .github/skills/。也可以从仓库中复制 .github/plugins/azure-sdk-typescript/skills/azure-cosmos-ts/ 目录；源材料未规定其他独立安装器。
如何使用这个 Skill？
让编码代理处理包含触发词的任务，例如：“使用 @azure/cosmos 和 TypeScript 为 Cosmos DB 实现带参数化查询、分区键和 429 重试处理的文档服务。”使用前配置 COSMOS_ENDPOINT、COSMOS_DATABASE 和 COSMOS_CONTAINER；采用密钥认证时配置 COSMOS_KEY，使用 DefaultAzureCredential 时按说明配置 AZURE_TOKEN_CREDENTIALS。源材料未提供独立的运行命令或测试命令。
这个 Skill 与同类方案有什么区别？
与 @azure/arm-cosmosdb 相比，本技能使用 @azure/cosmos 处理文档、查询和存储过程等数据平面操作；@azure/arm-cosmosdb 用于通过 ARM 创建账户、数据库和容器。@azure/identity 用于提供身份验证凭据，而不是执行 Cosmos DB 数据操作。