通过

Spring Cloud Azure 4.0 的迁移指南

  • 项目

本指南可帮助从旧版 Azure Spring 库迁移到 Spring Cloud Azure 4.0。

介绍

我们将调用组 ID 和项目 ID 遵循 新式 库 模式的库，以及具有模式 、或 旧 库的库。

本指南将重点介绍新式和旧版库之间类似配置的并行比较。

假定熟悉 com.azure.spring:azure-spring-boot-*、com.azure.spring:azure-spring-cloud-* 或 com.azure.spring:azure-spring-integration-* 包。

如果你不熟悉 Spring Cloud Azure 4.0 库，请参阅 Spring Cloud Azure 开发人员指南 而不是本指南。

迁移优势

考虑是否采用新版本或库时要问的自然问题是它的好处。 随着 Azure 已经成熟并得到了一组更多样化的开发人员的欢迎，我们专注于学习模式和做法，以最好地支持开发人员的工作效率，并了解 Spring Cloud Azure 库存在的差距。

在 Spring Cloud Azure 库中，有一些一致的反馈。 最重要的是，不同 Azure 服务的库尚未启用完整的配置集。 此外，项目命名、项目 ID、版本和配置不一致使学习曲线急剧增加。

为了改善 Spring Cloud Azure 库的开发体验，引入了一组设计准则，以确保 Spring Cloud Azure 库在 Spring 生态系统方面具有自然和惯常的感觉。 设计文档中提供了更多详细信息， 感兴趣的人员。

Spring Cloud Azure 4.0 提供与不同 Spring 项目集成的库之间的共享体验，例如 Spring Boot、Spring Integration、Spring Cloud Stream 等。 共享体验包括：

  • 包含所有 Spring Cloud Azure 4.0 库的统一 BOM。
  • 项目的一致命名约定。
  • 配置凭据、代理、重试、云环境和传输层设置的统一方法。
  • 支持 Azure 服务或 Azure 服务 SDK 支持的所有身份验证方法。

概述

此迁移指南包含以下部分：

  • Spring Cloud Azure 4.0 的命名更改
  • 项目更改：已重命名/已添加/已删除
  • 依赖项更改
  • 身份验证更改
  • 配置属性
  • API 中断性变更
  • 库更改

命名更改

从未有一个一致或官方名称来调用所有 Spring Cloud Azure 库。 其中一些人被称为 Azure Spring Boot，其中一些人 Spring on Azure。 自 4.0 起，我们开始使用项目名称 Spring Cloud Azure 来表示所有 Azure Spring 库。

BOM

我们过去为库（azure-spring-boot-bom 和 azure-spring-cloud-dependencies）运送了两个 BOM，但自 4.0 spring-cloud-azure-dependencies以来，我们将这两个 BOM 合并为一个 BOM。 在项目的 dependencyManagement 部分中添加一个条目，以便从依赖项管理中受益。

<dependencyManagement>
  <dependencies>
    <dependency>
      <groupId>com.azure.spring</groupId>
      <artifactId>spring-cloud-azure-dependencies</artifactId>
      <version>5.20.0</version>
      <type>pom</type>
      <scope>import</scope>
    </dependency>
  </dependencies>
</dependencyManagement>

注意

如果使用 Spring Boot 2.x，请确保将 spring-cloud-azure-dependencies 版本设置为 4.19.0。 有关用于此 BOM 的版本的详细信息，请参阅 应使用哪个版本的 Spring Cloud Azure。

项目更改：已重命名/已添加/已删除

对于现代和旧版 Spring Cloud Azure 库，组 ID 是相同的。 他们都是 com.azure.spring。 新式 Spring Cloud Azure 库的项目 ID 已更改。 根据它所属的 Spring 项目、Spring Boot、Spring Integration 或 Spring Cloud Stream，项目 ID 模式可以是 spring-cloud-azure-starter-[service]、spring-integration-azure-[service]或 spring-cloud-azure-stream-binder-[service]。 每个项目的旧初学者都遵循模式 azure-spring-*的项目 ID。 这提供了一种快速且易于访问的方法，可帮助你快速了解使用新式或旧版初学者。

在开发 Spring Cloud Azure 4.0 的过程中，我们重命名了一些项目，使其遵循新的命名约定，删除了一些项目，以便可以将该功能放入更合适的项目中，并添加了一些新项目，以更好地为某些方案提供服务。

下表显示了旧项目 ID 与新式项目 ID 之间的映射：

旧项目 ID 新式项目 ID 描述
azure-spring-boot-starter spring-cloud-azure-starter 此项目已被删除，所有功能都将合并到新的 spring-cloud-azure-starter 项目中。
azure-spring-boot-starter-active-directory spring-cloud-azure-starter-active-directory 已重命名项目。
azure-spring-boot-starter-active-directory-b2c spring-cloud-azure-starter-active-directory-b2c 已重命名项目。
azure-spring-boot-starter-cosmos spring-cloud-azure-starter-data-cosmos 已重命名项目以添加 data，指示使用 Spring Data Azure Cosmos DB。
azure-spring-boot-starter-keyvault-certificates 不適用 此版本中未包含，但将在更高版本中受支持。
azure-spring-boot-starter-keyvault-secrets spring-cloud-azure-starter-keyvault-secrets 已重命名项目。
azure-spring-boot-starter-servicebus-jms spring-cloud-azure-starter-servicebus-jms 已重命名项目。
azure-spring-boot-starter-storage spring-cloud-azure-starter-storage-blob
spring-cloud-azure-starter-storage-file-share		 旧项目包含存储 Blob 和文件共享的功能，它已合并到 4.0、spring-cloud-azure-starter-storage-blob 和 spring-cloud-azure-starter-storage-file-share 中的两个单独的项目。
azure-spring-boot 不適用 此项目已被删除，所有功能都将合并到新的 spring-cloud-azure-autoconfigure 项目中。
azure-spring-cloud-autoconfigure 不適用 此项目已被删除，所有功能都将合并到新的 spring-cloud-azure-autoconfigure 项目中。
azure-spring-cloud-context 不適用 此项目已删除，所有功能都将合并到新的 spring-cloud-azure-autoconfigure 和 spring-cloud-azure-resourcemanager 项目。
azure-spring-cloud-messaging spring-messaging-azure 消息传送侦听器注释已删除。
azure-spring-cloud-starter-cache 不適用 已删除该项目，以便使用 redis，只需添加 spring-boot-starter-data-redis、spring-boot-starter-cache、spring-cloud-azure-resourcemanager 和 spring-cloud-azure-starter。 有关使用情况的详细信息，请参阅 Spring Cloud Azure Redis 支持。
azure-spring-cloud-starter-eventhubs-kafka 不適用 已删除此项目，以便使用 kafka，只需添加 spring kafka、spring-cloud-azure-resourcemanager 和 spring-cloud-azure-starter。 有关使用情况的详细信息，请参阅 Spring Cloud Azure Kafka 支持。
azure-spring-cloud-starter-eventhubs spring-cloud-azure-starter-integration-eventhubs 已重命名项目以添加 integration，指示将 Spring Integration 与事件中心配合使用。
azure-spring-cloud-starter-servicebus spring-cloud-azure-starter-integration-servicebus 已重命名项目以添加 integration，指示将 Spring Integration 与服务总线配合使用。
azure-spring-cloud-starter-storage-queue spring-cloud-azure-starter-integration-storage-queue 已重命名项目以添加 integration，指示将 Spring Integration 与存储队列配合使用。
azure-spring-cloud-storage 不適用 此项目已被删除，所有功能都合并到新的 spring-cloud-azure-autoconfigure 项目中。
azure-spring-cloud-stream-binder-eventhubs spring-cloud-azure-stream-binder-eventhubs 该项目已使用新设计进行重构，主要是 spring-cloud-azure-stream-binder-eventhubs 和 spring-cloud-azure-stream-binder-eventhubs-core。
azure-spring-cloud-stream-binder-service-core spring-cloud-azure-stream-binder-servicebus-core 已重命名项目。
azure-spring-cloud-stream-binder-servicebus-queue spring-cloud-azure-stream-binder-servicebus 此项目已被删除，所有功能都合并到 spring-cloud-azure-stream-binder-servicebus 项目中。
azure-spring-cloud-stream-binder-servicebus-topic spring-cloud-azure-stream-binder-servicebus 此项目已被删除，所有功能都合并到 spring-cloud-azure-stream-binder-servicebus 项目中。
azure-spring-integration-core spring-integration-azure-core 已重命名项目。
azure-spring-integration-eventhubs spring-integration-azure-eventhubs 重命名项目。
azure-spring-integration-servicebus spring-integration-azure-servicebus 重命名项目。
azure-spring-integration-storage-queue spring-integration-azure-storage-queue 重命名项目。
不適用 spring-cloud-azure-initialize 新添加的 Spring Cloud Azure 执行器项目。
不適用 spring-cloud-azure-initialize-autoconfigure 新添加的 Spring Cloud Azure 执行器 AutoConfigure 项目，包括执行器的自动配置。
不適用 spring-cloud-azure-autoconfigure 新添加的 Spring Cloud Azure AutoConfigure 项目，包括 SDK 客户端的所有自动配置、Spring Security 支持、Spring Data 支持和 Spring Integration 支持。
不適用 spring-cloud-azure-core 新添加的 Spring Cloud Azure Core 项目，包括所有核心功能。
不適用 spring-cloud-azure-resourcemanager 新添加的资源管理器项目。 它是使用 Azure 资源管理器读取元数据和创建资源的核心库。
不適用 spring-cloud-azure-service 新添加的 Spring Cloud Azure 服务项目，包括 Azure 服务的抽象。
不適用 spring-cloud-azure-starter-appconfiguration 新添加的入门程序用于使用 Azure 应用配置 SDK 客户端。
不適用 spring-cloud-azure-starter-cosmos 新添加的用于使用 Azure Cosmos DB SDK 客户端的初学者。
不適用 spring-cloud-azure-starter-eventhubs 新增了使用 Azure 事件中心 SDK 客户端的初学者。
不適用 spring-cloud-azure-starter-servicebus 新添加的用于使用 Azure 服务总线 SDK 客户端的初学者。
不適用 spring-cloud-azure-starter-storage-blob 新增了使用 Azure 存储 Blob SDK 客户端的初学者。
不適用 spring-cloud-azure-starter-storage-file-share 新添加的用于使用 Azure 存储文件共享 SDK 客户端的初学者。
不適用 spring-cloud-azure-starter-storage-queue 新增了使用 Azure 存储队列 SDK 客户端的初学者。
不適用 spring-cloud-azure-starter-stream-eventhubs 新增了使用 Azure 事件中心 Spring Cloud Stream Binder 的初学者。
不適用 spring-cloud-azure-starter-stream-servicebus 新添加的入门程序用于使用 Azure 服务总线 Spring Cloud Stream Binder
不適用 spring-cloud-azure-stream-binder-eventhubs-core 为 Azure 事件中心新增了 Spring Cloud Stream 核心项目。

依赖项更改

旧项目中包括了一些不必要的依赖项，我们在现代 Spring Cloud Azure 4.0 库中删除了这些依赖项。 请务必将已删除的依赖项手动添加到项目，以防止崩溃。

具有依赖项更改的库包括：

身份验证更改

Spring Cloud Azure 4.0 支持每个 Azure 服务 SDK 支持的所有身份验证方法。 它使你能够配置全局令牌凭据，并在每个服务级别提供令牌凭据。 但是，配置 Spring Cloud Azure 4.0 不需要凭据，因为它可以应用存储在本地开发环境或 Azure 服务中的托管标识中的凭据。 只需确保主体已获得足够的权限即可访问目标 Azure 资源。

注意

