适用于 SQL API 的 Azure Cosmos DB Async Java SDK:发行说明和资源Azure Cosmos DB Async Java SDK for SQL API: Release notes and resources

SQL API Async Java SDK 与 SQL API Java SDK 的区别在于,前者通过支持 Netty 库提供异步操作。The SQL API Async Java SDK differs from the SQL API Java SDK by providing asynchronous operations with support of the Netty library. 先存在的 SQL API Java SDK 不支持异步操作。The pre-existing SQL API Java SDK does not support asynchronous operations.

重要

这不是最新的 Azure Cosmos DB Java SDK!This is not the latest Java SDK for Azure Cosmos DB! 请考虑将 Azure Cosmos DB Java SDK v4 用于项目。Consider using Azure Cosmos DB Java SDK v4 for your project. 若要升级,请按照迁移到 Azure Cosmos DB Java SDK v4 指南和 Reactor 与 RxJava 指南中的说明进行操作。To upgrade, follow the instructions in the Migrate to Azure Cosmos DB Java SDK v4 guide and the Reactor vs RxJava guide.

SDK 下载SDK Download MavenMaven
API 文档API documentation Java API 参考文档Java API reference documentation
参与 SDKContribute to SDK GitHubGitHub
入门Get started Async Java SDK 入门Get started with the Async Java SDK
代码示例Code sample GitHubGitHub
性能提示Performance tips GitHub 自述文件GitHub readme
受支持的最小运行时Minimum supported runtime JDK 8JDK 8

