用于 Core (SQL) API 的 Azure Cosmos DB Java SDK v4:发行说明和资源

适用于: SQL API

用于 Core (SQL) 的 Azure Cosmos DB Java SDK v4 将异步 API 和同步 API 合并到一个 Maven 项目中。 v4 SDK 基于 Project Reactor 和 Netty 库提供了增强的性能、新 API 功能和 Async 支持。 通过 Azure Cosmos DB Java SDK v4 与 Azure Cosmos DB Async Java SDK v2Azure Cosmos DB Sync Java SDK v2,用户可以提高性能。

重要

这些发行说明仅适用于 Azure Cosmos DB Java SDK v4。 如果你当前使用的是早于 v4 的版本,请参阅迁移到 Azure Cosmos DB Java SDK v4 指南,获取升级到 v4 的相关帮助。

以下是快速操作的三个步骤!

  1. 安装最低支持的 Java 运行时版本,JDK 8,以便可以使用 SDK。
  2. 通过 Azure Cosmos DB Java SDK v4 快速入门指南,可以访问 Maven 项目并完成基本的 Azure Cosmos DB 请求。
  3. 阅读 Azure Cosmos DB Java SDK v4 性能提示疑难解答指南,以优化应用程序的 SDK。

此外,Azure Cosmos DB 研讨会和实验室也是了解如何使用 Azure Cosmos DB Java SDK v4 的绝佳资源!

帮助性内容

Content 链接
SDK 下载 Maven
API 文档 Java API 参考文档
参与 SDK GitHub 上用于 Java 的 Azure SDK 中央存储库
入门 快速入门:生成 Java 应用以管理 Azure Cosmos DB SQL API 数据
具有快速入门代码的 GitHub 存储库
基本代码示例 Azure Cosmos DB:SQL API 的 Java 示例
具有示例代码的 GitHub 存储库
包含更改源的控制台应用 更改源 - Java SDK v4 示例
具有示例代码的 GitHub 存储库
Web 应用示例 使用 Java SDK v4 构建 Web 应用
具有示例代码的 GitHub 存储库
性能提示 适用于 Java SDK v4 的性能提示
故障排除 排查 Java SDK v4 问题
从旧 SDK 迁移到 v4 迁移到 Java V4 SDK
受支持的最小运行时 JDK 8
Azure Cosmos DB 研讨会和实验室 Cosmos DB 研讨会主页

重要

  • 4.13.0 版本更新了 2020.0.4 (Europium) 版本序列的 reactor-corereactor-netty 的主要版本。
  • 4.7.0 版本 - 强烈建议使用 4.7.0 版本和更高版本。

发布历史记录

4.16.0-beta.2(未发布)

4.16.0-beta.1 (2021-05-20)

关键 Bug 修复

  • 与以前版本相比没有变化,是为了解决与 cosmos 加密模块的兼容性问题而发布。

4.15.0 (2021-05-12)

新功能

  • CosmosDiagnostics 中为 DIRECT 连接模式添加了 backendLatencyInMs
  • CosmosDiagnostics 中添加了 retryContext,用于查询操作。

关键 Bug 修复

  • 修复了被忽略的 HttpClient 解码器配置问题。
  • 修复了 CosmosDiagnostics 中错误的连接模式问题。
  • 修复了有效分区键中处理冲突的问题。
  • 修复了 readAllItems API 中的 CosmosQueryRequestOptions NPE。

4.15.0-beta.2 (2021-04-26)

关键 Bug 修复

  • 与以前版本相比没有变化,是为了解决与 cosmos 加密模块的兼容性问题而发布。

4.15.0-beta.1 (2021-04-07)

关键 Bug 修复

  • 与以前版本相比没有变化,是为了解决与 cosmos 加密模块的兼容性问题而发布。

4.14.0 (2021-04-06)