将角色分配给安全主体以与 Azure 消息传送服务交互时，执行消息传送操作需要 Data 相关角色。 对于 Azure Spring Apps Stream 事件中心/服务总线联编程序库，当需要自动创建资源的功能时，需要 Contributor 角色。 有关详细信息，请参阅 Azure 内置角色。

链接凭据，DefaultAzureCredential bean 默认自动配置，如果未指定其他身份验证信息，所有组件都将使用。 有关详细信息，请参阅适用于 Java的 Azure 标识客户端库 的 DefaultAzureCredential 部分。

配置属性

属性迁移

我们已创建一个 additional-spring-configuration-metadata.json 文件，以在与 spring-boot-properties-migrator一起使用时平滑属性迁移。 首先，将以下属性迁移程序添加到应用程序：

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-properties-migrator</artifactId>
    <scope>runtime</scope>
</dependency>

或者，如果使用 Gradle：

runtime("org.springframework.boot:spring-boot-properties-migrator")

如果运行应用，它将标识不再由 Spring Cloud Azure 管理的属性。 如果有替换项，它将暂时重新映射属性，并显示警告。 如果没有替换项，错误报告将为你提供更多信息。 无论哪种方式，都必须更新配置，并在更新配置后删除依赖项。

在继续操作之前，最好使用 IDE 的搜索功能仔细检查是否未使用集成测试中迁移的属性之一。

注意

在此更改中，我们更改了许多配置属性。 使用 spring-boot-properties-migrator 有助于顺利迁移。

全局配置

新式 spring-cloud-azure-starter 使你能够定义应用于命名空间 spring.cloud.azure中所有 Azure SDK 的属性。 旧版 azure-spring-boot-starter不支持此功能。 全局配置可以分为五个类别，如下表所示：

前缀 描述
spring.cloud.azure.client 在每个 Azure SDK 下配置传输客户端。
spring.cloud.azure.credential 配置如何使用 Microsoft Entra ID 进行身份验证。
spring.cloud.azure.profile 配置 Azure 云环境。
spring.cloud.azure.proxy 配置代理选项，适用于所有 Azure SDK 客户端。
spring.cloud.azure.retry 配置重试选项，适用于所有 Azure SDK 客户端。 重试选项支持部分 SDK，没有 spring.cloud.azure.cosmos.retry。

有关配置的完整列表，请参阅Spring Cloud Azure 配置属性。

配置每个 SDK

有关 SDK 级别的配置选项的详细信息，请使用以下链接：

API 中断性变更

有关每个库中 API 中断性变更的详细信息，请使用以下链接：

库更改

每个库中的中断性变更如下所示。

从 azure-spring-boot-starter 到 spring-cloud-azure-starter

本指南旨在帮助从 azure-spring-boot-starter版本 3 迁移到 spring-cloud-azure-starter。

有关常规信息，请使用以下链接：

  • 有关 4.0 中更改的概述，请参阅 简介 和 迁移权益 部分。
  • 若要详细了解项目命名中的策略更改，请参阅 命名更改 部分。
  • 若要了解如何对所有 Spring Cloud Azure 库使用一个 BOM，请参阅 BOM 部分。
  • 若要了解如何在 Spring Cloud Azure 4.0 中处理身份验证，请参阅 身份验证更改 部分。
  • 若要了解如何在迁移期间利用 spring-boot-properties-migrator，请参阅 配置每个 SDK 部分。
  • 若要详细了解全局配置和常见配置更改，请参阅 全局配置 部分。

依赖项更改

旧项目中包括了一些不必要的依赖项，我们在现代 Spring Cloud Azure 4.0 库中删除了这些依赖项。 请务必将已删除的依赖项手动添加到项目，以防止意外崩溃。

下表显示了“已删除”依赖项：

删除了依赖项 描述
org.springframework.boot：spring-boot-starter-validation 如果要使用休眠验证程序，请包含验证初学者。

从 azure-spring-boot-starter-active-directory 到 spring-cloud-azure-starter-active-directory

本指南旨在帮助从 azure-spring-boot-starter-active-directory版本 3 迁移到 spring-cloud-azure-starter-active-directory。

有关常规信息，请使用以下链接：

  • 有关 4.0 中更改的概述，请参阅 简介 和 迁移权益 部分。
  • 若要详细了解项目命名中的策略更改，请参阅 命名更改 部分。
  • 若要了解如何对所有 Spring Cloud Azure 库使用一个 BOM，请参阅 BOM 部分。
  • 若要了解如何在 Spring Cloud Azure 4.0 中处理身份验证，请参阅 身份验证更改 部分。
  • 若要了解如何在迁移期间利用 spring-boot-properties-migrator，请参阅 配置每个 SDK 部分。
  • 若要详细了解全局配置和常见配置更改，请参阅 全局配置 部分。

依赖项更改

自新式 Spring Cloud Azure 4.0 库以来，已删除旧项目中的一些不必要的依赖项。 将这些已删除的依赖项添加到项目，以防止意外崩溃。

下表显示了“已删除”依赖项：

删除了依赖项 描述
com.fasterxml.jackson.core：jackson-databind 如果需要，请将此依赖项添加到项目。
io.projectreactor.netty：reactor-netty 如果需要，请将此依赖项添加到项目。
org.springframework.boot：spring-boot-starter-validation 如果需要，请将此依赖项添加到项目。
org.springframework.boot：spring-boot-starter-webflux 如果需要，请将此依赖项添加到项目。

SDK 配置更改

本部分包括有关添加、删除和更改的属性的更改。

  • 以下两点是关注的主要事项：
  1. 所有配置属性名称的前缀都从 azure.activedirectory 更改为 spring.cloud.azure.active-directory。
  2. 添加了新属性 spring.cloud.azure.active-directory.enabled 以启用/禁用Microsoft Entra 相关功能。 默认值为 false。

下表显示了 azure-spring-boot-starter-active-directory 和 spring-cloud-azure-starter-active-directory之间的属性映射：

旧属性 新式属性
azure.activedirectory.app-id-uri spring.cloud.azure.active-directory.app-id-uri
azure.activedirectory.application-type spring.cloud.azure.active-directory.application-type
azure.activedirectory.authorization-clients spring.cloud.azure.active-directory.authorization-clients
azure.activedirectory.authorization-clients.AZURE_CLIENT_NAME.authorization-grant-type spring.cloud.azure.active-directory.authorization-clients.AZURE_CLIENT_NAME.authorization-grant-type
azure.activedirectory.authorization-clients.AZURE_CLIENT_NAME.on-demand spring.cloud.azure.active-directory.authorization-clients.AZURE_CLIENT_NAME.on-demand
azure.activedirectory.authorization-clients.AZURE_CLIENT_NAME.scopes spring.cloud.azure.active-directory.authorization-clients.AZURE_CLIENT_NAME.scopes
azure.activedirectory.authenticate-additional-parameters spring.cloud.azure.active-directory.authenticate-additional-parameters
azure.activedirectory.base-uri spring.cloud.azure.active-directory.profile.environment.active-directory-endpoint
azure.activedirectory.client-id spring.cloud.azure.active-directory.credential.client-id
azure.activedirectory.client-secret spring.cloud.azure.active-directory.credential.client-secret
azure.activedirectory.graph-membership-uri 有关详细信息，请查看下表。
azure.activedirectory.jwt-connect-timeout spring.cloud.azure.active-directory.jwt-connect-timeout。
azure.activedirectory.jwt-read-timeout spring.cloud.azure.active-directory.jwt-read-timeout。
azure.activedirectory.jwt-size-limit spring.cloud.azure.active-directory.jwt-size-limit。
azure.activedirectory.jwk-set-cache-生命期 spring.cloud.azure.active-directory.jwk-set-cache-生命期。
azure.activedirectory.jwk-set-cache-refresh-time spring.cloud.azure.active-directory.jwk-set-cache-refresh-time
azure.activedirectory.post-logout-redirect-uri spring.cloud.azure.active-directory.post-logout-redirect-uri
azure.activedirectory.session-stateless spring.cloud.azure.active-directory.session-stateless
azure.activedirectory.redirect-uri-template spring.cloud.azure.active-directory.redirect-uri-template
azure.activedirectory.resource-server.claim-to-authority-prefix-map spring.cloud.azure.active-directory.resource-server.claim-to-authority-prefix-map
azure.activedirectory.resource-server.principal-claim-name spring.cloud.azure.active-directory.resource-server.principal-claim-name
azure.activedirectory.tenant-id spring.cloud.azure.active-directory.profile.tenant-id
azure.activedirectory.user-group.allowed-group-ids spring.cloud.azure.active-directory.user-group.allowed-group-ids
azure.activedirectory.user-group.allowed-group-names spring.cloud.azure.active-directory.user-group.allowed-group-names
azure.activedirectory.user-name-attribute spring.cloud.azure.active-directory.user-name-attribute

  • 以下属性的值类型从 long 更改为 Duration：

    • jwt-connect-timeout
    • jwt-read-timeout
    • jwk-set-cache-lifespan
    • jwk-set-cache-refresh-time。

  • 删除了以下属性：

    • azure.activedirectory.allow-telemetry
    • azure.activedirectory.user-group.enable-full-list
    • azure.activedirectory.graph-base-uri
    • azure.activedirectory.graph-membership-uri

  • 添加了以下属性：

    • spring.cloud.azure.active-directory.enabled
    • spring.cloud.azure.active-directory.profile.environment.microsoft-graph-endpoint
    • spring.cloud.azure.active-directory.user-group.use-transitive-members

注意

azure.activedirectory.graph-membership-uri 函数已替换为 2 个属性：spring.cloud.azure.active-directory.profile.environment.microsoft-graph-endpoint 和 spring.cloud.azure.active-directory.user-group.use-transitive-members。 第一个属性用于指定主机名，第二个用于使用 URL 路径的标志：v1.0/me/memberOf 或 v1.0/me/transitiveMemberOf。

下面是迁移的一些示例：

  • 示例 1. 案例 1

    • 对于旧版：azure.activedirectory.graph-membership-uri=https://graph.microsoft.com/v1.0/me/memberOf

    • 对于新式：spring.cloud.azure.active-directory.profile.environment.microsoft-graph-endpoint=https://graph.microsoft.com/ + spring.cloud.azure.active-directory.user-group.use-transitive-members=false

  • 示例 2. 案例 2

    • 对于旧版：azure.activedirectory.graph-membership-uri=https://graph.microsoft.com/v1.0/me/transitiveMemberOf

    • 对于新式：spring.cloud.azure.active-directory.profile.environment.microsoft-graph-endpoint=https://graph.microsoft.com/ + spring.cloud.azure.active-directory.user-group.use-transitive-members=true

API 更改

下表显示了从 azure-spring-boot-starter-active-directory 到 spring-cloud-azure-starter-active-directory的类映射：

