Spring Cloud Azure 4.0 的迁移指南

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

介绍

我们将调用其组 ID 和项目 ID 遵循新式库模式的库,以及具有模式com.azure.spring:spring-cloud-azure-*com.azure.spring:azure-spring-cloud-*com.azure.spring:azure-spring-boot-*的库或com.azure.spring:azure-spring-integration-*库。

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

假定熟悉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 的命名更改
  • 项目更改:已重命名/已添加/已删除
  • 依赖项更改
  • 身份验证更改
  • 配置属性
  • APIAPI 中断性变更
  • 库更改

命名变更

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

物料清单

我们曾经为库提供两个 BOM,azure-spring-boot-bomazure-spring-cloud-dependencies但从 4.0 spring-cloud-azure-dependencies开始,我们将这两个 BOM 合并为一个 BOM。 在项目的节中添加 dependencyManagement 一个条目,以便从依赖项管理中受益。

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

注意

如果使用 Spring Boot 3.x,请确保将 spring-cloud-azure-dependencies 版本设置为 5.8.0。 有关该 spring-cloud-azure-dependencies 版本的详细信息,请参阅 我应使用哪个版本的 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 与 存储 Queue 配合使用。
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-eventhubsspring-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 事件中心/服务总线 Binder 库,Contributor当需要自动创建资源的功能时,需要角色。 有关详细信息,请参阅 Azure 内置角色

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

配置属性

属性迁移

我们创建了一个 附加的 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不支持此功能。 全局配置可以分为五个类别,如下表所示:

Prefix 说明
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 级别的配置选项的详细信息,请使用以下链接:

APIAPI 中断性变更

有关每个库中 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-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-directoryspring-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
  • 以下属性的值类型从longDuration以下属性更改为:

    • 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-endpointspring.cloud.azure.active-directory.user-group.use-transitive-members。 第一个属性用于指定主机名,第二个用于使用 URL 路径的标志: v1.0/me/memberOfv1.0/me/transitiveMemberOf

下面是迁移的一些示例:

  • 示例 1。 Case 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。 Case 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-directoryspring-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-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-b2cspring-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
  • 以下属性的值类型从longDuration以下属性更改为:

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

API 更改