新功能

  • CosmosAsyncContainerCosmosContainerreadMany() API 的正式版。
  • CosmosPagedFluxCosmosPagedIterablehandle() API 的正式版。
  • 已将 Jackson 升级到修补程序版本 2.12.2。
  • FeedResponse 中公开了 getDocumentUsagegetDocumentCountUsage() API,以检索文档计数元数据。

关键 Bug 修复

  • 允许 CosmosPagedFlux#handle()CosmosPagedIterable#handle() API 进行链接。
  • CosmosException 中删除了 AfterBurner 模块的使用,导致出现警告日志。
  • 修复了同一“更改源处理器”实例上项的重复处理问题。
  • 在客户端的写入操作超时时返回 RequestTimeoutException

4.13.1 (2021-03-22)

关键 Bug 修复

  • 修复了问题:当并行计划程序中的线程所需存储不足时,由于过时的网关缓存而导致无法从 410 状态代码和 0 子状态代码恢复。
  • 修复了由于 CosmosDiagnostics 中使用 afterburner 模块而引起的警告。
  • 查询性能改进。

4.13.0 (2021-03-11)

重要

此版本将 reactor-corereactor-netty 主要版本更新为 2020.0.4 (Europium) 版本序列。

新功能

  • 已将 reactor-core 版本更新为 3.4.3。
  • 已将 reactor-netty 版本更新为 1.0.4。
  • 添加了用于查询的 Diagnostics

关键 Bug 修复

  • 修复了跨分区查询的混合类型和未定义类型的 OrderBy
  • 修复了具有 resourceToken 的 readAllItems
  • 修复了在 resourceToken 连接模式下使用 Gateway 的问题。
  • 修复了在 Gateway 连接模式下具有权限的点操作问题。

4.12.0 (2021-02-09)

新功能

  • 添加了连接终结点重新发现功能,以帮助减少和缓和高延迟高峰。
  • 添加了 changeFeed 拉取模型 beta API。
  • 添加了对分区拆分后从预先拆分的延续令牌中恢复查询的支持。
  • 通过缓存设有筛选器和 orderby 的单分区查询的查询计划,优化了查询执行时间。

关键 Bug 修复

  • 修复了遥测反序列化问题。
  • 跳过查询计划、触发器和 UDF 的会话令牌。
  • 改进了会话超时 404/1002 异常处理。

4.11.0 (2021-01-15)

新功能

  • 添加了用于修补程序支持的 Beta API。
  • 已将 reactor-core 库版本更新为 3.3.12.RELEASE
  • 已将 reactor-netty 库版本更新为 0.9.15.RELEASE
  • 已将 netty 库版本更新为 4.1.54.Final

关键 Bug 修复

  • 修复了 RntbdServiceEnpoint 关闭问题。
  • 提高了多路复用时写入的延迟和吞吐量。

4.10.0 (2020-12-14)

新功能

  • 添加了冲突 API 支持。

4.9.0 (2020-12-11)

新功能

  • 添加了用于批量操作的 Beta API。
  • CosmosDiagnostics 中添加了 getRegionsContacted API。
  • 已为 CosmosStoredProcedureResponse 添加诊断。
  • 添加了 CosmosException 的疑难解答指南链接。

关键 Bug 修复

  • 在可能的情况下,在客户端暂时性写入失败时添加自动重试,并且仍然是幂等的。
  • 修复了 CosmosStoredProcedureResponsegetDiagnostics 上的 NPE。
  • 修复了 CosmosException 中的空 resourceAddress

4.8.0 (2020-10-27)

新功能

  • CosmosItemRequestOptions 添加了 contentResponseOnWriteEnabled 功能。

关键 Bug 修复

  • 修复了从延续令牌恢复时可能会影响查询行为的问题。

4.7.1 (2020-10-21)

关键 Bug 修复

  • 改进了 449 重试策略,以在初始重试时强制退避,并从较短的退避开始。

4.7.0 (2020-10-17)

重要

强烈建议客户使用 4.7.0 及更高版本。