旧类 新式类
com.azure.spring.aad.webapi.AADJwtBearerTokenAuthenticationConverter com.azure.spring.cloud.autoconfigure.aad.AadJwtBearerTokenAuthenticationConverter
com.azure.spring.aad.webapi.AADResourceServerProperties com.azure.spring.cloud.autoconfigure.aad.properties.AadResourceServerProperties
com.azure.spring.aad.webapi.AADResourceServerWebSecurityConfigurerAdapter com.azure.spring.cloud.autoconfigure.aad.AadResourceServerWebSecurityConfigurerAdapter
com.azure.spring.aad.webapp.AADWebSecurityConfigurerAdapter com.azure.spring.cloud.autoconfigure.aad.AadWebSecurityConfigurerAdapter
com.azure.spring.aad.webapp.AuthorizationClientProperties com.azure.spring.cloud.autoconfigure.aad.properties.AuthorizationClientProperties
com.azure.spring.aad.AADApplicationType com.azure.spring.cloud.autoconfigure.aad.properties.AadApplicationType
com.azure.spring.aad.AADAuthorizationGrantType com.azure.spring.cloud.autoconfigure.aad.properties.AadAuthorizationGrantType
com.azure.spring.aad.AADAuthorizationServerEndpoints com.azure.spring.cloud.autoconfigure.aad.properties.AadAuthorizationServerEndpoints
com.azure.spring.aad.AADClientRegistrationRepository com.azure.spring.cloud.autoconfigure.aad.AadClientRegistrationRepository
com.azure.spring.aad.AADTrustedIssuerRepository com.azure.spring.cloud.autoconfigure.aad.AadTrustedIssuerRepository
com.azure.spring.autoconfigure.aad.AADAppRoleStatelessAuthenticationFilter com.azure.spring.cloud.autoconfigure.aad.filter.AadAppRoleStatelessAuthenticationFilter
com.azure.spring.autoconfigure.aad.AADAuthenticationFilter com.azure.spring.cloud.autoconfigure.aad.filter.AadAuthenticationFilter
com.azure.spring.autoconfigure.aad.AADAuthenticationProperties com.azure.spring.cloud.autoconfigure.aad.properties.AadAuthenticationProperties
com.azure.spring.autoconfigure.aad.UserPrincipal com.azure.spring.cloud.autoconfigure.aad.filter.UserPrincipal
com.azure.spring.autoconfigure.aad.UserPrincipalManager com.azure.spring.cloud.autoconfigure.aad.filter.UserPrincipalManager

本部分列出了从 azure-spring-boot-starter-active-directory 中删除的类。

  • 删除了旧类

    • com.azure.spring.aad.webapp.AADHandleConditionalAccessFilter
    • com.azure.spring.aad.webapi.validator.AADJwtAudienceValidator
    • com.azure.spring.aad.webapi.validator.AADJwtClaimValidator

从 azure-spring-boot-starter-active-directory-b2c 到 spring-cloud-azure-starter-active-directory-b2c

本指南旨在帮助从 azure-spring-boot-starter-active-directory-b2c版本 3 迁移到 spring-cloud-azure-starter-active-directory-b2c。

有关常规信息，请使用以下链接：

  • 有关 4.0 中更改的概述，请参阅 简介 和 迁移权益 部分。
  • 若要详细了解项目命名中的策略更改，请参阅 命名更改 部分。
  • 若要了解如何对所有 Spring Cloud Azure 库使用一个 BOM，请参阅 BOM 部分。
  • 若要了解如何在 Spring Cloud Azure 4.0 中处理身份验证，请参阅 身份验证更改 部分。
  • 若要了解如何在迁移期间利用 spring-boot-properties-migrator，请参阅 配置每个 SDK 部分。
  • 若要详细了解全局配置和常见配置更改，请参阅 全局配置 部分。

依赖项更改

旧项目中包括了一些不必要的依赖项，我们在现代 Spring Cloud Azure 4.0 库中删除了这些依赖项。 请务必将已删除的依赖项手动添加到项目，以防止意外崩溃。

下表显示了“已删除”依赖项：

删除了依赖项 描述
org.springframework.boot：spring-boot-starter-validation 如果要使用休眠验证程序，请包含验证初学者。

SDK 配置更改

本部分包括有关添加、删除和更改的属性的更改。

  • 以下两点是关注的主要事项：
  1. 所有配置属性名称将前缀从 azure.activedirectory.b2c 更改为 spring.cloud.azure.active-directory.b2c。
  2. 添加了新属性 spring.cloud.azure.active-directory.b2c.enabled 以允许启用/禁用 Azure AD B2C 相关功能。 默认值为 false。

下表显示了从 azure-spring-boot-starter-active-directory-b2c 到 spring-cloud-azure-starter-active-directory-b2c的属性映射：

旧属性 新式属性
azure.activedirectory.b2c.authenticate-additional-parameters spring.cloud.azure.active-directory.b2c.authenticate-additional-parameters
azure.activedirectory.b2c.authorization-clients spring.cloud.azure.active-directory.b2c.authorization-clients
azure.activedirectory.b2c.authorization-clients。<AZURE_CLIENT_NAME>.authorization-grant-type spring.cloud.azure.active-directory.b2c.authorization-clients。<AZURE_CLIENT_NAME>.authorization-grant-type
azure.activedirectory.b2c.authorization-clients。<AZURE_CLIENT_NAME>.scopes spring.cloud.azure.active-directory.b2c.authorization-clients。<AZURE_CLIENT_NAME>.scopes
azure.activedirectory.b2c.app-id-uri spring.cloud.azure.active-directory.b2c.app-id-uri
azure.activedirectory.b2c.base-uri spring.cloud.azure.active-directory.b2c.base-uri
azure.activedirectory.b2c.client-id spring.cloud.azure.active-directory.b2c.credential.client-id
azure.activedirectory.b2c.client-secret spring.cloud.azure.active-directory.b2c.credential.client-secret
azure.activedirectory.b2c.jwt-connect-timeout spring.cloud.azure.active-directory.b2c.jwt-connect-timeout
azure.activedirectory.b2c.jwt-read-timeout spring.cloud.azure.active-directory.b2c.jwt-read-timeout
azure.activedirectory.b2c.jwt-size-limit spring.cloud.azure.active-directory.b2c.jwt-size-limit
azure.activedirectory.b2c.login-flow spring.cloud.azure.active-directory.b2c.login-flow
azure.activedirectory.b2c.logout-success-url spring.cloud.azure.active-directory.b2c.logout-success-url
azure.activedirectory.b2c.reply-url spring.cloud.azure.active-directory.b2c.reply-url
azure.activedirectory.b2c.tenant-id spring.cloud.azure.active-directory.b2c.profile.tenant-id
azure.activedirectory.b2c.user-flow spring.cloud.azure.active-directory.b2c.user-flow
azure.activedirectory.b2c.user-name-attribute-name spring.cloud.azure.active-directory.b2c.user-name-attribute-name

  • 从 azure-spring-boot-starter-active-directory-b2c 中删除了属性：

    • azure.activedirectory.b2c.allow-telemetry
    • azure.activedirectory.b2c.tenant

  • 以下属性的值类型从 long 更改为 Duration：

    • jwt-connect-timeout
    • jwt-read-timeout

API 更改

下表显示了从 azure-spring-boot-starter-active-directory-b2c 到 spring-cloud-azure-starter-active-directory-b2c的类映射：

旧类 新式类
com.azure.spring.autoconfigure.b2c.AADB2CAuthorizationRequestResolver com.azure.spring.cloud.autoconfigure.aadb2c.AadB2cAuthorizationRequestResolver
com.azure.spring.autoconfigure.b2c.AADB2CJwtBearerTokenAuthenticationConverter com.azure.spring.cloud.autoconfigure.aad.AadJwtBearerTokenAuthenticationConverter
com.azure.spring.autoconfigure.b2c.AADB2CLogoutSuccessHandler com.azure.spring.cloud.autoconfigure.aadb2c.AadB2cLogoutSuccessHandler
com.azure.spring.autoconfigure.b2c.AADB2COidcLoginConfigurer com.azure.spring.cloud.autoconfigure.aadb2c.AadB2COidcLoginConfigurer
com.azure.spring.autoconfigure.b2c.AADB2CProperties com.azure.spring.cloud.autoconfigure.aadb2c.properties.AadB2cProperties
com.azure.spring.autoconfigure.b2c.AADB2CTrustedIssuerRepository com.azure.spring.cloud.autoconfigure.aadb2c.AadB2cTrustedIssuerRepository
com.azure.spring.autoconfigure.b2c.AuthorizationClientProperties com.azure.spring.cloud.autoconfigure.aad.properties.AuthorizationClientProperties

从 azure-spring-boot-starter-cosmos 到 spring-cloud-azure-starter-data-cosmos

本指南旨在帮助从 azure-spring-boot-starter-cosmos版本 3 迁移到 spring-cloud-azure-starter-data-cosmos。

有关常规信息，请使用以下链接：

  • 有关 4.0 中更改的概述，请参阅 简介 和 迁移权益 部分。
  • 若要详细了解项目命名中的策略更改，请参阅 命名更改 部分。
  • 若要了解如何对所有 Spring Cloud Azure 库使用一个 BOM，请参阅 BOM 部分。
  • 若要了解如何在 Spring Cloud Azure 4.0 中处理身份验证，请参阅 身份验证更改 部分。
  • 若要了解如何在迁移期间利用 spring-boot-properties-migrator，请参阅 配置每个 SDK 部分。
  • 若要详细了解全局配置和常见配置更改，请参阅 全局配置 部分。

SDK 配置更改

所有配置属性名称将前缀从 azure.cosmos 更改为 spring.cloud.azure.cosmos。

下表显示了从 azure-spring-boot-starter-cosmos 到 spring-cloud-azure-starter-data-cosmos的类映射：

旧属性 新式属性
azure.cosmos.connection-mode spring.cloud.azure.cosmos.connection-mode
azure.cosmos.consistency-level spring.cloud.azure.cosmos.consistency-level
azure.cosmos.database spring.cloud.azure.cosmos.database
azure.cosmos.key spring.cloud.azure.cosmos.key
azure.cosmos.populate-query-metrics spring.cloud.azure.cosmos.populate-query-metrics
azure.cosmos.uri spring.cloud.azure.cosmos.endpoint

从 azure-spring-boot-starter-keyvault-secrets 到 spring-cloud-azure-starter-keyvault-secrets

本指南旨在帮助从 azure-spring-boot-starter-starter-keyvault-secrets版本 3 spring-cloud-azure-starter-keyvault-secrets。

有关常规信息，请使用以下链接：

  • 有关 4.0 中更改的概述，请参阅 简介 和 迁移权益 部分。
  • 若要详细了解项目命名中的策略更改，请参阅 命名更改 部分。
  • 若要了解如何对所有 Spring Cloud Azure 库使用一个 BOM，请参阅 BOM 部分。
  • 若要了解如何在 Spring Cloud Azure 4.0 中处理身份验证，请参阅 身份验证更改 部分。
  • 若要了解如何在迁移期间利用 spring-boot-properties-migrator，请参阅 配置每个 SDK 部分。
  • 若要详细了解全局配置和常见配置更改，请参阅 全局配置 部分。

SDK 配置更改

本部分包括有关添加、删除和更改的属性的更改。

下表显示了从 azure-spring-boot-starter-keyvault-secrets 到 spring-cloud-azure-starter-keyvault-secrets的属性映射：

旧属性 新式属性
azure.keyvault.case-sensitive-keys spring.cloud.azure.keyvault.secret.property-source[n].case-sensitive
azure.keyvault.certificate-password spring.cloud.azure.keyvault.secret.property-source[n].credential.client-certificate-password
azure.keyvault.certificate-path spring.cloud.azure.keyvault.secret.property-source[n].credential.client-certificate-path
azure.keyvault.client-id spring.cloud.azure.keyvault.secret.property-source[n].credential.client-id
azure.keyvault.client-key spring.cloud.azure.keyvault.secret.property-source[n].credential.client-secret
azure.keyvault.enabled spring.cloud.azure.keyvault.secret.property-source-enabled 和 spring.cloud.azure.keyvault.secret.property-source-enabled
azure.keyvault.order 不再受支持。 请改用属性源[n]中的顺序。
azure.keyvault.refresh-interval spring.cloud.azure.keyvault.secret.property-source[n].refresh-interval
azure.keyvault.secret-keys spring.cloud.azure.keyvault.secret.property-source[n].secret-keys
azure.keyvault.tenant-id spring.cloud.azure.keyvault.secret.property-source[n].profile.tenant-id
azure.keyvault.uri spring.cloud.azure.keyvault.secret.property-source[n].endpoint
  • 从 spring-cloud-azure-starter-keyvault-secrets 中删除了属性