下表显示了从azure-spring-boot-starter-active-directory-b2cspring-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-cosmosspring-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-secretsspring-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-enabledspring.cloud.azure.keyvault.secret.property-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用于启用所有密钥库机密功能,包括配置密钥库机密客户端豆类(如SecretClient和)和加载项KeyVaultPropertySourceConfigurableEnvironmentSecretAsyncClient
  3. spring.cloud.azure.keyvault.secret.property-source-enabled 用于启用所有 KeyVaultPropertySource。 仅当 .spring.cloud.azure.keyvault.secret.enabled=true
  4. 对于 Azure 通用属性(如client、、retryproxy、)profilecredential和密钥库属性(如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-timeoutlong(毫秒)更改为 Duration 模式的配置类型,以便实现可读性。

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

本指南旨在帮助从 azure-spring-boot-starter-storage-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-storagespring-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-endpoint spring.cloud.azure.storage.blob.endpoint

API 更改

下表显示了从azure-spring-boot-starter-storagespring-cloud-azure-starter-storage-blob以下项到的类映射:

旧类 新式类
com.azure.spring.autoconfigure.storage.resource.Azure存储ProtocolResolver com.azure.spring.core.resource.Azure存储BlobProtocolResolver
com.azure.spring.autoconfigure.storage.resource.Blob存储Resource com.azure.spring.core.resource。存储BlobResource
com.azure.spring.autoconfigure.storage.resource.Azure存储ResourcePatternResolver com.azure.spring.core.resource.Azure存储BlobProtocolResolver

从 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-storagespring-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-storagespring-cloud-azure-starter-storage-file-share以下项到的类映射:

旧类 新式类
com.azure.spring.autoconfigure.storage.resource.Azure存储ProtocolResolver com.azure.spring.core.resource.Azure存储FileProtocolResolver
com.azure.spring.autoconfigure.storage.resource.File存储Resource com.azure.spring.core.resource。存储FileResource
com.azure.spring.autoconfigure.storage.resource.Azure存储ResourcePatternResolver com.azure.spring.core.resource.Azure存储FileProtocolResolver

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

本指南旨在帮助从 azure-spring-cloud-starter-eventhub 版本 2 迁移到 spring-cloud-starter-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-eventhubsspring-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.检查point-storage-account spring.cloud.azure.eventhubs.processor.检查point-store.account-name
spring.cloud.azure.eventhub.检查point-access-key spring.cloud.azure.eventhubs.processor.检查point-store.account-key
spring.cloud.azure.eventhub.检查point-container spring.cloud.azure.eventhubs.processor.检查point-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
  • 重命名EventHubInboundChannelAdapterEventHubsInboundChannelAdapter与Azure 事件中心服务保持一致。
  • 将构造函数从 EventHubInboundChannelAdapter(String, SubscribeByGroupOperation, String) 更改为 EventHubsInboundChannelAdapter(EventHubsMessageListenerContainer)EventHubsInboundChannelAdapter(EventHubsMessageListenerContainer, ListenerMode)
  • 将实例化样式更改为 CheckpointConfig 简单的构造函数,而不是生成样式。
  • 删除 API EventHubOperation#setCheckpointConfig。 若要为入站通道适配器设置检查点配置,用户可以调用该方法EventHubsContainerProperties#setCheckpointConfig
  • 删除 API EventHubOperation#setBatchConsumerConfig。 若要设置入站通道适配器的批处理使用配置,用户可以调用这两种方法,同时调用这两种方法EventHubsContainerProperties#getBatch#setMaxSizeEventHubsContainerProperties#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 检查point 模式现在仅适用于批处理使用模式,可以通过传递给 ListenerMode.BATCH EventHubsInboundChannelAdapter 构造函数来启用该模式。

下表显示了从azure-spring-cloud-starter-eventhubsspring-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。检查point。CheckpointConfig
com.azure.spring.integration.core.api.CheckpointMode com.azure.spring.messaging.eventhubs.core。检查point。CheckpointMode
com.azure.spring.integration.core.api.reactor.Checkpointer com.azure.spring.messaging。检查point。检查点器
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-eventhub 版本 2 迁移到 spring-integration-azure-eventhubs。

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

API 更改

  • 删除 EventHubOperation 订阅函数移动到类 EventHubsMessageListenerContainer ,发送函数移动到 EventHubsTemplate
  • 重命名EventHubInboundChannelAdapterEventHubsInboundChannelAdapter与Azure 事件中心服务保持一致。
  • 将构造函数从 EventHubInboundChannelAdapter(String, SubscribeByGroupOperation, String) 更改为 EventHubsInboundChannelAdapter(EventHubsMessageListenerContainer)EventHubsInboundChannelAdapter(EventHubsMessageListenerContainer, ListenerMode)
  • 将实例化样式更改为 CheckpointConfig 简单的构造函数,而不是生成样式。
  • 删除 API EventHubOperation#setCheckpointConfig。 若要为入站通道适配器设置检查点配置,用户可以调用该方法EventHubsContainerProperties#setCheckpointConfig
  • 删除 API EventHubOperation#setBatchConsumerConfig。 若要设置入站通道适配器的批处理使用配置,用户可以调用这两种方法,同时调用这两种方法EventHubsContainerProperties#getBatch#setMaxSizeEventHubsContainerProperties#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 检查point 模式现在仅适用于批处理使用模式,可以通过传递给 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。检查point。CheckpointConfig
com.azure.spring.integration.core.api.CheckpointMode com.azure.spring.messaging.eventhubs.core。检查point。CheckpointMode
com.azure.spring.integration.core.api.reactor.Checkpointer com.azure.spring.messaging。检查point。检查点器
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-servicebusspring-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.mode=fixed 或指数配置 spring.cloud.azure.servicebus.retry.fixed.max-retries,具体取决于 spring.cloud.azure.servicebus.retry.mode=fixedexponential
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=fixedexponential 配置
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 更改

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

下表显示了从azure-spring-cloud-starter-servicebusspring-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 示例代码:

    使用 ServiceBusQueueInboundChannelAdapterServiceBusTopicInboundChannelAdapter

    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 更改

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

下表显示了从azure-spring-integration-servicebusspring-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-storage-queue 的 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-queuespring-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
  • 删除 checkpoint-mode 配置 StorageQueueTemplate,仅支持模式 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。存储QueueMessageConverter com.azure.spring.messaging.storage.queue.support.converter。存储QueueMessageConverter
com.azure.spring.integration.core.api.reactor.Checkpointer com.azure.spring.messaging。检查point。检查点器
com.azure.spring.integration.storage.queue。存储QueueTemplate com.azure.spring.storage.queue.core。存储QueueTemplate
com.azure.spring.integration.core.api.reactor.DefaultMessageHandler com.azure.spring.integration.core.handler.DefaultMessageHandler
com.azure.spring.integration.storage.queue.inbound。存储QueueMessageSource com.azure.spring.integration.storage.queue.inbound。存储QueueMessageSource

从 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
  • 删除 checkpoint-mode 配置 StorageQueueTemplate,仅支持模式 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。存储QueueMessageConverter com.azure.spring.messaging.storage.queue.support.converter。存储QueueMessageConverter
com.azure.spring.integration.core.api.reactor.Checkpointer com.azure.spring.messaging。检查point。检查点器
com.azure.spring.integration.storage.queue。存储QueueTemplate com.azure.spring.storage.queue.core。存储QueueTemplate
com.azure.spring.integration.core.api.reactor.DefaultMessageHandler com.azure.spring.integration.core.handler.DefaultMessageHandler
com.azure.spring.integration.storage.queue.inbound。存储QueueMessageSource com.azure.spring.integration.storage.queue.inbound。存储QueueMessageSource

从 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-eventhubsspring-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.检查point-storage-account spring.cloud.azure.eventhubs.processor.检查point-store.account-name
spring.cloud.azure.eventhub.检查point-access-key spring.cloud.azure.eventhubs.processor.检查point-store.account-key
spring.cloud.azure.eventhub.检查point-container spring.cloud.azure.eventhubs.processor.检查point-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.检查point-mode spring.cloud.stream.eventhubs.bindings.binding-name.consumer.检查point.mode
spring.cloud.stream.eventhub.bindings.binding-name.consumer.检查point-count spring.cloud.stream.eventhubs.bindings.binding-name.consumer.检查point.count
spring.cloud.stream.eventhub.bindings.binding-name.consumer.检查point-interval spring.cloud.stream.eventhubs.bindings.binding-name.consumer.检查point.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也从枚举更改为map每个分区的StartPositionProperties枚举com.azure.spring.integration.core.api.StartPosition。 因此,键是分区 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 的值包括: commonorganizationsconsumers或租户 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 的值包括: commonorganizationsconsumers或租户 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 的值包括: commonorganizationsconsumers或租户 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。检查point。检查点器
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 队列或 azure-spring-cloud-stream-binder-servicebus-queueazure-spring-cloud-stream-binder-servicebus-topic 迁移到 spring-cloud-azure-stream-binder-servicebus-servicebus。

有关常规信息,请使用以下链接:

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

SDK 配置更改

重要

旧绑定器库和azure-spring-cloud-stream-binder-servicebus-queueazure-spring-cloud-stream-binder-servicebus-topic现在它们合并为一个spring-cloud-azure-stream-binder-servicebus

重要

绑定器类型与绑定器类型组合在一servicebus-queueservicebusservicebus-topic

下表列出了以下项 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.mode=fixed 或指数配置 spring.cloud.azure.servicebus.retry.fixed.max-retries,具体取决于 spring.cloud.azure.servicebus.retry.mode=fixedexponential
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=fixedexponential 配置
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检查point-mode 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检查point-mode spring.cloud.stream.servicebus.bindings.binding-name.consumer自动完成

注意

sessionsEnabled 为 true maxConcurrentSessions 时,并发属性将被 maxConcurrentSessions 替换,当 sessionsEnabled false为 maxConcurrentCalls 时,将替换为 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 的值包括: commonorganizationsconsumers或租户 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 的值包括: commonorganizationsconsumers或租户 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 的值包括: commonorganizationsconsumers或租户 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。检查point。检查点器

azure-spring-cloud-messaging

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