适用于 SQL API 的 Azure Cosmos DB Node.js SDK:发行说明和资源

适用于: SQL API

资源 链接
下载 SDK NPM
API 文档 JavaScript SDK 参考文档
SDK 安装说明 安装说明
参与 SDK GitHub
示例 Node.js 代码示例
入门教程 JavaScript SDK 入门
Web 应用教程 使用 Azure Cosmos DB 创建 Node.js Web 应用程序
当前受支持的平台 Node.js v12. x - SDK 版本 3.x.x
Node.js v10.x - SDK 版本 3.x.x
Node.js v8.x - SDK 版本 3.x.x
Node.js v6.x - SDK 版本 2.x.x
Node.js v4.2.0 - SDK 版本 1.x.x
Node.js v0.12 - SDK 版本 1.x.x
Node.js v0.10 - SDK 版本 1.x.x

发行说明

3.1.0

  • 将默认 ResponseContinuationTokenLimitInKB 设置为 1kb。 默认情况下,我们会将此项限制为 1kb,以避免长标头(Node.js 具有多区域标头大小限制)。 用户可以设置此字段以允许使用更长的标头,这有助于后端优化查询执行。
  • 删除 disableSSLVerification。 此选项具有 #388 中所述的新替代方法

3.0.4

  • 允许 initialHeaders 显式设置分区键标头
  • 使用包 .json# 文件来阻止发布外来文件
  • 修复了旧版本 node+v8 上的路由映射排序错误
  • 修复了用户提供部分重试选项时遇到的 bug

3.0.3

  • 阻止 webpack 解析要求调用的模块

3.0.2

  • 修复了在聚合查询中 RU 总是被报告为 0 的长期未解决的 bug

3.0.0

🎉 v3 版本! 🎉 诸多新功能、bug 修复和一些重大变更。 此版本的主要目标:

  • 实现主要新功能
    • DISTINCT 查询
    • LIMIT/OFFSET 查询
    • 用户可取消请求
  • 更新到最新的 Cosmos REST API 版本,其中所有容器都可以无限缩放
  • 更轻松地在浏览器中使用 Cosmos
  • 更好地适应新的 Azure JS SDK 准则

重大变更的迁移指南

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

简化了构造函数选项:

  • 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"
})
简化了 QueryIterator 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)
}
固定容器现已分区

Cosmos 服务现支持所有容器上的分区键,包括以前创建为固定容器的分区键。 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') }
默认多区域写入

如果 Cosmos 配置支持,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。 任何直接调用 Cosmos 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)

2.1.5

  • 无需更改代码。 修复了在 2.1.4 包中包含一些额外文件的问题。

2.1.4

  • 修复了重试策略内的区域故障转移
  • 修复了 ChangeFeed hasMoreResults 属性
  • 开发依赖项更新
  • 添加了 PolicheckExclusions.txt

2.1.3

  • 将 _ts 类型从字符串转换为数字
  • 修复了默认索引测试
  • 将 uniqueKeyPolicy 向后移植到 v2
  • 演示和演示调试修补程序

2.1.2

  • 向后移植 v3 分支中的产品/服务修补程序
  • 修复了 executeNext() 类型签名中的 bug
  • 拼写错误修复

2.1.1

  • 版本重构。 允许在生成时拉取 SDK 版本。

2.1.0

