用于 API for NoSQL 的 Azure Cosmos DB Node.js SDK：发行说明和资源

项目
09/14/2024

适用范围： NoSQL

资源	链接
下载 SDK	@azure/cosmos
API 文档	JavaScript SDK 参考文档
SDK 安装说明	`npm install @azure/cosmos`
参与 SDK	azure-sdk-for-js 存储库供稿指南
示例	Node.js 代码示例
入门教程	JavaScript SDK 入门
Web 应用教程	使用 Azure Cosmos DB 创建 Node.js Web 应用程序
当前受支持的 Node.js 平台	LTS 版本的 Node.js

发行说明

版本历史记录保存在 azure-sdk-for-js 存储库中。有关版本的详细列表，请参阅 changelog 文件。

重大变更的迁移指南

如果使用旧版 SDK，建议迁移到 3.0 版本。本部分详细介绍了此版本的改进以及 3.0 版本中的 bug 修复。

改进了客户端构造函数选项

简化了构造函数选项：

masterKey 已重命名为 key 并移至顶层
之前在 options.auth 下的属性已移至顶层

// v2
const client = new CosmosClient({
    endpoint: "https://your-database.cosmos.azure.cn",
    auth: {
        masterKey: "your-primary-key"
    }
})

// v3
const client = new CosmosClient({
    endpoint: "https://your-database.cosmos.azure.cn",
    key: "your-primary-key"
})

简化了查询迭代器 API

在 v2 中，可以通过多种不同的方法来迭代或检索查询中的结果。我们已尝试简化 v3 API 并删除类似或重复的 API：

删除 iterator.next() 和 iterator.current()。使用 fetchNext() 获取结果页。
删除 iterator.forEach()。改用异步迭代器。
iterator.executeNext() 已重命名为 iterator.fetchNext()
iterator.toArray() 已重命名为 iterator.fetchAll()
页面现在是正确的响应对象，而不是纯 JS 对象
const 容器 = client.database(dbId).container(containerId)

// v2
container.items.query('SELECT * from c').toArray()
container.items.query('SELECT * from c').executeNext()
container.items.query('SELECT * from c').forEach(({ body: item }) => { console.log(item.id) })

// v3
container.items.query('SELECT * from c').fetchAll()
container.items.query('SELECT * from c').fetchNext()
for await(const { result: item } in client.databases.readAll().getAsyncIterator()) {
    console.log(item.id)
}

固定容器现已分区

Azure Cosmos DB 服务现支持所有容器上的分区键，包括以前创建为固定容器的分区键。 v3 SDK 更新到了实现此变更的最新 API 版本，但它不是中断性变更。如果没有为操作提供分区键，则默认使用适用于所有现有容器和文档的系统键。

为存储过程删除了 upsert

以前允许将 upsert 用于非分区集合，但通过 API 版本更新，所有集合均已分区，因此我们将其完全删除。

项读取不会引发 404 错误

const 容器 = client.database(dbId).container(containerId)

// v2
try {
    container.items.read(id, undefined)
} catch (e) {
    if (e.code === 404) { console.log('item not found') }
}

// v3
const { result: item }  = container.items.read(id, undefined)
if (item === undefined) { console.log('item not found') }

默认多区域写入

如果 Azure Cosmos DB 配置支持，SDK 现将默认写入多个区域。这在以前是选择行为。

相应的错误对象

失败请求现会引发相应的错误或错误子类。以前，它们会引发纯 JS 对象。

新增功能

用户可取消请求

通过在内部进行提取，可以使用浏览器 AbortController API 来支持用户可取消操作。对于可能正在进行多个请求的操作（如跨分区查询），该操作的所有请求都将被取消。新式浏览器用户将拥有 AbortController。 Node.js 用户需要使用填充代码库

 const controller = new AbortController()
 const {result: item} = await items.query('SELECT * from c', { abortSignal: controller.signal});
 controller.abort()

在 db/容器创建操作过程中设置吞吐量

const { database }  = client.databases.create({ id: 'my-database', throughput: 10000 })
database.containers.create({ id: 'my-container', throughput: 10000 })

@azure/cosmos-sign

标头令牌生成已拆分为新库 @azure/cosmos-sign。任何直接调用 Azure Cosmos DB REST API 的用户都可以使用它并通过我们在 @azure/cosmos 内调用的相同代码对标头进行签名。

生成 ID 的 UUID

v2 具有生成项 ID 的自定义代码。我们已切换到众所周知的、受维护的社区库 UUID。

连接字符串

现在可以传递从 Azure 门户复制的连接字符串：