新功能

  • 添加了针对事务性批处理的 Beta 版本 API。

关键 Bug 修复

  • 修复了在以“,”作为浮点分隔符的区域设置中分析查询指标时出现的错误。
  • 从网关检索包含无效 json 的响应时,停止了过度的区域故障转移。
  • 修复了一个错误,该错误导致网关中不必要地预期某些查询,即使使用直接传输也是如此。
  • 通过处理通道关闭时引发的 SSLException 来降低日志记录噪声级别。
  • 提高了“404 - ReadSession 不可用”错误的重试逻辑效率。

4.6.0 (2020-09-30)

新功能

  • 添加了新的 API,用于在 Cosmos 中支持 AAD 基于角色的访问控制。 这是一项预览功能,需要在帐户设置中启用它。
  • CosmosPagedFlux/CosmosPagedIterable 添加了处理程序 API (beta),以便对每个响应调用。

4.5.2 (2020-09-29)

关键 Bug 修复

  • 增强了在出现间歇性连接问题时执行查询和获取元数据缓存的可靠性。

4.5.1 (2020-09-25)

关键 Bug 修复

  • 为 ChangeFeedProcessor 添加了预览实现,可让你更详细地查看当前状态。
  • 解决了同时运行的多分区监督器任务在 leaseAcquireInterval 小于 leaseRenewInterval 时出现的问题。
  • 改进了 Rntbd 连接诊断。
  • 已阻止将 onError Dropped 事件泄露到默认反应器挂钩的情况。

4.5.0 (2020-09-16)

新功能

  • 增强了 Rntbd 堆栈在出现间歇性连接问题时的可靠性。
  • 缩短了在多区域帐户的单个后端副本出现间歇性连接问题时出现的延迟,避免启动不必要的区域故障转移。

4.4.0 (2020-09-12)

关键 Bug 修复

  • 修复了启用 netty-tcnative-boringssl 依赖项时引发的 RequestTimeoutException。
  • 解决了 GATEWAY 模式中 Delete 操作的内存泄漏问题。
  • 修复了终结点 URI 无效时 CosmosClient 实例化中的泄漏情况。
  • 改进了 CPU History 诊断。

4.4.0-beta.1 (2020-08-27)

新功能

  • 添加了新的 API,用于高效地通过 pk/id 对列表来加载多个文档,或加载与一组 pk 值对应的所有文档。
  • 添加了新的 deleteItem API。
  • 默认情况下启用了查询指标。

关键 Bug 修复

  • 修复了 GatewayAddressCache 中的 NPE。
  • 修复了零项响应的查询指标问题。
  • 提高了地址分析和主密钥身份验证的性能(降低了 CPU 使用率)。

4.3.2-beta.2 (2020-08-17)

关键 Bug 修复

  • 与以前版本相比没有变化,因为与 spring 数据模块的兼容性问题而发布。

4.3.2-beta.1 (2020-08-14)

关键 Bug 修复

  • 修复了 RntbdServiceEndpoint 中的问题,以避免未使用的 TCP 连接提前关闭。

4.3.1 (2020-08-13)

关键 Bug 修复

  • 修复了 GROUP BY 查询的问题。在该查询中,它仅返回一页。
  • 根据中央 SDK 准则修复了用户代理字符串格式。
  • 增强了诊断信息,使之包括查询计划诊断。

4.3.0 (2020-07-29)

新功能

  • 已将 reactor-core 库版本更新为 3.3.8.RELEASE
  • 已将 reactor-netty 库版本更新为 0.9.10.RELEASE
  • 已将 netty 库版本更新为 4.1.51.Final
  • 为具有 partitionKeyupsertItem 添加了新的重载 API。
  • 添加了开放式遥测跟踪支持。