新功能

  • 添加了 ChangeFeed 支持 (#196)
  • 添加了用于索引的 MultiPolygon 数据类型 (#191)
  • 向构造函数添加“key”属性作为 masterKey 的别名 (#202)

修复项

  • 修复了 next() 在迭代器上返回错误值的 bug

工程改进

  • 添加了对 typescript 使用的集成测试 (#199)
  • 启用直接从 GitHub 安装 (#194)

2.0.5

  • 添加节点代理类型的接口。 Typescript 用户不再需要安装 @types/node 作为依赖项
  • 现在将正确地采用首选位置
  • 对参与开发人员文档的改进
  • 各种拼写错误修复

2.0.4

  • 修复了 2.0.3 中引入的类型定义问题

2.0.3

  • 删除了 big-integer 依赖项
  • 切换到 AsyncIterable 类型的引用指令。 Typescript 用户不再需要自定义其“lib”设置。
  • 拼写错误修复

2.0.2

  • 修复了自述文件链接

2.0.1

  • 修复了重试接口实现

2.0.0

  • JavaScript SDK 版本 2.0.0 正式发布
  • 添加了对多区域写入的支持。

2.0.0-3

  • RC1 版本 2.0.0 的 JavaScript SDK(公共预览版)。

  • 新对象模型,使用顶级 CosmosClient 和方法拆分成相关的数据库、容器和项类。

  • 支持承诺

  • 转换为 TypeScript 的 SDK。

1.14.4

  • npm 文档已修复。

1.14.3

  • 添加了对连接问题的默认重试的支持。
  • 添加了对读取集合更改源的支持。
  • 修复了间歇性导致“读取会话不可用”的会话一致性 bug。
  • 添加了对查询指标的支持。
  • 修改了 http 代理的最大连接数。

1.14.2

  • 将文档更新为了引用 Azure Cosmos DB 而非 Azure DocumentDB。
  • 在 ConnectionPolicy 中增加了对 proxyUrl 设置的支持。

1.14.1

  • 微调了区分大小写的文件系统。

1.14.0

1.13.0

  • 防拆分跨分区查询。
  • 添加对带有前导和尾随斜杠(和对应测试)的资源链接的支持。

1.12.2

  • npm 文档已修复。

1.12.1

  • 修复了 executeStoredProcedure 中的一个 bug,其中涉及的文档具有特殊 Unicode 字符(LS、PS)。
  • 修复了在分区键中处理含 Unicode 字符的文档时的 bug。
  • 修复使用名称媒体创建集合的支持。 GitHub 问题 #114。
  • 修复了权限授权令牌的支持。 GitHub 问题 #178。

1.12.0

  • 添加了对称为“ConsistentPrefix”的新一致性级别的支持。
  • 添加了对 UriFactory 的支持。
  • 修复了 Unicode 支持 bug。 GitHub 问题 #171。

1.11.0

  • 添加了对聚合查询(COUNT、MIN、MAX、SUM、AVG)的支持。
  • 现可控制跨分区查询的并行度。
  • Azure Cosmos DB 模拟器运行时,添加了禁用 TLS 验证的选项。
  • 将分区集合上的最小吞吐量从 10,100 RU/s 降低到 2500 RU/s。
  • 修复了针对单分区集合的继续标记 bug。 GitHub 问题 #107。
  • 修复了将 0 处理成单个参数时出现的 executeStoredProcedure bug。 GitHub 问题 #155。

1.10.2

  • 修复了 user-agent 标头,使之包括 SDK 版本。
  • 细微代码清理。

1.10.1

  • 使用 SDK 定位模拟器 (hostname=localhost) 时禁用 TLS 验证。
  • 添加了在存储过程执行期间对启用脚本日志记录的支持。

1.10.0

  • 添加了对跨分区并行查询的支持。
  • 添加了对分区集合的 TOP/ORDER BY 查询支持。

1.9.0

  • 添加了对限制请求的重试策略支持。 (限制请求收到请求速率太大的异常,错误代码 429。)默认情况下,出现错误代码 429 时,Azure Cosmos DB 将针对每个请求重试九次,具体取决于响应标头中的 retryAfter 时间。 如果想要忽略重试之间由服务器返回的 retryAfter 时间,现在可以对 ConnectionPolicy 对象设置固定的重试间隔时间,并将其作为 RetryOptions 属性的一部分。 Azure Cosmos DB 现在对每个要中止的请求等待最多 30 秒(不考虑重试次数),并返回对错误代码 429 作出的响应。 还可以在 ConnectionPolicy 对象的 RetryOptions 属性中替代该时间。
  • Cosmos DB 现在将 x-ms-throttle-retry-count 和 x-ms-throttle-retry-wait-time-ms 作为每个请求的响应标头返回,以表示限制重试计数和重试之间请求所等待的累计时间。
  • 已添加 RetryOptions 类,从而公开了 ConnectionPolicy 类上可用于替代某些默认重试选项的 RetryOptions 属性。

1.8.0

  • 添加了对多区域数据库帐户的支持。

1.7.0

  • 添加了对文档生存时间 (TTL) 功能的支持。

1.6.0

1.5.6

  • 修复了 RangePartitionResolver.resolveForRead Bug,其会由于结果的错误 concat,它不返回链接。

1.5.5

  • 修复了 hashPartitionResolver resolveForRead():当没有提供分区键时抛出异常,而不是返回所有已注册链接的列表。

1.5.4

  • 修复了问题 #100 - 专用 HTTPS 代理:避免因 Azure Cosmos DB 用途而修改多区域代理。 对所有 lib 的请求均使用专用代理。

1.5.3

  • 修复了问题 #81 - 正确处理媒体 ID 中的短划线。

1.5.2

  • 修复了问题 #95 - EventEmitter 侦听器泄漏警告。

1.5.1

  • 修复了问题 #92 - 对区分大小写的系统,将文件夹 Hash 重命名为 hash。

1.5.0

  • 通过添加哈希和范围分区解析程序来实现分片支持。

1.4.0

  • 实现 Upsert。 DocumentClient 上的新 upsertXXX 方法。

1.3.0

  • 跳过以使版本号与其他 SDK 相符。

1.2.2

  • 将 Q 承诺包装拆分到新的存储库。
  • 更新到 npm 注册表的程序包文件。

1.2.1

  • 实现基于 ID 的路由。
  • 修复了问题 #49 - 当前属性与方法 current() 发生冲突。

1.2.0

  • 添加对地理空间索引的支持。
  • 验证所有资源的 ID 属性。 资源的 ID 不能包含 ?、/、#、//、字符或以空格结尾。
  • 将新标头“索引转换进度”添加到 ResourceResponse。

1.1.0

  • 实现 V2 索引策略。

1.0.3

  • 问题 #40 - 已在核心和承诺 SDK 中实现 eslint 和 grunt 配置。

1.0.2

  • 问题 #45 - 承诺包装器不包括错误的标头。

1.0.1

  • 通过添加 readConflicts、readConflictAsync 和 queryConflicts 实现了查询冲突的功能。
  • 更新了 API 文档。
  • 问题 #41 - client.createDocumentAsync 错误。

1.0.0

  • GA SDK。

发布和停用日期

Azure 会在停用 SDK 时至少提前 12 个月发出通知,以便用户顺利转换为更高版本/受支持版本。 新特性和功能以及优化仅添加到当前 SDK,因此建议始终尽早升级到最新的 SDK 版本。

版本 发布日期 停用日期
3.1.0 2019 年 7 月 26 日 ---
3.0.4 2019 年 7 月 22 日 ---
3.0.3 2019 年 7 月 17 日 ---
3.0.2 2019 年 7 月 9 日 ---
3.0.0 2019 年 6 月 28 日 ---
2.1.5 2019 年 3 月 20 日 ---
2.1.4 2019 年 3 月 15 日 ---
2.1.3 2019 年 3 月 8 日 ---
2.1.2 2019 年 1 月 28 日 ---
2.1.1 2018 年 12 月 5 日 ---
2.1.0 2018 年 12 月 4 日 ---
2.0.5 2018 年 11 月 7 日 ---
2.0.4 2018 年 10 月 30 日 ---
2.0.3 2018 年 10 月 30 日 ---
2.0.2 2018 年 10 月 10 日 ---
2.0.1 2018 年 9 月 25 日 ---
2.0.0 2018 年 9 月 24 日 ---
2.0.0-3 (RC) 2018 年 8 月 2 号 ---
1.14.4 2018 年 5 月 3 日 2020 年 8 月 30 日
1.14.3 2018 年 5 月 3 日 2020 年 8 月 30 日
1.14.2 2017 年 12 月 21 日 2020 年 8 月 30 日
1.14.1 2017 年 11 月 10 日 2020 年 8 月 30 日
1.14.0 2017 年 11 月 9 日 2020 年 8 月 30 日
1.13.0 2017 年 10 月 11 日 2020 年 8 月 30 日
1.12.2 2017 年 8 月 10 日 2020 年 8 月 30 日
1.12.1 2017 年 8 月 10 日 2020 年 8 月 30 日
1.12.0 2017 年 5 月 10 日 2020 年 8 月 30 日
1.11.0 2017 年 3 月 16 日 2020 年 8 月 30 日
1.10.2 2017 年 1 月 27 日 2020 年 8 月 30 日
1.10.1 2016 年 12 月 22 日 2020 年 8 月 30 日
1.10.0 2016 年 10 月 3 日 2020 年 8 月 30 日
1.9.0 2016 年 7 月 7 日 2020 年 8 月 30 日
1.8.0 2016 年 6 月 14 日 2020 年 8 月 30 日
1.7.0 2016 年 4 月 26 日 2020 年 8 月 30 日
1.6.0 2016 年 3 月 29 日 2020 年 8 月 30 日
1.5.6 2016 年 3 月 8 日 2020 年 8 月 30 日
1.5.5 2016 年 2 月 2 日 2020 年 8 月 30 日
1.5.4 2016 年 2 月 1 日 2020 年 8 月 30 日
1.5.2 2016 年 1 月 26 日 2020 年 8 月 30 日
1.5.2 2016 年 1 月 22日 2020 年 8 月 30 日
1.5.1 2016 年 1 月 4 日 2020 年 8 月 30 日
1.5.0 2015 年 12 月 31 日 2020 年 8 月 30 日
1.4.0 2015 年 10 月 6 日 2020 年 8 月 30 日
1.3.0 2015 年 10 月 6 日 2020 年 8 月 30 日
1.2.2 2015 年 9 月 10日 2020 年 8 月 30 日
1.2.1 2015 年 8 月 15日 2020 年 8 月 30 日
1.2.0 2015 年 8 月 5 日 2020 年 8 月 30 日
1.1.0 2015 年 7 月 9 日 2020 年 8 月 30 日
1.0.3 2015 年 6 月 4 日 2020 年 8 月 30 日
1.0.2 2015 年 5 月 23 日 2020 年 8 月 30 日
1.0.1 2015年 5 月 15日 2020 年 8 月 30 日
1.0.0 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 版本提供支持。

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

另请参阅

若要了解有关 Cosmos DB 的详细信息,请参阅 Azure Cosmos DB 服务页。