const client = new CosmosClient("AccountEndpoint=https://test-account.documents.azure.cn:443/;AccountKey=c213asdasdefgdfgrtweaYPpgoeCsHbpRTHhxuMsTaw==;")
Add DISTINCT and LIMIT/OFFSET queries (#306)
 const { results } = await items.query('SELECT DISTINCT VALUE r.name FROM ROOT').fetchAll()
 const { results } = await items.query('SELECT * FROM root r OFFSET 1 LIMIT 2').fetchAll()

改进了浏览器体验

尽管可以在浏览器中使用 v2 SDK，但这并不是理想体验。需要对几个 Node.js 内置库填充代码，并使用 Webpack 或 Parcel 之类的捆绑程序。 v3 SDK 为浏览器用户提供了更好的全新体验。

将内部请求替换为 fetch (#245)
不使用缓冲区 (#330)
不使用节点 builtin，以支持通用包/API (#328)
切换到节点中止控制器 (#294)

Bug 修复

修复了产品/服务读取并返回产品/服务测试 (#224)
修复了 EnableEndpointDiscovery (#207)
修复了分页结果上缺少的 RU (#360)
展开 SQL 查询参数类型 (#346)
向 ItemDefinition 添加 ttl (#341)
修复了 CP 查询指标 (#311)
将 activityId 添加到 FeedResponse (#293)
将 _ts 类型从字符串转换为数字 (#252)(#295)
修复了请求费用聚合 (#289)
允许空字符串分区键 (#277)
将字符串添加到冲突查询类型 (#237)
将 uniqueKeyPolicy 添加到容器 (#234)

工程系统

虽然这些更改不总是那么明显，但可以帮助我们的团队更快地交付更出色的代码。

为生产版本使用汇总 (#104)
更新到 TypeScript 3.5 (#327)
转换为 TS 项目引用。提取测试文件夹 (#270)
启用 noUnusedLocals 和 noUnusedParameters (#275)
用于 CI 的 Azure Pipelines YAML 版本 (#298)

发布和停用日期

Microsoft 至少会在停用 SDK 前提前 12 个月发出通知，以便顺利转换为更高版本/受支持版本。新特性和功能以及优化仅添加到当前 SDK，因此建议你始终尽早升级到最新的 SDK 版本。有关更多详细信息，请阅读 Microsoft SDK 支持策略。

版本	发布日期	停用日期
v3	2019 年 6 月 28 日	---
v2	2018 年 9 月 24 日	2021 年 9 月 24 日
v1	2015 年 4 月 8 日	2020 年 8 月 30 日

常见问题解答

如何收到即将停用的 SDK 的通知？

Azure 会在即将停用的 SDK 的支持结束之前提前 12 个月进行通知，以便协助平稳地转换到支持的 SDK。我们会通过以下通信通道通知你：Azure 门户、Azure 更新以及与分配的服务管理员的直接通信。

在这 12 个月期间，我是否可以使用即将停用的 Azure Cosmos DB SDK 来创作应用程序？

可以，你可以在 12 个月的宽限期内使用即将停用的 Azure Cosmos DB SDK 创作、部署和修改应用程序。建议在 12 个月的宽限期内根据相应情况迁移到支持的较新版本 Azure Cosmos DB SDK。

停用日期之后，使用不受支持的 Azure Cosmos DB SDK 的应用程序会发生什么情况？

停用日期之后，Azure Cosmos DB 将不再进行 bug 修复、添加新功能或为已停用的 SDK 版本提供支持。如果不想升级，从已停用的 SDK 版本发送的请求将继续由 Azure Cosmos DB 服务提供服务。

哪些 SDK 版本将包含最新功能和更新？

新功能和更新将仅添加到最新的受支持的主要 SDK 版本的最新次要版本。建议始终使用最新版本，以充分利用新功能、性能改进和 bug 修补程序。如果使用的是未停用的旧版本 SDK，则对 Azure Cosmos DB 进行的请求仍然有效，但是你无法访问任何新功能。

如果无法在截止日期之前更新应用程序，该怎么办？

我们建议尽早升级到最新 SDK。 SDK 标记为要停用之后，你将有 12 个月的时间来更新应用程序。如果无法在停用日期之前更新，从已停用的 SDK 版本发送的请求将继续由 Azure Cosmos DB 提供服务，因此正在运行的应用程序将继续运行。但 Azure Cosmos DB 将不再进行 bug 修复、添加新功能或为已停用的 SDK 版本提供支持。

如果你有支持计划并需要技术支持，请创建支持工单以联系我们。

如何请求将功能添加到 SDK 或连接器？

新功能并不总是立即添加到每个 SDK 或连接器中。如果你想添加的功能不受支持，请在我们的社区论坛提出反馈。

另请参阅

若要详细了解 Azure Cosmos DB，请参阅 Azure Cosmos DB 服务页。

通过