azure.keyvault.allow-telemetry azure.keyvault.order

应注意以下几点：

  1. 所有配置属性名称将前缀从 azure.keyvault 更改为 spring.cloud.azure.keyvault.secret。
  2. spring.cloud.azure.keyvault.secret.enabled 用于启用所有 Key Vault 机密功能，包括配置 Key Vault 机密客户端（如 SecretClient 和 SecretAsyncClient），并在 ConfigurableEnvironment中添加 KeyVaultPropertySource。
  3. spring.cloud.azure.keyvault.secret.property-source-enabled 用于启用所有 KeyVaultPropertySource。 只有在 spring.cloud.azure.keyvault.secret.enabled=true时才生效。
  4. 对于 Azure 通用属性（如 client、proxy、retry、credential、profile） 和 Key Vault 属性（如 endpoint、service-version）。 如果未配置 spring.cloud.azure.keyvault.secret.property-sources[n].PROPERTY_NAME，将使用 spring.cloud.azure.keyvault.secret.PROPERTY_NAME。
  5. spring.cloud.azure.keyvault.secret.property-sources[n].resource 特定于唯一的 Azure 资源，因此如果未配置，则不会从其他位置获取值。

从 azure-spring-boot-starter-servicebus-jms 到 spring-cloud-azure-starter-servicebus-jms

本指南旨在帮助从 azure-spring-boot-starter-servicebus-jms版本 3 迁移到 spring-cloud-azure-starter-servicebus-jms。

有关常规信息，请使用以下链接：

  • 有关 4.0 中更改的概述，请参阅 简介 和 迁移权益 部分。
  • 若要详细了解项目命名中的策略更改，请参阅 命名更改 部分。
  • 若要了解如何对所有 Spring Cloud Azure 库使用一个 BOM，请参阅 BOM 部分。
  • 若要了解如何在 Spring Cloud Azure 4.0 中处理身份验证，请参阅 身份验证更改 部分。
  • 若要了解如何在迁移期间利用 spring-boot-properties-migrator，请参阅 配置每个 SDK 部分。
  • 若要详细了解全局配置和常见配置更改，请参阅 全局配置 部分。

SDK 配置更改

spring.jms.servicebus.idle-timeout 的配置类型从 long（毫秒）更改为 Duration 模式，以便可读。

从 azure-spring-boot-starter-storage 到 spring-cloud-azure-starter-storage-blob

本指南旨在帮助从 azure-spring-boot-starter-storage版本 3 迁移到 spring-cloud-azure-starter-storage-blob。

有关常规信息，请使用以下链接：

  • 有关 4.0 中更改的概述，请参阅 简介 和 迁移权益 部分。
  • 若要详细了解项目命名中的策略更改，请参阅 命名更改 部分。
  • 若要了解如何对所有 Spring Cloud Azure 库使用一个 BOM，请参阅 BOM 部分。
  • 若要了解如何在 Spring Cloud Azure 4.0 中处理身份验证，请参阅 身份验证更改 部分。
  • 若要了解如何在迁移期间利用 spring-boot-properties-migrator，请参阅 配置每个 SDK 部分。
  • 若要详细了解全局配置和常见配置更改，请参阅 全局配置 部分。

SDK 配置更改

所有配置属性名称将前缀从 azure.storage 更改为 spring.cloud.azure.storage.blob。

下表显示了从 azure-spring-boot-starter-storage 到 spring-cloud-azure-starter-storage-blob的属性映射：

旧属性 新式属性
azure.storage.account-name spring.cloud.azure.storage.blob.account-name
azure.storage.account-key spring.cloud.azure.storage.blob.account-key
azure.storage.blob 终结点 spring.cloud.azure.storage.blob.endpoint

API 更改

下表显示了从 azure-spring-boot-starter-storage 到 spring-cloud-azure-starter-storage-blob的类映射：

旧类 新式类
com.azure.spring.autoconfigure.storage.resource.AzureStorageProtocolResolver com.azure.spring.core.resource.AzureStorageBlobProtocolResolver
com.azure.spring.autoconfigure.storage.resource.BlobStorageResource com.azure.spring.core.resource.StorageBlobResource
com.azure.spring.autoconfigure.storage.resource.AzureStorageResourcePatternResolver com.azure.spring.core.resource.AzureStorageBlobProtocolResolver

从 azure-spring-boot-starter-storage 到 spring-cloud-azure-starter-storage-file-share

本指南旨在帮助从 azure-spring-boot-starter-storage-storage版本 3 迁移到 spring-cloud-azure-starter-storage-file-share。

有关常规信息，请使用以下链接：

  • 有关 4.0 中更改的概述，请参阅 简介 和 迁移权益 部分。
  • 若要详细了解项目命名中的策略更改，请参阅 命名更改 部分。
  • 若要了解如何对所有 Spring Cloud Azure 库使用一个 BOM，请参阅 BOM 部分。
  • 若要了解如何在 Spring Cloud Azure 4.0 中处理身份验证，请参阅 身份验证更改 部分。
  • 若要了解如何在迁移期间利用 spring-boot-properties-migrator，请参阅 配置每个 SDK 部分。
  • 若要详细了解全局配置和常见配置更改，请参阅 全局配置 部分。

SDK 配置更改

所有配置属性名称将前缀从 azure.storage 更改为 spring.cloud.azure.storage.fileshare。

下表显示了从 azure-spring-boot-starter-storage 到 spring-cloud-azure-starter-storage-file-share的属性映射：

旧属性 新式属性
azure.storage.account-name spring.cloud.azure.storage.fileshare.account-name
azure.storage.account-key spring.cloud.azure.storage.fileshare.account-key
azure.storage.file-endpoint spring.cloud.azure.storage.fileshare.endpoint

API 更改

下表显示了从 azure-spring-boot-starter-storage 到 spring-cloud-azure-starter-storage-file-share的类映射：

旧类 新式类
com.azure.spring.autoconfigure.storage.resource.AzureStorageProtocolResolver com.azure.spring.core.resource.AzureStorageFileProtocolResolver
com.azure.spring.autoconfigure.storage.resource.FileStorageResource com.azure.spring.core.resource.StorageFileResource
com.azure.spring.autoconfigure.storage.resource.AzureStorageResourcePatternResolver com.azure.spring.core.resource.AzureStorageFileProtocolResolver

从 azure-spring-cloud-starter-eventhubs 到 spring-cloud-azure-starter-integration-eventhubs

本指南旨在帮助从 azure-spring-cloud-starter-eventhubs版本 2 迁移到 spring-cloud-starter-integration-eventhubs。

有关常规信息，请使用以下链接：

  • 有关 4.0 中更改的概述，请参阅 简介 和 迁移权益 部分。
  • 若要详细了解项目命名中的策略更改，请参阅 命名更改 部分。
  • 若要了解如何对所有 Spring Cloud Azure 库使用一个 BOM，请参阅 BOM 部分。
  • 若要了解如何在 Spring Cloud Azure 4.0 中处理身份验证，请参阅 身份验证更改 部分。
  • 若要了解如何在迁移期间利用 spring-boot-properties-migrator，请参阅 配置每个 SDK 部分。
  • 若要详细了解全局配置和常见配置更改，请参阅 全局配置 部分。

SDK 配置更改

重要

配置前缀已从 spring.cloud.azure.eventhub 更改为 spring.cloud.azure.eventhubs.

有关此前缀的子项的更改，请参阅下表：

下表显示了从 azure-spring-cloud-starter-eventhubs 到 spring-cloud-azure-starter-integration-eventhubs的属性映射：

旧属性 新式属性
spring.cloud.azure.resource-group spring.cloud.azure.eventhubs.resource.resource-group
spring.cloud.azure.eventhub.namespace spring.cloud.azure.eventhubs.namespace
spring.cloud.azure.eventhub.connection-string spring.cloud.azure.eventhubs.connection-string
spring.cloud.azure.eventhub.checkpoint-storage-account spring.cloud.azure.eventhubs.processor.checkpoint-store.account-name
spring.cloud.azure.eventhub.checkpoint-access-key spring.cloud.azure.eventhubs.processor.checkpoint-store.account-key
spring.cloud.azure.eventhub.checkpoint-container spring.cloud.azure.eventhubs.processor.checkpoint-store.container-name

例如，从：

spring:
  cloud:
    azure:
      eventhub:
        connection-string: ${AZURE_EVENTHUBS_CONNECTION_STRING}
        checkpoint-storage-account: ${AZURE_CHECKPOINT_STORAGE_ACCOUNT_NAME}
        checkpoint-access-key: ${AZURE_CHECKPOINT_ACCOUNT_KEY}
        checkpoint-container: ${AZURE_CHECKPOINT_CONTAINER_NAME}

自：

spring:
  cloud:
    azure:
      eventhubs:
        connection-string: ${AZURE_EVENTHUBS_CONNECTION_STRING}
        processor:
          checkpoint-store:
            container-name: ${AZURE_STORAGE_CONTAINER_NAME}
            account-name: ${AZURE_STORAGE_ACCOUNT_NAME}
            account-key: ${AZURE_STORAGE_ACCOUNT_KEY}

API 更改

  • 有关侦听器注释的更改，请参阅 <<migration-azure-spring-cloud-messaging、azure-spring-cloud-messaging>> 库的迁移指南。
  • 删除 EventHubOperation，订阅函数移动到类 EventHubsMessageListenerContainer，发送函数移动到 EventHubsTemplate。
  • 将 EventHubInboundChannelAdapter 重命名为 EventHubsInboundChannelAdapter，以与 Azure 事件中心的服务保持一致。
  • 将构造函数从 EventHubInboundChannelAdapter(String, SubscribeByGroupOperation, String) 更改为 EventHubsInboundChannelAdapter(EventHubsMessageListenerContainer) 和 EventHubsInboundChannelAdapter(EventHubsMessageListenerContainer, ListenerMode)。
  • 将 CheckpointConfig 实例化样式更改为简单构造函数，而不是生成样式。
  • 删除 API EventHubOperation#setCheckpointConfig。 若要设置入站通道适配器的检查点配置，用户可以调用方法 EventHubsContainerProperties#setCheckpointConfig。
  • 删除 API EventHubOperation#setBatchConsumerConfig。 若要设置入站通道适配器的批处理使用配置，用户可以同时调用两种方法 EventHubsContainerProperties#getBatch#setMaxSize 和 EventHubsContainerProperties#getBatch#setMaxWaitTime。
  • 对于批处理使用模式，请更改从批处理消息转换的消息标头名称。
    • 将消息标头从 azure_eventhub_enqueued_time 更改为 azure_eventhubs_batch_converted_enqueued_time。
    • 将消息标头从 azure_eventhub_offset 更改为 azure_eventhubs_batch_converted_offset。
    • 将消息标头从 azure_eventhub_sequence_number 更改为 azure_eventhubs_batch_converted_sequence_number。
    • 将消息标头从 azure_partition_key 更改为 azure_batch_converted_partition_key。
  • 将消息发布到事件中心时，忽略从批处理消息转换的所有消息标头。 标头包括：
    • azure_batch_converted_partition_key
    • azure_eventhubs_batch_converted_enqueued_time
    • azure_eventhubs_batch_converted_offset
    • azure_eventhubs_batch_converted_sequence_number
    • azure_eventhubs_batch_converted_system_properties
    • azure_eventhubs_batch_converted_application_properties
  • BATCH 检查点模式现在仅适用于批处理使用模式，可通过将 ListenerMode.BATCH 传递给 EventHubsInboundChannelAdapter 构造函数来启用该模式。

