共用方式為


Spring Cloud Azure Kafka 支援

本文適用于: ✔️版本 4.14.0 ✔️ 5.8.0

從 4.3.0 版開始,適用于 Kafka 的 Spring Cloud Azure 支援各種類型的認證,以驗證並聯機到Azure 事件中樞。

支援的 Kafka 版本

目前的入門版本應該與使用 JAVA 8 或更高版本的 Apache Kafka 用戶端 2.0.0 相容。

支援的驗證類型

支援以下驗證類型:

  • 一般連接字串驗證
    • 直接連接字串驗證
    • ARM 型連接字串驗證
  • OAuth 認證驗證
    • 受控識別驗證
    • 使用者名稱/密碼驗證
    • 服務主體驗證
    • DefaultAzureCredential 驗證

運作方式

OAuth 認證驗證

本節說明 Spring Cloud Azure OAuth 驗證的整體工作流程。

Spring Cloud Azure 會根據應用程式驗證組態,先建置下列其中一種類型的認證:

  • ClientSecretCredential
  • ClientCertificateCredential
  • UsernamePasswordCredential
  • ManagedIdentityCredential

如果找不到這些類型的認證,則會使用 透過 DefaultAzureTokenCredential 的認證鏈結,從應用程式屬性、環境變數、受控識別或 IDE 取得認證。 如需詳細資訊,請參閱 Spring Cloud Azure 驗證

一般連接字串驗證

針對連接字串驗證模式,您可以直接使用連接字串驗證,或使用 Azure Resource Manager 來擷取連接字串。 如需使用方式的詳細資訊,請參閱 連接字串驗證 的基本用法一節。

注意

由於 4.3.0 版,連接字串驗證已被取代為 OAuth 驗證。

組態

搭配 OAuth 驗證使用 Kafka 支援時可設定的屬性

適用于 Kafka 的 Spring Cloud Azure 支援下列兩個層級的組態選項:

  1. 適用于事件中樞 Kafka 屬性的 Spring Cloud Azure。
  2. profile 的全域驗證組態選項 credential ,前置詞為 spring.cloud.azure
  3. Kafka 特定的層級設定。 Kafka 層級組態也適用于 Spring Boot 和 Spring Cloud Stream 系結器,這些 commonconsumerproduceradmin 系結器具有不同的前置詞。

全域屬性會透過 com.azure.spring.cloud.autoconfigure.context.AzureGlobalProperties 公開。 Kafka 特定屬性會透過 org.springframework.boot.autoconfigure.kafka.KafkaProperties (Spring Boot) 和 org.springframework.cloud.stream.binder.kafka.properties.KafkaBinderConfigurationProperties (Spring Cloud Stream 系結器) 公開。

下列清單顯示所有支援的組態選項。

  • 適用于事件中樞 Kafka 屬性的 Spring Cloud Azure。

    • 財產: spring.cloud.azure.eventhubs.kafka.enabled
    • 描述:是否要啟用 Kafka Azure 事件中樞的無認證連線,預設值為 true
  • Spring Cloud Azure 全域驗證組態選項

    • 前置詞:spring.cloud.azure
    • 支援的選項: spring.cloud.azure.credential.*spring.cloud.azure.profile.*

    如需通用群組態選項的完整清單,請參閱 全域設定屬性

  • Spring Boot Kafka 一般設定

    • 前置詞:spring.kafka.properties.azure
    • 範例: spring.kafka.properties.azure .credential.*
  • Spring Kafka 取用者設定選項

    • 前置詞:spring.kafka.consumer.properties.azure
    • 範例: spring.kafka.consumer.properties.azure .credential.*
  • Spring Kafka 產生者組態選項

    • 前置詞:spring.kafka.producer.properties.azure
    • 範例: spring.kafka.producer.properties.azure .credential.*
  • Spring Kafka 系統管理員設定選項

    • 前置詞:spring.kafka.admin.properties.azure
    • 範例: spring.kafka.admin.properties.azure .credential.*
  • Spring Cloud Stream Kafka Binder 一般設定

    • 前置詞:spring.cloud.stream.kafka.binder.configuration.azure
    • 範例: spring.cloud.stream.kafka.binder.configuration.azure .credential.*
  • Spring Cloud Stream Kafka Binder 取用者設定

    • 前置詞:spring.cloud.stream.kafka.binder.consumer-properties.azure
    • 範例: spring.cloud.stream.kafka.binder.consumer-properties.azure .credential.*
  • Spring Cloud Stream Kafka Binder 產生者設定

    • 前置詞:spring.cloud.stream.kafka.binder.producer-properties.azure
    • 範例: spring.cloud.stream.kafka.binder.producer-properties.azure .credential.*
  • Spring Cloud Stream Kafka Binder 管理員設定

    • 前置詞:不支援,應該使用 Spring Boot Kafka 一般或系統管理員設定。