关键 Bug 修复

  • 修复了在网关模式下取消请求时引发 SSLException 的问题。
  • 修复了存储过程执行中的资源限制重试策略问题。
  • 修复了 SDK 在日志级别调试模式下挂起的问题。
  • 修复了直接模式下延迟定期出现峰值的问题。
  • 修复了客户端初始化时间过长的问题。
  • 修复了使用直接模式和网关模式自定义客户端时的 http 代理 bug。
  • 修复了用户中的潜在 NPE 传递 null 选项的问题。
  • 将 timeUnit 添加到诊断字符串中的 requestLatency
  • 从诊断字符串中删除了重复的 uri 字符串。
  • 将诊断字符串修复为正确的 JSON 格式以用于点操作。
  • 修复了导致 reactor 链在出现“未找到”异常时爆发的 .single() 运算符问题。

4.2.0 (2020-07-14)

新功能

  • CosmosStoredProcedureRequestOptions 添加了启用脚本日志记录的 API。
  • DirectConnectionConfig 的默认 idleEndpointTimeout 更新为 1 小时,并将默认 connectTimeout 更新为 5 秒。

关键 Bug 修复

  • 修复了 GatewayConnectionConfig idleConnectionTimeout 替代 DirectConnectionConfig idleConnectionTimeout 的问题。
  • 修复了 CosmosQueryRequestOptions 中的 responseContinuationTokenLimitInKb get 和 set API。
  • 修复了使用相同名称重新创建集合时查询和更改源中的问题。
  • 修复了引发 ClassCastException 的顶层查询的问题。
  • 修复了 order by 查询引发 NullPointerException 的问题。
  • 修复了在直接模式下处理已取消的请求导致调用 reactor onErrorDropped 的问题。

4.1.0 (2020-06-25)

新功能

  • 添加了对 GROUP BY 查询的支持。
  • 在 DirectConnectionConfig 中将 maxConnectionsPerEndpoint 的默认值增加到 130。
  • 在 DirectConnectionConfig 中将 maxRequestsPerConnection 的默认值增加到 30。

关键 Bug 修复

  • 修复了使用继续标记恢复时 order by 查询返回重复结果的问题。
  • 修复了 value 查询为嵌套对象返回 null 值的问题。
  • 修复了 RntbdClientChannelPool 中请求管理器上的空指针异常问题。

4.0.1 (2020-06-10)

新功能

  • 已将 QueryRequestOptions 重命名为 CosmosQueryRequestOptions
  • 已将 ChangeFeedProcessorBuilder 更新为生成器模式。
  • 使用新的容器名称和子资源 API 更新了 CosmosPermissionProperties

关键 Bug 修复

  • 修复了 ConnectionPolicy toString() 空指针异常。

4.0.1-beta.4 (2020-06-03)

新功能

  • CosmosClientBuilder 添加了更多示例和丰富的文档。
  • 更新了带有吞吐量属性的 CosmosDatabaseCosmosContainer API,以支持自动缩放/Autopilot。
  • 已将 CosmosClientException 重命名为 CosmosException
  • 已将 AccessConditionAccessConditionType API 替换为 ifMatchETag()ifNoneMatchETag() API。
  • 已将所有 Cosmos*AsyncResponseCosmosResponse 类型合并为单个 CosmosResponse 类型。
  • 已将 CosmosResponseDiagnostics 重命名为 CosmosDiagnostics
  • 已将 FeedResponseDiagnostics 包装到 CosmosDiagnostics 中。
  • 从 azure-cosmos 中删除了 jackson 依赖项并依赖于 azure-core。
  • 已将 CosmosKeyCredential 替换为 AzureKeyCredential 类型。
  • GatewayConnectionConfig 添加了 ProxyOptions API。
  • 更新了 SDK 以使用 Instant 类型,而不是使用 OffsetDateTime
  • 添加了新的枚举类型 OperationKind
  • 已将 FeedOptions 重命名为 QueryRequestOptions
  • Cosmos*Properties 类型添加了 getETag()getTimestamp() API。
  • CosmosExceptionCosmosDiagnostics中添加了 userAgent 信息。
  • 已将 Diagnostics 中的新换行符更新为系统的新换行符。
  • 删除了 readAll* API,请改用查询选择所有 API。
  • 添加了 ChangeFeedProcessor 估算滞后时间 API。