下表显示了从 azure-spring-cloud-starter-eventhubs 到 spring-cloud-azure-starter-integration-eventhubs的类映射：

旧类 新式类
com.azure.spring.integration.core.AzureHeaders com.azure.spring.messaging.AzureHeaders
com.azure.spring.integration.core.EventHubHeaders com.azure.spring.messaging.eventhubs.support.EventHubsHeaders
com.azure.spring.integration.core.api.CheckpointConfig com.azure.spring.messaging.eventhubs.core.checkpoint.CheckpointConfig
com.azure.spring.integration.core.api.CheckpointMode com.azure.spring.messaging.eventhubs.core.checkpoint.CheckpointMode
com.azure.spring.integration.core.api.reactor.Checkpointer com.azure.spring.messaging.checkpoint.Checkpointer
com.azure.spring.integration.core.api.reactor.DefaultMessageHandler com.azure.spring.integration.core.handler.DefaultMessageHandler
com.azure.spring.integration.eventhub.inbound.EventHubInboundChannelAdapter com.azure.spring.integration.eventhubs.inbound.EventHubsInboundChannelAdapter

示例代码片段

  • EventHubsInboundChannelAdapter 示例代码：

    旧代码：

    public class Demo {
    @Bean
    public EventHubInboundChannelAdapter messageChannelAdapter(
        @Qualifier("INPUT_CHANNEL") MessageChannel inputChannel, EventHubOperation   eventhubOperation) {
        eventhubOperation.setCheckpointConfig(CheckpointConfig.builder().checkpointMode  (CheckpointMode.MANUAL).build());
        EventHubInboundChannelAdapter adapter = new EventHubInboundChannelAdapter("EVENTHUB_NAME",
            eventhubOperation, "CONSUMER_GROUP");
        adapter.setOutputChannel(inputChannel);
        return adapter;
    }
}

    新式代码：

    public class Demo {
    @Bean
    public EventHubsMessageListenerContainer messageListenerContainer(EventHubsProcessorFactory processorFactory) {
        EventHubsContainerProperties containerProperties = new EventHubsContainerProperties();
        containerProperties.setEventHubName("EVENTHUB_NAME");
        containerProperties.setConsumerGroup("CONSUMER_GROUP");
        CheckpointConfig config = new CheckpointConfig(CheckpointMode.MANUAL);
        containerProperties.setCheckpointConfig(config);
        return new EventHubsMessageListenerContainer(processorFactory, containerProperties);
    }

    @Bean
    public EventHubsInboundChannelAdapter messageChannelAdapter(@Qualifier("INPUT_CHANNEL") MessageChannel inputChannel,
                                                                EventHubsMessageListenerContainer listenerContainer) {
        EventHubsInboundChannelAdapter adapter = new EventHubsInboundChannelAdapter(listenerContainer);
        adapter.setOutputChannel(inputChannel);
        return adapter;
    }
}

  • DefaultMessageHandler 示例代码：

    旧代码：

    public class Demo {
    @Bean
    @ServiceActivator(inputChannel = "OUTPUT_CHANNEL")
    public MessageHandler messageSender(EventHubOperation eventhubOperation) {
        DefaultMessageHandler handler = new DefaultMessageHandler("EVENTHUB_NAME", eventhubOperation);
        handler.setSendCallback(new ListenableFutureCallback<Void>() {
            @Override
            public void onSuccess(Void result) {
                LOGGER.info("Message was sent successfully.");
            }

            @Override
            public void onFailure(Throwable ex) {
                LOGGER.error("There was an error sending the message.", ex);
            }
        });
        return handler;
    }
}

    新式代码：

    public class Demo {
    @Bean
    @ServiceActivator(inputChannel = "OUTPUT_CHANNEL")
    public MessageHandler messageSender(EventHubsTemplate eventhubOperation) {
        DefaultMessageHandler handler = new DefaultMessageHandler("EVENTHUB_NAME", eventhubOperation);
        handler.setSendCallback(new ListenableFutureCallback<Void>() {
            @Override
            public void onSuccess(Void result) {
                LOGGER.info("Message was sent successfully.");
            }

            @Override
            public void onFailure(Throwable ex) {
                LOGGER.error("There was an error sending the message.", ex);
            }
        });

        return handler;
    }
}

从 azure-spring-integration-eventhubs 到 spring-integration-azure-eventhubs

本指南旨在帮助从 azure-spring-integration-eventhubs版本 2 迁移到 spring-integration-azure-eventhubs。

  • 有关 4.0 中更改的概述，请参阅 简介 和 迁移权益 部分。
  • 若要详细了解项目命名中的策略更改，请参阅 命名更改 部分。
  • 若要了解如何对所有 Spring Cloud Azure 库使用一个 BOM，请参阅 BOM 部分。

API 更改

  • 删除 EventHubOperation，订阅函数移动到类 EventHubsMessageListenerContainer，发送函数移动到 EventHubsTemplate。
  • 将 EventHubInboundChannelAdapter 重命名为 EventHubsInboundChannelAdapter，以与 Azure 事件中心的服务保持一致。
  • 将构造函数从 EventHubInboundChannelAdapter(String, SubscribeByGroupOperation, String) 更改为 EventHubsInboundChannelAdapter(EventHubsMessageListenerContainer) 和 EventHubsInboundChannelAdapter(EventHubsMessageListenerContainer, ListenerMode)。
  • 将 CheckpointConfig 实例化样式更改为简单构造函数，而不是生成样式。
  • 删除 API EventHubOperation#setCheckpointConfig。 若要设置入站通道适配器的检查点配置，用户可以调用方法 EventHubsContainerProperties#setCheckpointConfig。
  • 删除 API EventHubOperation#setBatchConsumerConfig。 若要设置入站通道适配器的批处理使用配置，用户可以同时调用两种方法 EventHubsContainerProperties#getBatch#setMaxSize 和 EventHubsContainerProperties#getBatch#setMaxWaitTime。
  • 对于批处理使用模式，请更改从批处理消息转换的消息标头名称。
    • 将消息标头从 azure_eventhub_enqueued_time 更改为 azure_eventhubs_batch_converted_enqueued_time。
    • 将消息标头从 azure_eventhub_offset 更改为 azure_eventhubs_batch_converted_offset。
    • 将消息标头从 azure_eventhub_sequence_number 更改为 azure_eventhubs_batch_converted_sequence_number。
    • 将消息标头从 azure_partition_key 更改为 azure_batch_converted_partition_key。
  • 将消息发布到事件中心时，忽略从批处理消息转换的所有消息标头。 标头包括：
    • azure_batch_converted_partition_key
    • azure_eventhubs_batch_converted_enqueued_time
    • azure_eventhubs_batch_converted_offset
    • azure_eventhubs_batch_converted_sequence_number
    • azure_eventhubs_batch_converted_system_properties
    • azure_eventhubs_batch_converted_application_properties
  • BATCH 检查点模式现在仅适用于批处理使用模式，可通过将 ListenerMode.BATCH 传递给 EventHubsInboundChannelAdapter 构造函数来启用该模式。

下表显示了从 azure-spring-integration-eventhubs 到 spring-integration-azure-eventhubs的类映射：

旧类 新式类
com.azure.spring.integration.core.AzureHeaders com.azure.spring.messaging.AzureHeaders
com.azure.spring.integration.core.EventHubHeaders com.azure.spring.messaging.eventhubs.support.EventHubsHeaders
com.azure.spring.integration.core.api.CheckpointConfig com.azure.spring.messaging.eventhubs.core.checkpoint.CheckpointConfig
com.azure.spring.integration.core.api.CheckpointMode com.azure.spring.messaging.eventhubs.core.checkpoint.CheckpointMode
com.azure.spring.integration.core.api.reactor.Checkpointer com.azure.spring.messaging.checkpoint.Checkpointer
com.azure.spring.integration.core.api.reactor.DefaultMessageHandler com.azure.spring.integration.core.handler.DefaultMessageHandler
com.azure.spring.integration.eventhub.inbound.EventHubInboundChannelAdapter com.azure.spring.integration.eventhubs.inbound.EventHubsInboundChannelAdapter

从 azure-spring-cloud-starter-servicebus 到 spring-cloud-azure-starter-integration-servicebus

本指南旨在帮助从 azure-spring-cloud-starter-servicebus版本 2 迁移到 spring-cloud-starter-integration-servicebus。

有关常规信息，请使用以下链接：

  • 有关 4.0 中更改的概述，请参阅 简介 和 迁移权益 部分。
  • 若要详细了解项目命名中的策略更改，请参阅 命名更改 部分。
  • 若要了解如何对所有 Spring Cloud Azure 库使用一个 BOM，请参阅 BOM 部分。
  • 若要了解如何在 Spring Cloud Azure 4.0 中处理身份验证，请参阅 身份验证更改 部分。
  • 若要了解如何在迁移期间利用 spring-boot-properties-migrator，请参阅 配置每个 SDK 部分。
  • 若要详细了解全局配置和常见配置更改，请参阅 全局配置 部分。

SDK 配置更改

对于 spring-cloud-azure-starter-integration-servicebus中支持的所有配置选项，前缀将保持为 spring.cloud.azure.servicebus。

下表显示了从 azure-spring-cloud-starter-servicebus 到 spring-cloud-azure-starter-integration-servicebus的属性映射：

旧属性 新式属性
spring.cloud.azure.resource-group spring.cloud.azure.servicebus.resource.resource-group
spring.cloud.azure.servicebus.transport-type spring.cloud.azure.servicebus.client.transport-type
spring.cloud.azure.servicebus.retry-options.retry-mode spring.cloud.azure.servicebus.retry.mode
spring.cloud.azure.servicebus.retry-options.max-retries spring.cloud.azure.servicebus.retry.exponential.max-retries 或 spring.cloud.azure.servicebus.retry.fixed.max-retries，应根据 spring.cloud.azure.servicebus.retry.mode=固定 或 指数
spring.cloud.azure.servicebus.retry-options.delay spring.cloud.azure.servicebus.retry.exponential.base-delay 或 spring.cloud.azure.servicebus.retry.fixed.delay，应根据 spring.cloud.azure.servicebus.retry.mode=固定 或 指数
spring.cloud.azure.servicebus.retry-options.max-delay spring.cloud.azure.servicebus.retry.exponential.max-delay
spring.cloud.azure.servicebus.retry-options.try-timeout spring.cloud.azure.servicebus.retry.try-timeout

API 更改

  • 删除 ServiceBusQueueOperation 并 ServiceBusTopicOperation 订阅函数移动到类 ServiceBusMessageListenerContainer，发送函数移动到 ServiceBusTemplate。
  • 删除 ServiceBusQueueInboundChannelAdapter 和 ServiceBusTopicInboundChannelAdapter，并将功能移动到 ServiceBusInboundChannelAdapter 以侦听服务总线队列/主题实体。
  • 将构造函数从 ServiceBusQueueInboundChannelAdapter(String, SubscribeByGroupOperation, String) 更改为 ServiceBusInboundChannelAdapter(ServiceBusMessageListenerContainer) 和 ServiceBusInboundChannelAdapter(ServiceBusMessageListenerContainer, ListenerMode)。
  • 将构造函数从 ServiceBusTopicInboundChannelAdapter(String, SubscribeByGroupOperation, String) 更改为 ServiceBusInboundChannelAdapter(ServiceBusMessageListenerContainer) 和 ServiceBusInboundChannelAdapter(ServiceBusMessageListenerContainer, ListenerMode)。
  • 删除 API ServiceBusQueueOperation#setCheckpointConfig 和 ServiceBusTopicOperation#setCheckpointConfig。 若要设置入站通道适配器的检查点配置，用户可以改为调用方法 ServiceBusContainerProperties#setAutoComplete。 若要禁用自动完成模式，等效于 MANUAL 检查点模式，并启用它将触发 RECORD 模式。
  • 删除 API ServiceBusQueueOperatio#setClientConfig 和 ServiceBusTopicOperation#setClientConfig。 若要配置入站通道适配器使用的基础 ServiceBusProcessorClient，用户可以改用 ServiceBusContainerProperties。
  • 请改为在 ServiceBusTemplate 和 DefaultMessageHandler中删除 CompletableFuture 支持，以支持 Reactor。
  • 添加新的 ServiceBusTemplate#setDefaultEntityType API 以指定实体类型，当没有为 ProducerProperties#entityType提供 PropertiesSupplier&lt;String, ProducerProperties&gt; 豆时，该类型是必需的。
  • 删除消息头 AzureHeaders.RAW_ID。 请改用 ServiceBusMessageHeaders.MESSAGE_ID。

