共用方式為

Spring Cloud Azure 4.0 的移轉指南

  • 發行項

本指南可協助從舊版 Azure Spring 程式庫移轉至 Spring Cloud Azure 4.0。

簡介

我們將呼叫群組識別碼和成品識別碼遵循新式 程式庫的模式，以及具有模式 com.azure.spring:spring-cloud-azure-*com.azure.spring:azure-spring-boot-* 、 com.azure.spring:azure-spring-cloud-* 或 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 服務的程式庫尚未啟用完整的組態集。 此外，專案命名、成品識別碼、版本和組態不一致使得學習曲線急劇增加。

為了改善 Spring Cloud Azure 程式庫的開發體驗，引進了一組設計指導方針，以確保 Spring Cloud Azure 程式庫在 Spring 生態系統方面具有自然且慣用的感覺。 如需進一步的詳細資料， 請參閱設計檔 。

Spring Cloud Azure 4.0 提供跨程式庫的共用體驗，與不同的 Spring 專案整合，例如 Spring Boot、Spring Integration、Spring Cloud Stream 等等。 共用體驗包括：

  • 整合的 BOM，包含所有 Spring Cloud Azure 4.0 程式庫。
  • 成品的一致命名慣例。
  • 設定認證、Proxy、重試、雲端環境和傳輸層設定的統一方式。
  • 支援 Azure 服務或 Azure 服務 SDK 支援的所有驗證方法。

概觀

此移轉指南包含下列各節：

  • Spring Cloud Azure 4.0 的命名變更
  • 成品變更：已重新命名/新增/已刪除
  • 相依性變更
  • 驗證變更
  • 設定屬性
  • API 重大變更
  • 程式庫變更

命名變更

呼叫所有 Spring Cloud Azure 程式庫從未有過一致或官方名稱。 他們中的一些人被叫來，其中 Spring on Azure 一些人被叫 Azure Spring Boot 了。 自 4.0 起，我們開始使用專案名稱 Spring Cloud Azure 來代表所有 Azure Spring 程式庫。

30M

我們曾經為 程式庫 azure-spring-boot-bomazure-spring-cloud-dependencies 和 提供兩個 BOM，但我們將這兩個 BOM 合併成一個 BOM，因為 4.0 是 spring-cloud-azure-dependencies 。 在專案的 區段中新增專案 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 程式庫的群組識別碼相同。 它們全都是 com.azure.spring 。 新式 Spring Cloud Azure 程式庫的成品識別碼已變更。 根據其所屬的 Spring 專案、Spring Boot、Spring Integration 或 Spring Cloud Stream，成品識別碼模式可以是 spring-cloud-azure-starter-[service] 、 spring-integration-azure-[service] 或 spring-cloud-azure-stream-binder-[service] 。 每個 的舊版入門都有遵循模式 azure-spring-* 的成品識別碼。 這提供快速且無障礙的方法，可協助您一目了然地瞭解您使用的是新式或舊版入門。

在開發 Spring Cloud Azure 4.0 的過程中，我們重新命名了一些成品，使其遵循新的命名慣例，刪除了一些成品，讓功能可以放入更適當的成品中，並新增一些新的成品，以更好地處理某些案例。

下表顯示舊版成品識別碼與新式成品識別碼之間的對應：

舊版成品識別碼 新式成品識別碼 描述
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-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-一個執行器 新新增的 Spring Cloud Azure 執行器成品。
不適用 spring-cloud-azure-actuator-autoconfigure 新增的 Spring Cloud Azure 執行器自動設定成品，包括執行器的自動設定。
不適用 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 新增的 Resource Manager 成品。 它是使用 Azure Resource Manager 來讀取中繼資料並建立資源的核心程式庫。
不適用 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 不支援此功能。 通用群組態可以分成五個類別，如下表所示：

前置詞 描述
spring.cloud.azure.client 設定每個 Azure SDK 下方的傳輸用戶端。
spring.cloud.azure.credential 設定如何使用 Microsoft Entra 識別碼進行驗證。
spring.cloud.azure.profile 設定 Azure 雲端環境。
spring.cloud.azure.proxy 設定 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。