下表顯示 Spring Boot Kafka 一般組態選項:

名稱 描述
spring.kafka.properties.azure.credential.client-certificate-password 憑證檔案的密碼。
spring.kafka.properties.azure.credential.client-certificate-path 使用 Azure 執行服務主體驗證時要使用的 PEM 憑證檔案路徑。
spring.kafka.properties.azure.credential.client-id 使用 Azure 執行服務主體驗證時要使用的用戶端識別碼。 這是舊版屬性。
spring.kafka.properties.azure.credential.client-secret 使用 Azure 執行服務主體驗證時要使用的用戶端密碼。 這是舊版屬性。
spring.kafka.properties.azure.credential.managed-identity-enabled 是否要讓受控識別向 Azure 進行驗證。 如果 為 true client-id 已設定 ,則會使用用戶端識別碼作為使用者指派的受控識別用戶端識別碼。 預設值為 false
spring.kafka.properties.azure.credential.password 使用 Azure 執行使用者名稱/密碼驗證時要使用的密碼。
spring.kafka.properties.azure.credential.username 使用 Azure 執行使用者名稱/密碼驗證時要使用的使用者名稱。
spring.kafka.properties.azure.profile.environment.active-directory-endpoint 要連接的 Microsoft Entra 端點。
spring.kafka.properties.azure.profile.tenant-id Azure 資源的租使用者識別碼。 允許 tenant-id 的值包括: commonorganizationsconsumers 或租使用者識別碼。

注意

不同層級的組態選項會套用下列規則。 特定組態選項的優先順序高於一般設定選項。 例如:

  • Spring Kafka 一般設定選項取代全域選項。
  • Spring Kafka 取用者設定選項取代通用選項。
  • Spring Kafka 產生者組態選項取代了一般選項。
  • Spring Kafka 系統管理員設定選項取代了一般選項。
  • Spring Cloud Stream Kafka Binder 選項就像上述一樣。

搭配一般連接字串驗證使用 Kafka 支援時可設定的屬性

下表顯示適用于 Kafka 的 Spring Boot 事件中樞一般組態選項:

屬性 說明
spring.cloud.azure.eventhubs.kafka.enabled 是否啟用 Azure 事件中樞 Kafka 支援。 預設值為 true
spring.cloud.azure.eventhubs.connection-string Azure 事件中樞 連接字串。 當您想要直接提供連接字串時,請提供此值。
spring.cloud.azure.eventhubs.namespace Azure 事件中樞命名空間。 當您想要透過 Azure Resource Manager 擷取連線資訊時,請提供此值。
spring.cloud.azure.eventhubs.resource.resource-group Azure 事件中樞 命名空間的資源群組。 當您想要透過 Azure Resource Manager 擷取連線資訊時,請提供此值。
spring.cloud.azure.profile.subscription-id 訂用帳戶識別碼。 當您想要透過 Azure Resource Manager 擷取連線資訊時,請提供此值。

相依性設定

將下列相依性新增至您的專案。 這會自動在專案中以可轉移的方式包含 spring-boot-starter 相依性。

<dependency>
    <groupId>com.azure.spring</groupId>
    <artifactId>spring-cloud-azure-starter</artifactId>
</dependency>

注意

請記得新增 BOM spring-cloud-azure-dependencies 以及上述相依性。 如需詳細資訊,請參閱 Spring Cloud Azure 開發人員指南 開始使用 一節。

基本使用方式

下列各節顯示傳統 Spring Boot 應用程式使用案例。

使用 OAuth 驗證

當您使用 Spring Cloud Azure for Kafka 所提供的 OAuth 驗證時,您可以使用上述設定來設定特定認證。 或者,您可以選擇不設定認證的相關設定,在此情況下,Spring Cloud Azure 會從環境載入認證。 本節說明從 Azure CLI 環境或 Azure Spring Apps 裝載環境載入認證的使用方式。

注意

如果您選擇使用安全性主體向 Microsoft Entra ID 進行驗證和授權,以存取 Azure 資源,請參閱 使用 Microsoft Entra ID 授權存取一節,以確定安全性主體已獲得足夠的許可權來存取 Azure 資源。

下一節說明使用不同 Spring 生態系統程式庫搭配 OAuth 驗證的案例。

Spring Kafka 應用程式支援

本節說明使用 Spring Kafka 或 Spring Integration Kafka 程式庫之 Spring Boot 應用程式的使用案例。

相依性設定
<dependency>
    <groupId>com.azure.spring</groupId>
    <artifactId>spring-cloud-azure-starter</artifactId>
</dependency>
<!-- Using Spring Kafka library only-->
<dependency>
    <groupId>org.springframework.kafka</groupId>
    <artifactId>spring-kafka</artifactId>
    <version>{version}</version><!--Need to be set, for example:2.8.6-->