2.6.9 - 2020-06-152.6.9 - 2020-06-15

  • 修复了从继续标记恢复时 order by 结果重复的问题 (#341)Fixed duplicate results on order by when resuming from continuation token (#341)

2.6.8 - 2020-05-112.6.8 - 2020-05-11

  • 修复了一个问题,该问题导致从继续标记恢复时 order by 结果可能包含重复/缺少的文档 (#332)Fixes an issue due to which the order by results when resuming from continuation token might contain duplicates/missing documents (#332)

2.6.7 - 2020-04-212.6.7 - 2020-04-21

  • 修复了直接 TCP 传输客户端中的多个内存泄漏 (#326)Fixed multiple memory leak in direct TCP transport client (#326)

2.6.6 - 2020-03-122.6.6 - 2020-03-12

  • 使 DocumentClientException 线程安全 (#323)Made DocumentClientException thread safe (#323)

2.6.5 - 2020-01-312.6.5 - 2020-01-31

  • 修复了尝试恢复跨分区查询时继续标记设置不正确的问题 (#312)Fixed an issue where continuation token is not being set properly when trying to resume cross partition queries(#312)
  • 将反序列化移出 Netty 线程 (#315)Moving deserialization out of netty threads (#315)
  • 修复了禁止时无法重试写入的问题 (#307)Fixed dont retry writes on forbidden (#307)

2.6.4 - 2020-01-022.6.4 - 2020-01-02

  • 修复了 SDK 在发生网络故障时重试写入的 bug (#301)Fixed a bug where SDK was retrying on writes on network failure(#301)
  • 添加了对使用系统属性指定默认直接 TCP 选项的支持 (#299)Add support for specifying default Direct TCP options using System properties (#299)
  • 改进了直接 TCP 传输客户端中的诊断功能 (#287)Improved diagnostics in Direct TCP transport client (#287)
  • 将 Netty 版本升级到了 4.1.42.Final,并将 netty-tcnative.version 升级到了 2.0.26.Final,以解决直接 TCP SSL 问题 (#274)Bumped netty.version to 4.1.42.Final and netty-tcnative.version to 2.0.26.Final to address a Direct TCP SSL issue (#274)

2.6.3 - 2019-10-232.6.3 - 2019-10-23

  • 解决了报告错误(重试策略已损坏)的状态代码:Addressed status code reporting errors that undermined retry policy:
    • RequestRateTooLargeException.getStatusCode 现在会正确返回 TOO_MANY_REQUESTSRequestRateTooLargeException.getStatusCode now correctly returns TOO_MANY_REQUESTS.
    • ServiceUnavailableException.getStatusCode 现在会正确返回 SERVICE_UNAVAILABLEServiceUnavailableException.getStatusCode now correctly returns SERVICE_UNAVAILABLE.
    • commons 和 direct-impl 中的 DocumentClientExceptionTest 现在会验证是否为所有 DocumentClientException 子类型返回了正确的状态代码。DocumentClientExceptionTest in commons and direct-impl now verify that the correct status code is returned for all DocumentClientException subtypes.

2.6.2 - 2019-10-052.6.2 - 2019-10-05

  • 修复了将 MaxItemCount 设置为 -1 时的查询故障 (#261)。Fixed query failure when setting MaxItemCount to -1 (#261).
  • 修复了有关分区拆分的 NPE bug (#267)。Fixed a NPE bug on Partitoin split (#267).
  • 改进了直接模式下的日志记录。Improved logging in Direct mode.

2.6.1 - 2019-09-042.6.1 - 2019-09-04

  • 针对查询逻辑的多主数据库区域故障转移修补程序 (#245)Multimaster regional failover fixes for query logic (#245)
  • jackson-databind 2.9.9.3 更新 (#244)jackson-databind 2.9.9.3 update (#244)
  • 直接 TCP 修补程序(内存、性能)及指标接口 (#242)Direct TCP fixes (memory, perf) & metrics interface (#242)

2.6.0 - 2019-08-012.6.0 - 2019-08-01

  • 使用新查询计划检索程序检索查询信息 (#111)Retrieving query info using new query plan retriever (#111)
  • 偏移量限制查询支持 (#234)Offset limit query support (#234)

2.5.1 - 2019-07-312.5.1 - 2019-07-31

  • 修复 executeStoredProcedureInternal 以使用客户端重试策略 (#210)Fixing executeStoredProcedureInternal to use client retry policy (#210)

2.4.6 - 2019-07-192.4.6 - 2019-07-19

  • 内存改进memory improvements

2.5.0 - 2019-06-252.5.0 - 2019-06-25

  • 默认启用 TCP 传输TCP transport enabled by default
  • TCP 传输改进TCP transport improvements
  • 大量测试改进Lots of testing improvements

2.4.5 - 2019-05-062.4.5 - 2019-05-06

  • 添加了对 Hash v2 的支持 (#96)Added support for Hash v2 (#96)
  • 开源直接连接实现 (#94)Open source direct connectivity implementation (#94)
  • 添加了对诊断字符串的支持Added Support for Diagnostics String

2.4.4 - 2019-06-252.4.4 - 2019-06-25

  • 其他修补程序misc fixes

2.4.3 - 2019-03-052.4.3 - 2019-03-05

  • 修复了关闭客户端时资源泄漏的问题Fixed resource leak issue on closing client

2.4.2 - 2019-03-012.4.2 - 2019-03-01

  • 修复了对跨分区查询的继续标记支持中的 bugFixed bugs in continuation token support for cross partition queries

2.4.1 - 2019-02-202.4.1 - 2019-02-20

  • 修复了直接模式下的一些 bug。Fixed some bugs in Direct mode.
  • 改进了直接模式下的日志记录。Improved logging in Direct mode.
  • 改进了连接管理。Improved connection management.

2.4.0 - 2019-02-082.4.0 - 2019-02-08

  • 直接公开上市。Direct GA.
  • 添加了对 QueryMetrics 的支持。Added support for QueryMetrics.
  • 将接受 java.util.Collection(顺序很重要)的 API 更改为接受 java.util.List。Changed the APIs accepting java.util.Collection for which order is important to accept java.util.List instead. 现在 ConnectionPolicy#getPreferredLocations()、JsonSerialization 和 PartitionKey(.) 接受列表。Now ConnectionPolicy#getPreferredLocations(), JsonSerialization, and PartitionKey(.) accept List.

2.4.0-beta1 - 2019-02-042.4.0-beta1 - 2019-02-04

  • 添加了对直接 Https 的支持。Added support for Direct Https.
  • 将接受 java.util.Collection(顺序很重要)的 API 更改为接受 java.util.List。Changed the APIs accepting java.util.Collection for which order is important to accept java.util.List instead. 现在 ConnectionPolicy#getPreferredLocations()、JsonSerialization 和 PartitionKey(.) 接受列表。Now ConnectionPolicy#getPreferredLocations(), JsonSerialization, and PartitionKey(.) accept List.
  • 修复了网关模式下文档查询的会话 bug。Fixed a Session bug for Document query in Gateway mode.
  • 升级了依赖项(netty 0.4.20 github #79、RxJava 1.3.8)。Upgraded dependencies (netty 0.4.20 github #79, RxJava 1.3.8).

2.3.1 - 2019-01-152.3.1 - 2019-01-15

  • 修复了处理大规模查询响应时的问题。Fix handling very large query responses.
  • 修复了实例化客户端时的资源令牌处理方面的问题 (github #78)。Fix resource token handling when instantiating client (github #78).
  • 升级了易受攻击的依赖项 jackson-databind (github #77)。Upgraded vulnerable dependency jackson-databind (github #77).

2.3.0 - 2018-11-292.3.0 - 2018-11-29

  • 修复了资源泄漏 bug。Fixed a resource leak bug.
  • 添加了对 MultiPolygon 的支持Added support for MultiPolygon
  • 在 RequestOptions 中添加了对自定义标头的支持。Added support for custom headers in RequestOptions.

2.2.2 - 2018-11-262.2.2 - 2018-11-26

  • 修复了打包 bug。Fixed a packaging bug.

2.2.1 - 2018-11-052.2.1 - 2018-11-05

  • 修复了写入重试路径中的 NPE bug。Fixed a NPE bug in write retry path.
  • 修复了终结点管理中的 NPE bug。Fixed a NPE bug in endpoint management.
  • 升级了易受攻击的依赖项 (github #68)。Upgraded vulnerable dependencies (github #68).
  • 添加了对 Netty 网络日志记录的支持,以便进行故障排除。Added support for Netty network logging for troubleshooting.

2.2.0 - 2018-10-042.2.0 - 2018-10-04

  • 添加了对多区域写入的支持。Added support for Multi-region write.

2.1.0 - 2018-09-062.1.0 - 2018-09-06

  • 添加了对代理的支持。Added support for Proxy.
  • 添加了对资源令牌授权的支持。Added support for resource token authorization.
  • 修复了处理大分区键时的 bug (github #63)。Fixed a bug in handling large partition keys (github #63).
  • 改进了文档。Documentation improved.
  • SDK 重构为更细粒度的模块。SDK restructured into more granular modules.

2.0.1 - 2018-08-162.0.1 - 2018-08-16

  • 修复了非英语区域设置的 bug (github #51)。Fixed a bug for non-english locales (github #51).
  • 为冲突资源添加了帮助器方法。Added helper methods for Conflict resource.

2.0.0 - 2018-06-202.0.0 - 2018-06-20

  • 由于性能原因和授权,由 jackson 替换了 org.json 依赖项 (github #29)。Replaced org.json dependency by jackson due to performance reasons and licensing (github #29).
  • 删除了弃用的 OfferV2 类。Removed deprecated OfferV2 class.
  • 向 Offer 类添加了访问器方法以获取吞吐量内容。Added accessor method to Offer class for throughput content.
  • Document/Resource 中返回 org.json 类型的任何方法均已更改为返回 jackson 对象类型。Any method in Document/Resource returning org.json types changed to return a jackson object type.
  • 扩展了 JsonSerializable 的类的 getObject(.) 方法已更改为返回 jackson ObjectNode 类型。getObject(.) method of classes extending JsonSerializable changed to return a jackson ObjectNode type.
  • getCollection(.) 方法已更改为返回 ObjectNode 的集合。getCollection(.) method changed to return Collection of ObjectNode.
  • 使用 org.json.JSONObject arg 删除了 JsonSerializable 子类的构造函数。Removed JsonSerializable subclasses' constructors with org.json.JSONObject arg.
  • JsonSerializable.toJson (SerializationFormattingPolicy.Indented) 现在使用两个空格进行缩进。JsonSerializable.toJson (SerializationFormattingPolicy.Indented) now uses two spaces for indentation.

1.0.2 - 2018-05-181.0.2 - 2018-05-18

  • 添加了对唯一索引策略的支持。Added support for Unique Index Policy.
  • 在源选项中添加了对限制响应继续标记大小的支持。Added support for limiting response continuation token size in feed options.
  • 在跨分区查询中添加了对分区拆分的支持。Added support for Partition Split in Cross Partition Query.
  • 修复了 Json 时间戳序列化中的一个 bug (github #32)。Fixed a bug in Json timestamp serialization (github #32).
  • 修复了 Json 枚举序列化中的一个 bug。Fixed a bug in Json enum serialization.
  • 修复了管理 2MB 大小文档中的一个 bug (github #33)。Fixed a bug in managing documents of 2MB size (github #33).
  • 由于 bug (jackson-databind: github #1599),依赖项 com.fasterxml.jackson.core:jackson-databind 升级到了 2.9.5Dependency com.fasterxml.jackson.core:jackson-databind upgraded to 2.9.5 due to a bug (jackson-databind: github #1599)
  • 由于 bug (rxjava-extras: github #30),rxjava-extras 的依赖项升级到了 0.8.0.17。Dependency on rxjava-extras upgraded to 0.8.0.17 due to a bug (rxjava-extras: github #30).
  • pom 文件中的元数据说明更新为与文档的其余部分内联。The metadata description in pom file updated to be inline with the rest of documentation.
  • 语法改进 (github #41)、(github #40)。Syntax improvement (github #41), (github #40).

1.0.1 - 2018-04-201.0.1 - 2018-04-20

  • 在查询中添加了反压力支持。Added back-pressure support in query.
  • 在查询中添加了对分区键范围 ID 的支持。Added support for partition key range id in query.
  • 更改为允许在请求标头中使用更大的继续标记 (bugfix github #24)。Changed to allow larger continuation token in request header (bugfix github #24).
  • Netty 依赖项已升级到 4.1.22.Final,以确保 JVM 在主线程完成后关闭。netty dependency upgraded to 4.1.22.Final to ensure JVM shuts down after main thread finishes.
  • 已更改为避免在读取主资源时传递会话令牌。Changed to avoid passing session token when reading master resources.
  • 添加了更多示例。Added more examples.
  • 添加了更多基准测试方案。Added more benchmarking scenarios.
  • 修复了 Java 头文件以便生成正确的 javadoc。Fixed java header files for proper javadoc generation.

1.0.0 - 2018-02-261.0.0 - 2018-02-26

  • 版本 1.0.0 对于在网关模式下使用 Netty 库的非阻止 IO 提供完全的端到端支持。Release 1.0.0 has fully end to end support for non-blocking IO using netty library in Gateway mode.
  • 已删除 azure-documentdb SDK 的依赖项。Dependency on azure-documentdb SDK removed.
  • 项目 ID 在 0.9.0-rc2 中已从 azure-documentdb-rx 更改为 azure-cosmosdbArtifact id changed to azure-cosmosdb from azure-documentdb-rx in 0.9.0-rc2.
  • Java 包名称在 0.9.0-rc2 中已从 com.microsoft.azure.documentdb 更改为 com.microsoft.azure.cosmosdbJava package name changed to com.microsoft.azure.cosmosdb from com.microsoft.azure.documentdb in 0.9.0-rc2.

0.9.0-rc2 - 2018-02-260.9.0-rc2 - 2018-02-26

  • FeedResponsePage 已重命名为 FeedReponseFeedResponsePage renamed to FeedReponse
  • ConnectionPolicy 配置的一些小修改。Some minor modifications to ConnectionPolicy configuration. ConnectionPolicy 中的所有时间字段和方法均采用“InMillis”作为后缀,以使时间单位更加精确。All time fields and methods in ConnectionPolicy suffixed with "InMillis" to be more precise of the time unit.
  • 已删除 ConnectionPolicy#setProxy()ConnectionPolicy#setProxy() removed.
  • FeedOptions#pageSize 已重命名为 FeedOptions#maxItemCountFeedOptions#pageSize renamed to FeedOptions#maxItemCount
  • 版本 1.0.0 取代了 0.9.x 版本。Release 1.0.0 deprecates 0.9.x releases.

0.9.0-rc10.9.0-rc1

  • azure-documentdb-rx SDK 的第一版。First release of azure-documentdb-rx SDK.
  • CRUD 文档 API 完全不阻止使用 Netty。CRUD Document API fully non-blocking using netty. 已使用阻止 SDK azure-documentdb 将查询异步 API 实现为包装器。Query async API implemented as a wrapper using blocking SDK azure-documentdb.

发布日期和停用日期Release and retirement dates

Azure 会在停用 SDK 时至少提前 12 个月发出通知,以便用户顺利转换为更高版本/受支持版本。Azure will provide notification at least 12 months in advance of retiring an SDK in order to smooth the transition to a newer/supported version.

新特性、功能和优化仅添加到最新的 SDK 中。New features and functionality and optimizations are only added to the current SDK. 因此建议你始终尽早升级到最新的 SDK 版本。So it's recommended that you always upgrade to the latest SDK version as early as possible.

使用已停用的 SDK 对 Cosmos DB 发出的任何请求都会被服务拒绝。Any request to Cosmos DB using a retired SDK will be rejected by the service.

警告

Async Java SDK for SQL API 的所有 1.x 版本将于 2020 年 8 月 30 日停用 。All versions 1.x of the Async Java SDK for SQL API will be retired on August 30, 2020.


版本Version 发布日期Release Date 停用日期Retirement Date
2.6.42.6.4 2020 年 1 月 2 日Jan 2, 2020 ---
2.6.32.6.3 2019 年 10 月 23 日Oct 23, 2019 ---
2.6.22.6.2 2019 年 10 月5 日Oct 5, 2019 ---
2.6.12.6.1 2019 年 9 月 4 日Sept 4, 2019 ---
2.6.02.6.0 2019 年 8 月 1 日Aug 1, 2019 ---
2.5.12.5.1 2019 年 7 月 31 日Jul 31, 2019 ---
2.4.62.4.6 2019 年 7 月 19 日Jul 19, 2019 ---
2.5.02.5.0 2019 年 6 月 25 日Jun 25, 2019 ---
2.4.52.4.5 2019 年 5 月 6 日May 6, 2019 ---
2.4.32.4.3 2019 年 3 月 5 日Mar 5, 2019 ---
2.4.22.4.2 2019 年 3 月 1 日Mar 1, 2019 ---
2.4.12.4.1 2019 年 2 月 20 日Feb 20, 2019 ---
2.4.02.4.0 2019 年 2 月 8 日Feb 8, 2019 ---
2.4.0-beta-12.4.0-beta-1 2019 年 2 月 4 日Feb 4, 2019 ---
2.3.12.3.1 2019 年 1 月 15 日Jan 15, 2019 ---
2.3.02.3.0 2018 年 11 月 29 日Nov 29, 2018 ---
2.2.22.2.2 2018 年 11 月 8 日Nov 8, 2018 ---
2.2.12.2.1 2018 年 11 月 2日Nov 2, 2018 ---
2.2.02.2.0 2018 年 9 月 22 日September 22, 2018 ---
2.1.02.1.0 2018 年 9 月 5 日September 5, 2018 ---
2.0.12.0.1 2018 年 8 月 16 日August 16, 2018 ---
2.0.02.0.0 2018 年 6 月 20 日June 20, 2018 ---
1.0.21.0.2 2018 年 5 月 18日May 18, 2018 2020 年 8 月 30 日August 30, 2020
1.0.11.0.1 2018 年 4 月 20 日April 20, 2018 2020 年 8 月 30 日August 30, 2020
1.0.01.0.0 2018 年 2 月 27 日February 27, 2018 2020 年 8 月 30 日August 30, 2020

常见问题FAQ

1.如何向客户通知即将停用的 SDK?1. How will customers be notified of the retiring SDK?

Azure 会在即将停用的 SDK 的支持结束之前提前 12 个月进行通知,以便协助平稳地转换到支持的 SDK。Azure will provide 12 month advance notification to the end of support of the retiring SDK in order to facilitate a smooth transition to a supported SDK. 此外,会通过各种通信渠道(Azure 管理门户、开发人员中心、博客文章以及与分配的服务管理员的直接通信)来通知客户。Further, customers will be notified through various communication channels - Azure Management Portal, Developer Center, blog post, and direct communication to assigned service administrators.

2.在这 12 个月期间,客户是否可以使用“即将”停用的 Azure Cosmos DB SDK 来创作应用程序?2. Can customers author applications using a "to-be" retired Azure Cosmos DB SDK during the 12 month period?

可以,客户在 12 个月宽限期内具有完全访问权限,可以使用“即将”停用的 Azure Cosmos DB SDK 创作、部署和修改应用程序。Yes, customers will have full access to author, deploy and modify applications using the "to-be" retired Azure Cosmos DB SDK during the 12 month grace period. 在 12 个月宽限期内,建议客户根据相应情况迁移到支持的较新版本 Azure Cosmos DB SDK。During the 12 month grace period, customers are advised to migrate to a newer supported version of Azure Cosmos DB SDK as appropriate.

3.在 12 个月通知期之后,客户是否可以使用已停用的 Azure Cosmos DB SDK 创建和修改应用程序?3. Can customers author and modify applications using a retired Azure Cosmos DB SDK after the 12 month notification period?

在 12 个月通知期之后,SDK 会停用。After the 12 month notification period, the SDK will be retired. Azure Cosmos DB 平台不允许使用已停用 SDK 的应用程序对 Azure Cosmos DB 进行任何访问。Any access to Azure Cosmos DB by an applications using a retired SDK will not be permitted by the Azure Cosmos DB platform. 此外,Azure 不会对已停用的 SDK 提供客户支持。Further, Azure will not provide customer support on the retired SDK.

4.如果客户运行使用不支持的 Azure Cosmos DB SDK 版本的应用程序,会发生什么情况?4. What happens to Customer's running applications that are using unsupported Azure Cosmos DB SDK version?

任何使用已停用 SDK 版本连接 Azure Cosmos DB 服务的尝试都会被拒绝。Any attempts made to connect to the Azure Cosmos DB service with a retired SDK version will be rejected.

5.新特性和功能是否会适用于所有未停用的 SDK?5. Will new features and functionality be applied to all non-retired SDKs?

新特性和功能只添加到新版本。New features and functionality will only be added to new versions. 如果使用的是未停用的旧版本 SDK,则对 Azure Cosmos DB 进行的请求仍会与以前一样正常工作,但是你无法访问任何新功能。If you are using an old, non-retired, version of the SDK your requests to Azure Cosmos DB will still function as previous but you will not have access to any new capabilities.

6.如果无法在截止日期之前更新应用程序,该怎么办?6. What should I do if I cannot update my application before a cut-off date?

我们建议尽早升级到最新 SDK。We recommend that you upgrade to the latest SDK as early as possible. SDK 标记为要停用之后,会有 12 个月来更新应用程序。Once an SDK has been tagged for retirement you will have 12 months to update your application. 如果由于任何原因而无法在此时间范围内完成应用程序更新,请在截止日期之前与 Cosmos DB 团队联系并请求其帮助。If, for whatever reason, you cannot complete your application update within this timeframe then please contact the Cosmos DB Team and request their assistance before the cutoff date.

另请参阅See also

若要了解有关 Cosmos DB 的详细信息,请参阅 Azure Cosmos DB 服务页。To learn more about Cosmos DB, see Azure Cosmos DB service page.