下表顯示 和 spring-cloud-azure-starter-active-directory 之間的 azure-spring-boot-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-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 不再受支援。 請改用 property-source[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 和 SecretAsyncClient ），並新增 KeyVaultPropertySource 。 ConfigurableEnvironment
  3. spring.cloud.azure.keyvault.secret.property-source-enabled 是用來啟用所有 KeyVaultPropertySource 。 只有在 時 spring.cloud.azure.keyvault.secret.enabled=true 才會生效。
  4. 針對 Azure 通用屬性（例如 client 、、 retryproxy 、 credentialprofile 、 和 金鑰保存庫 屬性（例如 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-endpoint spring.cloud.azure.storage.blob.endpoint

API 變更

下表顯示 類別從 azure-spring-boot-starter-storage 對應到 spring-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 第 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.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-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 = fixed 或 指數
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 = fixed 或 exponential 來 設定。
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 。
  • 請改為在 和 DefaultMessageHandler 中 ServiceBusTemplate 卸載 CompletableFuture 支援 Reactor 。
  • 新增 的 API ServiceBusTemplate#setDefaultEntityType 以指定實體類型，這是針對 未提供 bean PropertiesSupplier&lt;String, ProducerProperties&gt; 時 ProducerProperties#entityType 的必要專案。
  • 卸載訊息標頭 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 。
  • 請改為在 和 DefaultMessageHandler 中 ServiceBusTemplate 卸載 CompletableFuture 支援 Reactor 。
  • 新增 的 API ServiceBusTemplate#setDefaultEntityType 以指定實體類型，這是針對 未提供 bean PropertiesSupplier&lt;String, ProducerProperties&gt; 時 ProducerProperties#entityType 的必要專案。
  • 卸載訊息標頭 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 。
  • 在 中卸載 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.checkpoint.Checkpointer
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.checkpoint.Checkpointer
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-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 變更為 mapStartPositionProperties 每個分割區的 。 因此，索引鍵是分割區識別碼，而值則 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 Resource Manager （ARM），然後使用 ARM 擷取指定命名空間的連接字串。 最後，應用程式會使用擷取連接字串來連線到Azure 事件中樞。 如此一來，應將所提供的安全性主體授與參與者 角色，以擷取相關聯的Azure 事件中樞命名空間。

針對 Azure Spring Apps 4.0，我們提供兩種方式來運用安全性主體進行驗證。 其中一個仍在使用主體來連線到 ARM，並擷取 Contributor 主體需要角色的連接字串。 另一個會利用安全性主體向 Microsoft Entra ID 進行驗證，然後直接連線到Azure 事件中樞。 在此情況下， Contributor 不再需要角色，而傳訊作業需要其他 Data 相關角色。 若要確定安全性主體已獲得足夠的許可權來存取 Azure 資源，請參閱 使用 Microsoft Entra 識別碼 授權存取權。

針對以 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 或租使用者識別碼。 如需這些值的詳細資訊，請參閱 使用錯誤的端點（個人和組織帳戶） 一節錯誤 AADSTS50020 - 來自識別提供者的使用者帳戶不存在於租使用者 中。 如需轉換單一租使用者應用程式的資訊，請參閱 在 Microsoft Entra 識別碼 上將單一租使用者應用程式轉換成多租使用者。

需要新式設定、Azure 訂用帳戶識別碼和資源群組的屬性：

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 或租使用者識別碼。 如需這些值的詳細資訊，請參閱 使用錯誤的端點（個人和組織帳戶） 一節錯誤 AADSTS50020 - 來自識別提供者的使用者帳戶不存在於租使用者 中。 如需轉換單一租使用者應用程式的資訊，請參閱 在 Microsoft Entra 識別碼 上將單一租使用者應用程式轉換成多租使用者。

您也可以直接移轉以使用 Microsoft Entra 識別碼進行驗證和授權，而不需前往 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 或租使用者識別碼。 如需這些值的詳細資訊，請參閱 使用錯誤的端點（個人和組織帳戶） 一節錯誤 AADSTS50020 - 來自識別提供者的使用者帳戶不存在於租使用者 中。 如需轉換單一租使用者應用程式的資訊，請參閱 在 Microsoft Entra 識別碼 上將單一租使用者應用程式轉換成多租使用者。

  • 使用受控識別

    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 第 2 版移轉至 spring-cloud-stream-binder-servicebus-queue 或 azure-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 = fixed 或 指數
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 = fixed 或 exponential 來 設定。
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 。 checkpoint-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 。 checkpoint-mode spring.cloud.stream.servicebus.bindings.binding-name.consumer 。 自動完成

注意

當 sessionsEnabled 為 true 時，concurrency 屬性將會由 maxConcurrentSessions 取代，而 sessionsEnabled 為 時，maxConcurrentCalls 會取代為 false 。

注意

啟用自動完成等於 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 Resource Manager （ARM），然後使用 ARM 擷取指定命名空間的連接字串。 最後，應用程式會使用擷取連接字串來連線到Azure 服務匯流排。 如此一來，應將所提供的安全性主體授與 參與者角色，以擷取相關聯的Azure 服務匯流排命名空間。

針對 Azure Spring Apps 4.0，我們提供兩種方式來運用安全性主體進行驗證。 其中一個仍在使用主體來連線到 ARM，並擷取 Contributor 主體需要角色的連接字串。 另一個會利用安全性主體向 Microsoft Entra ID 進行驗證，然後直接連線到Azure 服務匯流排。 在此情況下， Contributor 不再需要角色，而傳訊作業需要其他 Data 相關角色。 若要確定安全性主體已獲得足夠的許可權來存取 Azure 資源，請參閱 使用 Microsoft Entra 識別碼 授權存取權。

針對以 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 或租使用者識別碼。 如需這些值的詳細資訊，請參閱 使用錯誤的端點（個人和組織帳戶） 一節錯誤 AADSTS50020 - 來自識別提供者的使用者帳戶不存在於租使用者 中。 如需轉換單一租使用者應用程式的資訊，請參閱 在 Microsoft Entra 識別碼 上將單一租使用者應用程式轉換成多租使用者。

需要新式設定、Azure 訂用帳戶識別碼和資源群組的屬性：

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 或租使用者識別碼。 如需這些值的詳細資訊，請參閱 使用錯誤的端點（個人和組織帳戶） 一節錯誤 AADSTS50020 - 來自識別提供者的使用者帳戶不存在於租使用者 中。 如需轉換單一租使用者應用程式的資訊，請參閱 在 Microsoft Entra 識別碼 上將單一租使用者應用程式轉換成多租使用者。

您也可以直接移轉以使用 Microsoft Entra 識別碼進行驗證和授權，而不需前往 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 或租使用者識別碼。 如需這些值的詳細資訊，請參閱 使用錯誤的端點（個人和組織帳戶） 一節錯誤 AADSTS50020 - 來自識別提供者的使用者帳戶不存在於租使用者 中。 如需轉換單一租使用者應用程式的資訊，請參閱 在 Microsoft Entra 識別碼 上將單一租使用者應用程式轉換成多租使用者。

  • 使用受控識別

    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 批註。