关键 Bug 修复

  • 修复了在按查询的值顺序分析查询结果时的问题。

4.0.1-beta.3 (2020-05-15)

新功能

  • 为 SDK 添加了自动缩放/autopilot 吞吐量预配支持。
  • 已将 ConnectionPolicy 替换为新的连接配置。 通过 CosmosClientBuilder 为直接模式和网关模式连接配置公开 DirectConnectionConfigGatewayConnectionConfig API。
  • 已将 JsonSerializableResource 移到实现包。
  • 向 CosmsClientBuilder 添加了 contentResponseOnWriteEnabled API,该 API 禁用写操作时的完整响应内容。
  • 对响应类型公开了 getETag() API。
  • 已将 CosmosAuthorizationTokenResolver 移至实现。
  • 已将 preferredLocationsmultipleWriteLocations API 重命名为 preferredRegionsmultipleWriteRegions
  • 已将 reactor-core 更新为 3.3.5.RELEASE,将 reactor-netty 更新为 0.9.7.RELEASE,并将 netty 更新为 4.1.49.Final 版本。
  • 在 SDK 中添加了对 analyticalStoreTimeToLive 的支持。

关键 Bug 修复

  • 修复了直接 TCP 客户端的套接字泄漏问题。
  • 修复了 orderByQuery 的继续标记 bug。

4.0.1-beta.2 (2020-04-21)

新功能

  • CosmosClientException 扩展了 AzureException
  • FeedOptions 中删除了 maxItemCountrequestContinuationToken API,改用 CosmosPagedFluxCosmosPagedIterable 中的 byPage() API。
  • Permission API 的公共图面上引入了 CosmosPermissionProperties
  • 删除了 SqlParameterList 类型并将其替换为 List
  • 修复了直接 TCP 客户端中的多个内存泄漏。
  • 添加了对 DISTINCT 查询的支持。
  • 删除了 fasterxml.uuid, guava, commons-io, commons-collection4, commons-text 的外部依赖项。
  • 已将 CosmosPagedFluxCosmosPagedIterable 移到 utils 包。
  • 已将 netty 更新为“4.1.45.Final”,并已将 project reactor 更新为 3.3.3 版本。
  • 已将公共 REST 协定更新为 Final 类。
  • 添加了对点操作高级诊断的支持。

关键 Bug 修复

  • 修复了处理分区拆分但未找到分区时的 ChangeFeedProcessor bug。
  • 修复了跨不同线程同步租约更新时的 ChangeFeedProcessor bug。

4.0.1-beta.1 (2020-03-10)

新功能

  • 已将包更新为 com.azure.cosmos
  • 为模型/REST 协定添加了 models
  • CosmosPagedFluxCosmosPagedIterable 类型添加了 utils 包。
  • 更新了公共 API 以跨 SDK 使用 Duration
  • 已将所有 REST 协定添加到 models 包。
  • RetryOptions 已重命名为 ThrottlingRetryOptions
  • 为查询 API 添加了CosmosPagedFluxCosmosPagedIterable 分页类型。
  • 添加了对在 CosmosClientBuilder#connectionSharingAcrossClientsEnabled(true) 中使用新 API 跨多个 CosmosClients 实例共享 TransportClient 的支持
  • 通过删除双序列化/反序列化来进行查询优化。
  • 通过删除不必要的来回复制来优化响应标头。
  • 通过删除中间字符串实例化优化了 ByteBuffer 序列化/反序列化。

关键 Bug 修复

  • 修复了在 StoreReader 中导致 ArrayIndexOutOfBound 异常的争用情况

常见问题

如何收到即将停用的 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 服务页。