Azure Cosmos DB JavaScript/TypeScript SDK(azure/cosmos),用于数据平面操作,包括文档CRUD、查询、批量操作和容器管理。技能概述azure-cosmos-ts 技能是Azure Cosmos DB NoSQL API的TypeScript/JavaScript客户端库,提供完整的数据平面操作支持。该SDK支持文档的CRUD操作、SQL查询、批量操作、存储过程调用等功能,适用于构建Node.js应用和前端应用。通过该技能,开发者可以利用TypeScript的类型安全特性,快速实现可靠的数据访问层。下载地址:antigravity-awesome-skills/skills/azure-cosmos-ts at main · sickn33/antigravity-awesome-skills · GitHub主要功能文档CRUD操作: 支持文档的创建、读取、更新、删除、Upsert和Patch操作SQL查询: 支持参数化查询、跨分区查询、分页和投影批量操作: 支持批量创建、更新、删除操作,提高吞吐量分区键管理: 支持单分区键和层级分区键(MultiHash)TypeScript类型: 提供完整的类型定义,确保类型安全AAD认证: 支持使用DefaultAzureCredential进行安全认证乐观并发: 支持使用ETag实现乐观并发控制存储过程: 支持调用和管理存储过程、触发器和UDF触发条件在以下情况下应该使用此技能:需要使用TypeScript/JavaScript开发Azure Cosmos DB应用需要实现文档的CRUD操作和查询功能需要使用批量操作提高吞吐量需要实现乐观并发控制需要使用存储过程和触发器需要构建类型安全的数据访问层使用场景Node.js API服务构建基于Express或NestJS的RESTful API,使用Cosmos DB作为数据存储,实现高性能的数据访问。前端应用在浏览器或React Native应用中直接访问Cosmos DB,实现无服务器的数据访问架构。Azure Functions在Azure Functions中访问Cosmos DB,构建无服务器的事件驱动应用。处理过程1. 客户端初始化创建Cosmos客户端并配置认证:import { CosmosClient } from azure/cosmos;import { DefaultAzureCredential } from azure/identity;const client new CosmosClient({endpoint: process.env.COSMOS_ENDPOINT!,aadCredentials: new DefaultAzureCredential(),});2. 数据库和容器设置创建或获取数据库和容器:const { database } await client.databases.createIfNotExists({id: my-database,});const { container } await database.containers.createIfNotExists({id: my-container,partitionKey: { paths: [/partitionKey] },});3. 文档CRUD操作执行文档的创建、读取、更新和删除:interface Product {id: string;partitionKey: string;name: string;price: number;}// 创建const { resource } await container.items.createProduct(item);// 读取const { resource } await container.item(product-1, electronics).readProduct();// 更新const { resource: updated } await container.item(product-1, electronics).replaceProduct(existing);// Upsertconst { resource } await container.items.upsertProduct(item);// 删除await container.item(product-1, electronics).delete();4. Patch操作执行部分更新:import { PatchOperation } from azure/cosmos;const operations: PatchOperation[] [{ op: replace, path: /price, value: 799.99 },{ op: add, path: /discount, value: true },{ op: remove, path: /oldField },];const { resource } await container.item(product-1, electronics).patchProduct(operations);输入要求使用此技能时,需要提供:Cosmos DB账户端点URL认证凭据(AAD或密钥)数据库名称和容器名称分区键路径TypeScript接口定义输出说明技能将提供:完整的客户端初始化代码TypeScript接口定义示例CRUD操作实现代码查询执行和分页代码批量操作示例错误处理和并发控制使用示例示例1: 参数化查询import { SqlQuerySpec } from azure/cosmos;const querySpec: SqlQuerySpec {query: SELECT * FROM c WHERE c.partitionKey category AND c.price maxPrice,parameters: [{ name: category, value: electronics },{ name: maxPrice, value: 1000 },],};const { resources } await container.items.queryProduct(querySpec).fetchAll();示例2: 批量操作import { BulkOperationType, OperationInput } from azure/cosmos;const operations: OperationInput[] [{operationType: BulkOperationType.Create,resourceBody: { id: 1, partitionKey: cat-a, name: Item 1 },},{operationType: BulkOperationType.Upsert,resourceBody: { id: 2, partitionKey: cat-a, name: Item 2 },},{operationType: BulkOperationType.Delete,id: 3,partitionKey: cat-b,},];const response await container.items.executeBulkOperations(operations);示例3: 乐观并发控制// 读取时获取ETagconst { resource, etag } await container.item(product-1, electronics).readProduct();if (resource etag) {resource.price 899.99;try {// 仅当ETag匹配时替换await container.item(product-1, electronics).replace(resource, {accessCondition: {type: IfMatch,condition: etag,},});} catch (error) {if (error instanceof ErrorResponse error.code 412) {console.log(Document was modified by another process);}}}最佳实践使用AAD认证: 优先使用DefaultAzureCredential而不是密钥始终使用参数化查询: 防止注入攻击并提高计划缓存效率指定分区键: 尽可能避免跨分区查询使用批量操作: 对于多次写入,使用executeBulkOperations处理429错误: 实现指数退避的重试逻辑使用ETag实现并发: 防止并发场景中的丢失更新关闭客户端: 在清理时调用client.dispose()资源层次结构CosmosClient└── Database└── Container├── Items (documents)├── Scripts (stored procedures, triggers, UDFs)└── Conflicts分区键管理层级分区键(MultiHash)支持最多3层分区键,实现更精细的数据分布:import { PartitionKeyDefinitionVersion, PartitionKeyKind } from azure/cosmos;const { container } await database.containers.createIfNotExists({id: orders,partitionKey: {paths: [/tenantId, /userId, /sessionId],version: PartitionKeyDefinitionVersion.V2,kind: PartitionKeyKind.MultiHash,},});// 操作需要分区键值数组const { resource } await container.item(order-1, [tenant-a, user-123, session-xyz]).read();错误处理import { ErrorResponse } from azure/cosmos;try {const { resource } await container.item(missing, pk).read();} catch (error) {if (error instanceof ErrorResponse) {switch (error.code) {case 404:console.log(Document not found);break;case 409:console.log(Conflict - document already exists);break;case 412:console.log(Precondition failed (ETag mismatch));break;case 429:console.log(Rate limited - retry after:, error.retryAfterInMs);break;default:console.error(Cosmos error ${error.code}: ${error.message});}}throw error;}服务层模式export class ProductService {private container: Container;constructor(client: CosmosClient) {this.container client.database(process.env.COSMOS_DATABASE!).container(process.env.COSMOS_CONTAINER!);}async getById(id: string, category: string): PromiseProduct | null {try {const { resource } await this.container.item(id, category).readProduct();return resource ?? null;} catch (error) {if (error instanceof ErrorResponse error.code 404) {return null;}throw error;}}async create(product: OmitProduct, id): PromiseProduct {const item { ...product, id: crypto.randomUUID() };const { resource } await this.container.items.createProduct(item);return resource!;}}安装和配置# 安装依赖npm install azure/cosmos azure/identity# 环境变量COSMOS_ENDPOINThttps://account.documents.azure.com:443/COSMOS_DATABASEdatabase-nameCOSMOS_CONTAINERcontainer-nameTypeScript类型参考import {// 客户端和资源CosmosClient,Database,Container,Item,Items,// 操作OperationInput,BulkOperationType,PatchOperation,// 查询SqlQuerySpec,SqlParameter,FeedOptions,// 分区键PartitionKeyDefinition,PartitionKeyDefinitionVersion,PartitionKeyKind,// 响应ItemResponse,FeedResponse,ResourceResponse,// 错误ErrorResponse,} from azure/cosmos;相关SDKSDK用途安装azure/cosmos数据平面(此SDK)npm install azure/cosmosazure/arm-cosmosdb管理平面(ARM)npm install azure/arm-cosmosdbazure/identity认证npm install azure/identity