</dependency>
<!-- Using Spring Integration library only -->
<dependency>
    <groupId>org.springframework.integration</groupId>
    <artifactId>spring-integration-kafka</artifactId>
    <version>{version}</version><!--Need to be set, for example:5.5.12-->
</dependency>

組態更新

若要使用 OAuth 驗證,只要指定事件中樞端點,如下列範例所示:

spring.kafka.bootstrap-servers=<NAMESPACENAME>.servicebus.windows.net:9093

Spring Cloud Stream 系結器 Kafka 應用程式支援

本節說明使用 Spring Cloud Stream 系結器 Kafka 程式庫之 Spring Boot 應用程式的使用案例。

相依性設定
<dependency>
    <groupId>com.azure.spring</groupId>
    <artifactId>spring-cloud-azure-starter</artifactId>
</dependency>
<dependency>
    <groupId>org.springframework.cloud</groupId>
    <artifactId>spring-cloud-starter-stream-kafka</artifactId>
    <version>{version}</version><!--Need to be set, for example:3.2.3-->
</dependency>
組態

若要使用 OAuth 驗證,只要指定事件中樞端點,如下列範例所示:

spring.cloud.stream.kafka.binder.brokers=<NAMESPACENAME>.servicebus.windows.net:9093

注意

如果您使用版本 4.3.0 ,別忘了設定 spring.cloud.stream.binders.<kafka-binder-name>.environment.spring.main.sources=com.azure.spring.cloud.autoconfigure.kafka.AzureKafkaSpringCloudStreamConfiguration 屬性以啟用整個 OAuth 驗證工作流程,其中 kafka-binder-name 預設為 kafka 在單一 Kafka 系結器應用程式中。 組態 AzureKafkaSpringCloudStreamConfiguration 會指定 的 OAuth 安全性參數 KafkaBinderConfigurationProperties ,用於 KafkaOAuth2AuthenticateCallbackHandler 啟用 Azure 身分識別。

針對之後 4.4.0 的版本,每個 Kafka 系結器環境都會自動新增此屬性,因此您不需要手動新增它。

範例

請參閱 GitHub 上的 azure-spring-boot-samples 存放庫。

使用連接字串驗證

您可以直接使用連接字串驗證,或使用 Azure Resource Manager 來擷取連接字串。

注意

由於 4.3.0 版,連接字串驗證已被取代為 OAuth 驗證。

由於 4.5.0 版在搭配 Spring Cloud Stream 架構使用連接字串驗證時,必須有下列屬性,以確保連接字串可以生效,其中當 Kafka 系結器名稱沒有自訂群組態時,其值 <kafka-binder-name> 應該是 kafka

spring.cloud.stream.binders.<kafka-binder-name>.environment.spring.main.sources=com.azure.spring.cloud.autoconfigure.eventhubs.kafka.AzureEventHubsKafkaAutoConfiguration

相依性設定

如果您想要移轉 Apache Kafka 應用程式,以針對 Kafka 使用Azure 事件中樞,請新增下列相依性。

<dependency>
    <groupId>com.azure.spring</groupId>
    <artifactId>spring-cloud-azure-starter</artifactId>
</dependency>

如果您想要使用 Azure Resource Manager 擷取連接字串,請新增下列相依性:

<dependency>
    <groupId>com.azure.spring</groupId>
    <artifactId>spring-cloud-azure-resourcemanager</artifactId>
</dependency>

組態

直接使用事件中樞連接字串

連線到 Kafka 事件中樞的最簡單方式是使用 連接字串。 只要新增下列屬性即可。

spring.cloud.azure.eventhubs.connection-string=${AZURE_EVENTHUBS_CONNECTION_STRING}
使用 Azure Resource Manager 擷取連接字串

如果您不想在應用程式中設定連接字串,您可以使用 Azure Resource Manager 來擷取連接字串。 若要向 Azure Resource Manager 進行驗證,您也可以使用儲存在 Azure CLI 或其他本機開發工具的認證,例如 Visual Studio Code 或 Intellij IDEA。 或者,如果您的應用程式部署至 Azure 雲端,您可以使用受控識別。 請確定主體有足夠的許可權可讀取資源中繼資料。

注意

如果您選擇使用安全性主體來向 Microsoft Entra ID 進行驗證和授權,以存取 Azure 資源,請參閱 使用 Microsoft Entra ID 授權存取一節,以確定安全性主體已獲得足夠的許可權來存取 Azure 資源。

若要使用 Azure Resource Manager 來擷取連接字串,只要新增下列屬性即可。

spring:
  cloud:
    azure:
      profile:
        subscription-id: ${AZURE_SUBSCRIPTION_ID}
      eventhubs:
        namespace: ${AZURE_EVENTHUBS_NAMESPACE}
        resource:
          resource-group: ${AZURE_EVENTHUBS_RESOURCE_GROUP}

範例

請參閱 GitHub 上的 azure-spring-boot-samples 存放庫。