下表显示了从 azure-spring-cloud-starter-servicebus 到 spring-cloud-azure-starter-integration-servicebus的类映射：

旧类 新式类
com.azure.spring.integration.core.AzureHeaders com.azure.spring.messaging.AzureHeaders
com.azure.spring.integration.servicebus.converter.ServiceBusMessageHeaders com.azure.spring.messaging.servicebus.support.ServiceBusMessageHeaders
com.azure.spring.integration.servicebus.converter.ServiceBusMessageConverter com.azure.spring.messaging.servicebus.support.converter.ServiceBusMessageConverter
com.azure.spring.integration.core.DefaultMessageHandler com.azure.spring.integration.core.handler.DefaultMessageHandler
com.azure.spring.integration.servicebus.inbound.ServiceBusQueueInboundChannelAdapter com.azure.spring.integration.servicebus.inbound.ServiceBusInboundChannelAdapter
com.azure.spring.integration.servicebus.inbound.ServiceBusTopicInboundChannelAdapter com.azure.spring.integration.servicebus.inbound.ServiceBusInboundChannelAdapter

示例代码片段

  • ServiceBusInboundChannelAdapter 示例代码：

    使用 ServiceBusQueueInboundChannelAdapter 或 ServiceBusTopicInboundChannelAdapter的旧代码：

    public class Demo {
    @Bean
    public ServiceBusQueueInboundChannelAdapter queueMessageChannelAdapter(
        @Qualifier("INPUT_CHANNEL_NAME") MessageChannel inputChannel, ServiceBusQueueOperation queueOperation) {
        queueOperation.setCheckpointConfig(CheckpointConfig.builder().checkpointMode(CheckpointMode.MANUAL).build());
        ServiceBusQueueInboundChannelAdapter adapter = new ServiceBusQueueInboundChannelAdapter("QUEUE_NAME",
            queueOperation);
        adapter.setOutputChannel(inputChannel);
        return adapter;
    }

    @Bean
    public ServiceBusTopicInboundChannelAdapter topicMessageChannelAdapter(
        @Qualifier("INPUT_CHANNEL_NAME") MessageChannel inputChannel, ServiceBusTopicOperation topicOperation) {
        topicOperation.setCheckpointConfig(CheckpointConfig.builder().checkpointMode(CheckpointMode.MANUAL).build());
        ServiceBusTopicInboundChannelAdapter adapter = new ServiceBusTopicInboundChannelAdapter("TOPIC_NAME",
            topicOperation, "SUBSCRIPTION_NAME");
        adapter.setOutputChannel(inputChannel);
        return adapter;
    }

}

    新式代码：

    public class Demo {
    @Bean("queue-listener-container")
    public ServiceBusMessageListenerContainer messageListenerContainer(ServiceBusProcessorFactory processorFactory) {
        ServiceBusContainerProperties containerProperties = new ServiceBusContainerProperties();
        containerProperties.setEntityName("QUEUE_NAME");
        containerProperties.setAutoComplete(false);
        return new ServiceBusMessageListenerContainer(processorFactory, containerProperties);
    }

    @Bean
    public ServiceBusInboundChannelAdapter queueMessageChannelAdapter(
        @Qualifier("INPUT_CHANNEL") MessageChannel inputChannel,
        @Qualifier("queue-listener-container") ServiceBusMessageListenerContainer listenerContainer) {
        ServiceBusInboundChannelAdapter adapter = new ServiceBusInboundChannelAdapter(listenerContainer);
        adapter.setOutputChannel(inputChannel);
        return adapter;
    }

    @Bean("topic-listener-container")
    public ServiceBusMessageListenerContainer messageListenerContainer(ServiceBusProcessorFactory processorFactory) {
        ServiceBusContainerProperties containerProperties = new ServiceBusContainerProperties();
        containerProperties.setEntityName("TOPIC_NAME");
        containerProperties.setSubscriptionName("SUBSCRIPTION_NAME");
        containerProperties.setAutoComplete(false);
        return new ServiceBusMessageListenerContainer(processorFactory, containerProperties);
    }

    @Bean
    public ServiceBusInboundChannelAdapter topicMessageChannelAdapter(
        @Qualifier("INPUT_CHANNEL") MessageChannel inputChannel,
        @Qualifier("topic-listener-container") ServiceBusMessageListenerContainer listenerContainer) {
        ServiceBusInboundChannelAdapter adapter = new ServiceBusInboundChannelAdapter(listenerContainer);
        adapter.setOutputChannel(inputChannel);
        return adapter;
    }
}

  • DefaultMessageHandler 示例代码：

    旧代码，以队列为例：

    public class Demo {
    @Bean
    @ServiceActivator(inputChannel = "OUTPUT_CHANNEL_NAME")
    public MessageHandler queueMessageSender(ServiceBusQueueOperation queueOperation) {
        DefaultMessageHandler handler = new DefaultMessageHandler("QUEUE_NAME", queueOperation);
        handler.setSendCallback(new ListenableFutureCallback<Void>() {
            @Override
            public void onSuccess(Void result) {
                LOGGER.info("Message was sent successfully.");
            }
            @Override
            public void onFailure(Throwable ex) {
                LOGGER.info("There was an error sending the message.");
            }
        });
        return handler;
    }
}

    新式代码：

    public class Demo {

    @Bean
    @ServiceActivator(inputChannel = "OUTPUT_CHANNEL_NAME")
    public MessageHandler queueMessageSender(ServiceBusTemplate serviceBusTemplate) {
        serviceBusTemplate.setDefaultEntityType(ServiceBusEntityType.QUEUE);
        DefaultMessageHandler handler = new DefaultMessageHandler("QUEUE_NAME", serviceBusTemplate);
        handler.setSendCallback(new ListenableFutureCallback<Void>() {
            @Override
            public void onSuccess(Void result) {
                LOGGER.info("Message was sent successfully for {}.", "QUEUE_NAME");
            }

            @Override
            public void onFailure(Throwable ex) {
                LOGGER.info("There was an error sending the message.");
            }
        });

        return handler;
    }
}

从 azure-spring-integration-servicebus 到 spring-integration-azure-servicebus

本指南旨在帮助从 azure-spring-integration-servicebus版本 2 迁移到 spring-integration-azure-servicebus。

  • 有关 4.0 中更改的概述，请参阅 简介 和 迁移权益 部分。
  • 若要详细了解项目命名中的策略更改，请参阅 命名更改 部分。
  • 若要了解如何对所有 Spring Cloud Azure 库使用一个 BOM，请参阅 BOM 部分。

API 更改

  • 删除 ServiceBusQueueOperation 并 ServiceBusTopicOperation 订阅函数移动到类 ServiceBusMessageListenerContainer，发送函数移动到 ServiceBusTemplate。
  • 删除 ServiceBusQueueInboundChannelAdapter 和 ServiceBusTopicInboundChannelAdapter，并将功能移动到 ServiceBusInboundChannelAdapter 以侦听服务总线队列/主题实体。
  • 将构造函数从 ServiceBusQueueInboundChannelAdapter(String, SubscribeByGroupOperation, String) 更改为 ServiceBusInboundChannelAdapter(ServiceBusMessageListenerContainer) 和 ServiceBusInboundChannelAdapter(ServiceBusMessageListenerContainer, ListenerMode)。
  • 将构造函数从 ServiceBusTopicInboundChannelAdapter(String, SubscribeByGroupOperation, String) 更改为 ServiceBusInboundChannelAdapter(ServiceBusMessageListenerContainer) 和 ServiceBusInboundChannelAdapter(ServiceBusMessageListenerContainer, ListenerMode)。
  • 删除 API ServiceBusQueueOperation#setCheckpointConfig 和 ServiceBusTopicOperation#setCheckpointConfig。 若要设置入站通道适配器的检查点配置，用户可以改为调用方法 ServiceBusContainerProperties#setAutoComplete。 若要禁用自动完成模式，等效于 MANUAL 检查点模式，并启用它将触发 RECORD 模式。
  • 删除 API ServiceBusQueueOperation#setClientConfig 和 ServiceBusTopicOperation#setClientConfig。 若要配置入站通道适配器使用的基础 ServiceBusProcessorClient，用户可以改用 ServiceBusContainerProperties。
  • 请改为在 ServiceBusTemplate 和 DefaultMessageHandler中删除 CompletableFuture 支持，以支持 Reactor。
  • 添加新的 ServiceBusTemplate#setDefaultEntityType API 以指定实体类型，当没有为 ProducerProperties#entityType提供 PropertiesSupplier&lt;String, ProducerProperties&gt; 豆时，该类型是必需的。
  • 删除消息头 AzureHeaders.RAW_ID。 请改用 ServiceBusMessageHeaders.MESSAGE_ID。

下表显示了从 azure-spring-integration-servicebus 到 spring-integration-azure-servicebus的类映射：

旧类 新式类
com.azure.spring.integration.core.AzureHeaders com.azure.spring.messaging.AzureHeaders
com.azure.spring.integration.servicebus.converter.ServiceBusMessageHeaders com.azure.spring.messaging.servicebus.support.ServiceBusMessageHeaders
com.azure.spring.integration.servicebus.converter.ServiceBusMessageConverter com.azure.spring.messaging.servicebus.support.converter.ServiceBusMessageConverter
com.azure.spring.integration.core.DefaultMessageHandler com.azure.spring.integration.core.handler.DefaultMessageHandler
com.azure.spring.integration.servicebus.inbound.ServiceBusQueueInboundChannelAdapter com.azure.spring.integration.servicebus.inbound.ServiceBusInboundChannelAdapter
com.azure.spring.integration.servicebus.inbound.ServiceBusTopicInboundChannelAdapter com.azure.spring.integration.servicebus.inbound.ServiceBusInboundChannelAdapter

从 azure-spring-cloud-starter-storage-queue 到 spring-cloud-azure-starter-integration-storage-queue

本指南旨在帮助从 azure-spring-cloud-starter-storage-queue版本 2 迁移到 spring-cloud-starter-integration-storage-queue。

有关常规信息，请使用以下链接：

  • 有关 4.0 中更改的概述，请参阅 简介 和 迁移权益 部分。
  • 若要详细了解项目命名中的策略更改，请参阅 命名更改 部分。
  • 若要了解如何对所有 Spring Cloud Azure 库使用一个 BOM，请参阅 BOM 部分。
  • 若要了解如何在 Spring Cloud Azure 4.0 中处理身份验证，请参阅 身份验证更改 部分。
  • 若要了解如何在迁移期间利用 spring-boot-properties-migrator，请参阅 配置每个 SDK 部分。
  • 若要详细了解全局配置和常见配置更改，请参阅 全局配置 部分。

SDK 配置更改

所有配置属性名称将前缀从 spring.cloud.azure.storage 更改为 spring.cloud.azure.storage.queue。

下表显示了从 azure-spring-cloud-starter-storage-queue 到 spring-cloud-azure-starter-integration-storage-queue的属性映射：

旧属性 新式属性
spring.cloud.azure.storage.account spring.cloud.azure.storage.queue.account-name
spring.cloud.azure.storage.access-key spring.cloud.azure.storage.queue.account-key
spring.cloud.azure.storage.resource-group spring.cloud.azure.storage.queue.resource.resource-group

API 更改

  • 请删除 StorageQueueOperation 并提供 StorageQueueTemplate。
  • 在 StorageQueueTemplate中删除 checkpoint-mode 配置，仅支持 MANUAL 模式。

下表显示了从 azure-spring-cloud-starter-storage-queue 到 spring-cloud-azure-starter-integration-storage-queue的类映射。

旧类 新式类
com.azure.spring.integration.core.AzureHeaders com.azure.spring.messaging.AzureHeaders
com.azure.spring.integration.storage.queue.converter.StorageQueueMessageConverter com.azure.spring.messaging.storage.queue.support.converter.StorageQueueMessageConverter
com.azure.spring.integration.core.api.reactor.Checkpointer com.azure.spring.messaging.checkpoint.Checkpointer
com.azure.spring.integration.storage.queue.StorageQueueTemplate com.azure.spring.storage.queue.core.StorageQueueTemplate
com.azure.spring.integration.core.api.reactor.DefaultMessageHandler com.azure.spring.integration.core.handler.DefaultMessageHandler
com.azure.spring.integration.storage.queue.inbound.StorageQueueMessageSource com.azure.spring.integration.storage.queue.inbound.StorageQueueMessageSource

从 azure-spring-integration-storage-queue 到 spring-integration-azure-storage-queue

本指南旨在帮助从 azure-spring-integration-storage-queue版本 2 迁移到 spring-integration-azure-storage-queue。

  • 有关 4.0 中更改的概述，请参阅 简介 和 迁移权益 部分。
  • 若要详细了解项目命名中的策略更改，请参阅 命名更改 部分。
  • 若要了解如何对所有 Spring Cloud Azure 库使用一个 BOM，请参阅 BOM 部分。

API 更改

  • 请删除 StorageQueueOperation 并提供 StorageQueueTemplate。
  • 在 StorageQueueTemplate中删除 checkpoint-mode 配置，仅支持 MANUAL 模式。

下表显示了从 azure-spring-integration-storage-queue 到 spring-integration-azure-storage-queue的类映射。

旧类 新式类
com.azure.spring.integration.core.AzureHeaders com.azure.spring.messaging.AzureHeaders
com.azure.spring.integration.storage.queue.converter.StorageQueueMessageConverter com.azure.spring.messaging.storage.queue.support.converter.StorageQueueMessageConverter
com.azure.spring.integration.core.api.reactor.Checkpointer com.azure.spring.messaging.checkpoint.Checkpointer
com.azure.spring.integration.storage.queue.StorageQueueTemplate com.azure.spring.storage.queue.core.StorageQueueTemplate
com.azure.spring.integration.core.api.reactor.DefaultMessageHandler com.azure.spring.integration.core.handler.DefaultMessageHandler
com.azure.spring.integration.storage.queue.inbound.StorageQueueMessageSource com.azure.spring.integration.storage.queue.inbound.StorageQueueMessageSource

从 azure-spring-cloud-stream-binder-eventhubs 到 spring-cloud-azure-stream-binder-eventhubs

本指南旨在帮助从 azure-spring-cloud-stream-binder-eventhubs版本 2 迁移到 spring-cloud-stream-binder-eventhubs。

有关常规信息，请使用以下链接：

  • 有关 4.0 中更改的概述，请参阅 简介 和 迁移权益 部分。
  • 若要详细了解项目命名中的策略更改，请参阅 命名更改 部分。
  • 若要了解如何对所有 Spring Cloud Azure 库使用一个 BOM，请参阅 BOM 部分。
  • 若要了解如何在 Spring Cloud Azure 4.0 中处理身份验证，请参阅 身份验证更改 部分。
  • 若要了解如何在迁移期间利用 spring-boot-properties-migrator，请参阅 配置每个 SDK 部分。
  • 若要详细了解全局配置和常见配置更改，请参阅 全局配置 部分。

SDK 配置更改

重要

配置前缀已从 spring.cloud.azure.eventhub 更改为 spring.cloud.azure.eventhubs.

重要

绑定器类型已从：eventhub 重命名为 eventhubs。

有关对以下前缀的子项的更改，请参阅下表。

下表显示了从 azure-spring-cloud-stream-binder-eventhubs 到 spring-cloud-azure-stream-binder-eventhubs的属性映射：

旧属性 新式属性
spring.cloud.azure.resource-group spring.cloud.azure.eventhubs.resource.resource-group
spring.cloud.azure.eventhub.namespace spring.cloud.azure.eventhubs.namespace
spring.cloud.azure.eventhub.connection-string spring.cloud.azure.eventhubs.connection-string
spring.cloud.azure.eventhub.checkpoint-storage-account spring.cloud.azure.eventhubs.processor.checkpoint-store.account-name
spring.cloud.azure.eventhub.checkpoint-access-key spring.cloud.azure.eventhubs.processor.checkpoint-store.account-key
spring.cloud.azure.eventhub.checkpoint-container spring.cloud.azure.eventhubs.processor.checkpoint-store.container-name
spring.cloud.stream.eventhub.bindings.binding-name.consumer.max-batch-size spring.cloud.stream.eventhubs.bindings.binding-name.consumer.batch.max-size
spring.cloud.stream.eventhub.bindings.binding-name.consumer.max-wait-time spring.cloud.stream.eventhubs.bindings.binding-name.consumer.batch.max-wait-time
spring.cloud.stream.eventhub.bindings.binding-name.consumer.checkpoint-mode spring.cloud.stream.eventhubs.bindings.binding-name.consumer.checkpoint.mode
spring.cloud.stream.eventhub.bindings.binding-name.consumer.checkpoint-count spring.cloud.stream.eventhubs.bindings.binding-name.consumer.checkpoint.count
spring.cloud.stream.eventhub.bindings.binding-name.consumer.checkpoint-interval spring.cloud.stream.eventhubs.bindings.binding-name.consumer.checkpoint.interval
spring.cloud.stream.eventhub.bindings.binding-name.consumer.start-position spring.cloud.stream.eventhubs.bindings.binding-name.consumer.initial-partition-event-position

注意

start-position 配置的值类型也从 com.azure.spring.integration.core.api.StartPosition 枚举更改为每个分区的 StartPositionPropertiesmap。 因此，键是分区 ID，值是 com.azure.spring.cloud.service.eventhubs.properties.StartPositionProperties，其中包括偏移量、序列号、排队日期时间和是否非独占的属性。

配置迁移示例

若要使用连接字符串进行身份验证并迁移上述属性，请列出配置更改，如下所示：

旧配置：

spring:
  cloud:
    azure:
      eventhub:
        connection-string: ${AZURE_EVENTHUBS_CONNECTION_STRING}
        checkpoint-storage-account: ${AZURE_CHECKPOINT_STORAGE_ACCOUNT_NAME}
        checkpoint-access-key: ${AZURE_CHECKPOINT_ACCOUNT_KEY}
        checkpoint-container: ${AZURE_CHECKPOINT_CONTAINER_NAME}
    stream:
      eventhub:
        bindings:
          <binding-name>:
            consumer:
              max-batch-size: ${AZURE_MAX_BATCH_SIZE}
              max-wait-time: ${AZURE_MAX_WAIT_TIME}
              checkpoint-mode: ${AZURE_CHECKPOINT_MODE}
              checkpoint-count: ${AZURE_CHECKPOINT_COUNT}
              checkpoint-interval: ${AZURE_CHECKPOINT_INTERVAL}
              start-position: EARLIEST

新式配置：

spring:
  cloud:
    azure:
      eventhubs:
        connection-string: ${AZURE_EVENTHUBS_CONNECTION_STRING}
        processor:
          checkpoint-store:
            container-name: ${AZURE_STORAGE_CONTAINER_NAME}
            account-name:  ${AZURE_STORAGE_ACCOUNT_NAME}
            account-key: ${AZURE_STORAGE_ACCOUNT_KEY}
    stream:
      eventhubs:
        bindings:
          <binding-name>:
            consumer:
              batch:
                max-size: ${AZURE_MAX_BATCH_SIZE}
                max-wait-time: ${AZURE_MAX_WAIT_TIME}
              checkpoint:
                mode: ${AZURE_CHECKPOINT_MODE}
                count: ${AZURE_CHECKPOINT_COUNT}
                interval: ${AZURE_CHECKPOINT_INTERVAL}
              initial-partition-event-position:
                0:
                  offset: earliest
                1:
                  sequence-number: 100
                2:
                  enqueued-date-time: 2022-01-12T13:32:47.650005Z
                4:
                  inclusive: false

如果使用安全主体而不是连接字符串，则在 4.0 之前的版本中，应用程序将首先使用提供的安全主体连接到 Azure 资源管理器（ARM），然后使用 ARM 检索指定命名空间的连接字符串。 最后，应用程序使用检索到的连接字符串连接到 Azure 事件中心。 这样，应向提供的安全主体授予 参与者 角色，以检索关联的 Azure 事件中心命名空间。

对于 Azure Spring Apps 4.0，我们提供了两种方法来利用安全主体进行身份验证。 其中一个仍在使用主体连接到 ARM，并检索主体需要 Contributor 角色的连接字符串。 另一个利用安全主体进行身份验证以Microsoft Entra ID，然后直接连接到 Azure 事件中心。 在这种情况下，不再需要 Contributor 角色，而消息传递操作需要其他 Data 相关角色。 若要确保安全主体已授予访问 Azure 资源的足够权限，请参阅 使用 Microsoft Entra ID授权访问。

对于基于 ARM 的身份验证，以服务主体为例，配置迁移如下所示，其中分配的角色不应更改：

旧配置：

spring:
  cloud:
    azure:
      client-id: ${AZURE_CLIENT_ID}
      client-secret: ${AZURE_CLIENT_SECRET}
      tenant-id: <tenant>
      resource-group: ${EVENTHUB_RESOURCE_GROUP}
      eventhub:
        namespace: ${EVENTHUB_NAMESPACE}

注意

允许 tenant-id 的值包括：common、organizations、consumers或租户 ID。 有关这些值的详细信息，请参阅 使用错误的终结点（个人和组织帐户）错误AADSTS50020 - 租户中不存在来自标识提供者的用户帐户。 有关转换单租户应用的信息，请参阅 在 Microsoft Entra ID上将单租户应用转换为多租户。

新式配置、Azure 订阅 ID 和资源组的属性是必需的：

spring:
  cloud:
    azure:
      credential:
        client-id: ${AZURE_CLIENT_ID}
        client-secret: ${AZURE_CLIENT_SECRET}
      profile:
        tenant-id: <tenant>
        subscription-id: ${AZURE_SUBSCRIPTION_ID}
      eventhubs:
        namespace: ${EVENTHUB_NAMESPACE}
        resource:
          resource-group: ${RESOURCE_GROUP}

注意

允许 tenant-id 的值包括：common、organizations、consumers或租户 ID。 有关这些值的详细信息，请参阅 使用错误的终结点（个人和组织帐户）错误AADSTS50020 - 租户中不存在来自标识提供者的用户帐户。 有关转换单租户应用的信息，请参阅 在 Microsoft Entra ID上将单租户应用转换为多租户。

还可以直接迁移到使用 Microsoft Entra ID 进行身份验证和授权，而无需前往 ARM。 请确保向安全主体授予消息传送操作所需的 Data 角色。 下面列出了服务主体和托管标识的配置示例：

  • 使用服务主体

    spring:
  cloud:
    azure:
      credential:
        client-id: ${AZURE_CLIENT_ID}
        client-secret: ${AZURE_CLIENT_SECRET}
      profile:
        tenant-id: <tenant>
      eventhubs:
        namespace: ${EVENTHUB_NAMESPACE}

注意

允许 tenant-id 的值包括：common、organizations、consumers或租户 ID。 有关这些值的详细信息，请参阅 使用错误的终结点（个人和组织帐户）错误AADSTS50020 - 租户中不存在来自标识提供者的用户帐户。 有关转换单租户应用的信息，请参阅 在 Microsoft Entra ID上将单租户应用转换为多租户。

  • 使用托管标识

    spring:
  cloud:
    azure:
      credential:
        managed-identity-enabled: true
        client-id: ${AZURE_MANAGED_IDENTITY_CLIENT_ID} # Only needed when using a user-assigned managed identity
      eventhubs:
        namespace: ${EVENTHUB_NAMESPACE}

API 更改

下表显示了从 azure-spring-cloud-stream-binder-eventhubs 到 spring-cloud-azure-stream-binder-eventhubs的类映射。

旧类 新式类
com.azure.spring.integration.core.api.reactor.Checkpointer com.azure.spring.messaging.checkpoint.Checkpointer
com.azure.spring.integration.core.AzureHeaders com.azure.spring.messaging.AzureHeaders
com.azure.spring.integration.core.EventHubHeaders com.azure.spring.messaging.eventhubs.support.EventHubsHeaders

从 azure-spring-cloud-stream-binder-servicebus-* 到 spring-cloud-azure-stream-binder-servicebus

本指南旨在帮助从 azure-spring-cloud-stream-binder-servicebus-queue 或 azure-spring-cloud-stream-binder-servicebus-topic版本 2 迁移到 spring-cloud-stream-binder-servicebus-topic。

有关常规信息，请使用以下链接：

  • 有关 4.0 中更改的概述，请参阅 简介 和 迁移权益 部分。
  • 若要详细了解项目命名中的策略更改，请参阅 命名更改 部分。
  • 若要了解如何对所有 Spring Cloud Azure 库使用一个 BOM，请参阅 BOM 部分。
  • 若要了解如何在 Spring Cloud Azure 4.0 中处理身份验证，请参阅 身份验证更改 部分。
  • 若要了解如何在迁移期间利用 spring-boot-properties-migrator，请参阅 配置每个 SDK 部分。
  • 若要详细了解全局配置和常见配置更改，请参阅 全局配置 部分。

SDK 配置更改

重要

旧绑定程序库是 azure-spring-cloud-stream-binder-servicebus-queue 和 azure-spring-cloud-stream-binder-servicebus-topic，现在它们合并为一个 spring-cloud-azure-stream-binder-servicebus。

重要

绑定器类型从 servicebus-queue 和 servicebus-topic 合并为 servicebus。

下表列出了 spring-cloud-azure-stream-binder-servicebus的新配置属性：

新式属性 描述
spring.cloud.stream.servicebus.bindings.binding-name.producer.entity-type 如果使用发送函数，则需要设置实体类型，该类型可以设置为主题或队列。

下表显示了从 azure-spring-cloud-stream-binder-servicebus-* 到 spring-cloud-azure-stream-binder-servicebus的属性映射：

旧属性 新式属性
spring.cloud.azure.resource-group spring.cloud.azure.servicebus.resource.resource-group
spring.cloud.azure.servicebus.transport-type spring.cloud.azure.servicebus.client.transport-type
spring.cloud.azure.servicebus.retry-options.retry-mode spring.cloud.azure.servicebus.retry.mode
spring.cloud.azure.servicebus.retry-options.max-retries spring.cloud.azure.servicebus.retry.exponential.max-retries 或 spring.cloud.azure.servicebus.retry.fixed.max-retries，应根据 spring.cloud.azure.servicebus.retry.mode=固定 或 指数
spring.cloud.azure.servicebus.retry-options.delay spring.cloud.azure.servicebus.retry.exponential.base-delay 或 spring.cloud.azure.servicebus.retry.fixed.delay，应根据 spring.cloud.azure.servicebus.retry.mode=固定 或 指数
spring.cloud.azure.servicebus.retry-options.max-delay spring.cloud.azure.servicebus.retry.exponential.max-delay
spring.cloud.azure.servicebus.retry-options.try-timeout spring.cloud.azure.servicebus.retry.try-timeout
spring.cloud.stream.servicebus.queue.bindings.* spring.cloud.stream.servicebus.bindings.*
spring.cloud.stream.servicebus.queue.bindings.binding-name.consumer。并发 spring.cloud.stream.servicebus.bindings.binding-name.consumer.max-concurrent-sessions/max-concurrent-calls
spring.cloud.stream.servicebus.queue.bindings.binding-name.consumer。检查点模式 spring.cloud.stream.servicebus.bindings.binding-name.consumer。自动完成
spring.cloud.stream.servicebus.topic.bindings.* spring.cloud.stream.servicebus.bindings.*
spring.cloud.stream.servicebus.topic.bindings.binding-name.consumer。并发 spring.cloud.stream.servicebus.bindings.binding-name.consumer.max-concurrent-sessions/max-concurrent-calls
spring.cloud.stream.servicebus.topic.bindings.binding-name.consumer。检查点模式 spring.cloud.stream.servicebus.bindings.binding-name.consumer。自动完成

注意

当 sessionsEnabled 为 true 时，并发属性将由 maxConcurrentSessions 替换，当 sessionsEnabled false时，maxConcurrentCalls 将替换。

注意

启用自动完成与 RECORD 检查点模式相同，与 MANUAL 模式相反。

配置迁移示例

旧配置，以队列为例：

spring:
  cloud:
    azure:
      servicebus:
        connection-string: ${AZURE_SERVICEBUS_BINDER_CONNECTION_STRING}
    stream:
      function:
        definition: consume;supply
      bindings:
        consume-in-0:
          destination: ${AZURE_SERVICEBUS_QUEUE_NAME}
        supply-out-0:
          destination: ${AZURE_SERVICEBUS_QUEUE_NAME}
      servicebus:
        queue:
          bindings:
            consume-in-0:
              consumer:
                checkpoint-mode: MANUAL

新式配置：

spring:
  cloud:
    azure:
      servicebus:
        connection-string: ${AZURE_SERVICEBUS_BINDER_CONNECTION_STRING}
    stream:
      function:
        definition: consume;supply
      bindings:
        consume-in-0:
          destination: ${AZURE_SERVICEBUS_QUEUE_NAME}
        supply-out-0:
          destination: ${AZURE_SERVICEBUS_QUEUE_NAME}
      servicebus:
        bindings:
          consume-in-0:
            consumer:
              auto-complete: false
          supply-out-0:
            producer:
              entity-type: queue #set as topic if needed

如果使用安全主体而不是连接字符串，则在 4.0 之前的版本中，应用程序将首先使用提供的安全主体连接到 Azure 资源管理器（ARM），然后使用 ARM 检索指定命名空间的连接字符串。 最后，应用程序使用检索到的连接字符串连接到 Azure 服务总线。 这样，应向提供的安全主体授予 参与者 角色，以检索关联的 Azure 服务总线命名空间。

对于 Azure Spring Apps 4.0，我们提供了两种方法来利用安全主体进行身份验证。 其中一个仍在使用主体连接到 ARM，并检索主体需要 Contributor 角色的连接字符串。 另一个利用安全主体进行身份验证以Microsoft Entra ID，然后直接连接到 Azure 服务总线。 在这种情况下，不再需要 Contributor 角色，而消息传递操作需要其他 Data 相关角色。 若要确保安全主体已授予访问 Azure 资源的足够权限，请参阅 使用 Microsoft Entra ID授权访问。

对于基于 ARM 的身份验证，以服务主体为例，配置迁移如下所示，其中分配的角色不应更改：

旧配置：

spring:
  cloud:
    azure:
      client-id: ${AZURE_CLIENT_ID}
      client-secret: ${AZURE_CLIENT_SECRET}
      tenant-id: <tenant>
      resource-group: ${SERVICEBUS_RESOURCE_GROUP}
      servicebus:
        namespace: ${SERVICEBUS_NAMESPACE}

注意

允许 tenant-id 的值包括：common、organizations、consumers或租户 ID。 有关这些值的详细信息，请参阅 使用错误的终结点（个人和组织帐户）错误AADSTS50020 - 租户中不存在来自标识提供者的用户帐户。 有关转换单租户应用的信息，请参阅 在 Microsoft Entra ID上将单租户应用转换为多租户。

新式配置、Azure 订阅 ID 和资源组的属性是必需的：

spring:
  cloud:
    azure:
      credential:
        client-id: ${AZURE_CLIENT_ID}
        client-secret: ${AZURE_CLIENT_SECRET}
      profile:
        tenant-id: <tenant>
        subscription-id: ${AZURE_SUBSCRIPTION_ID}
      servicebus:
        namespace: ${SERVICEBUS_NAMESPACE}
        resource:
          resource-group: ${SERVICEBUS_RESOURCE_GROUP}

注意

允许 tenant-id 的值包括：common、organizations、consumers或租户 ID。 有关这些值的详细信息，请参阅 使用错误的终结点（个人和组织帐户）错误AADSTS50020 - 租户中不存在来自标识提供者的用户帐户。 有关转换单租户应用的信息，请参阅 在 Microsoft Entra ID上将单租户应用转换为多租户。

还可以直接迁移到使用 Microsoft Entra ID 进行身份验证和授权，而无需前往 ARM。 请确保向安全主体授予消息传送操作所需的 Data 角色。 下面列出了服务主体和托管标识的配置示例：

  • 使用服务主体

    spring:
  cloud:
    azure:
      credential:
        client-id: ${AZURE_CLIENT_ID}
        client-secret: ${AZURE_CLIENT_SECRET}
      profile:
        tenant-id: <tenant>
      servicebus:
        namespace: ${SERVICEBUS_NAMESPACE}

注意

允许 tenant-id 的值包括：common、organizations、consumers或租户 ID。 有关这些值的详细信息，请参阅 使用错误的终结点（个人和组织帐户）错误AADSTS50020 - 租户中不存在来自标识提供者的用户帐户。 有关转换单租户应用的信息，请参阅 在 Microsoft Entra ID上将单租户应用转换为多租户。

  • 使用托管标识

    spring:
  cloud:
    azure:
      credential:
        managed-identity-enabled: true
        client-id: ${AZURE_MANAGED_IDENTITY_CLIENT_ID} # Only needed when using a user-assigned   managed identity
      servicebus:
        namespace: ${SERVICEBUS_NAMESPACE}

API 更改

  • 删除消息头 AzureHeaders.RAW_ID。 请改用 ServiceBusMessageHeaders.MESSAGE_ID。

下表显示了从 azure-spring-cloud-stream-binder-eventhubs 到 spring-cloud-azure-stream-binder-eventhubs的类映射。

旧类 新式类
com.azure.spring.integration.core.AzureHeaders com.azure.spring.messaging.AzureHeaders
com.azure.spring.integration.servicebus.converter.ServiceBusMessageHeaders com.azure.spring.messaging.servicebus.support.ServiceBusMessageHeaders
com.azure.spring.integration.core.api.Checkpointer com.azure.spring.messaging.checkpoint.Checkpointer

azure-spring-cloud-messaging

com.azure.spring:azure-spring-cloud-messaging 库尚未准备好 4.0。 侦听器注释的功能正在重新设计中，因此目前不支持 @AzureMessageListener、@AzureMessageListeners和 @EnableAzureMessaging 批注。