Spring Cloud Azure Kafka 支援

適用於: ✅ Version 4.20.0, ✅ Version 5.25.0, ✅ Version 6.5.0, ✅ Version 7.4.0

Spring Cloud Azure Kafka 支援幫助 Spring 應用程式透過 OAuth 憑證或連接字串來認證並連接 Azure 事件中樞。本文說明所支援的認證類型、設定選項、相依關係及使用情境。

支援的 Kafka 版本

目前的 Starter 版本相容於 Apache Kafka Clients 2.0.0，並支援 Java 8 或更高版本。

支援的驗證類型

啟動器支援以下認證類型：

一般連接字串驗證
- 直接連接字串驗證
- 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 支援下列兩個層級的組態選項：

適用於事件中樞 Kafka 屬性的 Spring Cloud Azure。
credential 和 profile 的全域驗證組態選項，前置詞為 spring.cloud.azure。
Kafka 專屬的層級設定。 Kafka 層級組態也適用於 Spring Boot 和 Spring Cloud Stream 系結器，適用於具有不同前置詞的 common、consumer、producer或 admin 範圍。

全域屬性會透過 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` 為設定，則用戶端 ID 為使用者指派的管理身份客戶端 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` 允許的值包括：`common`、`organizations`、`consumers`或租用戶標識碼。

注意

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

Spring Kafka 一般設定選項取代全域選項。
Spring Kafka 取用者設定選項取代通用選項。
Spring Kafka 產生者組態選項取代了一般選項。
Spring Kafka 系統管理員設定選項取代了一般選項。
Spring Cloud Stream Kafka 活頁夾的選項也遵循相同的模式。

使用 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 為 Kafka 提供的 OAuth 認證時，可以透過上述設定來設定特定的憑證。或者，你也可以選擇不設定任何憑證。在這種情況下，Spring Cloud Azure 會從環境中載入憑證。本節說明如何從 Azure CLI 環境或 Azure Spring 應用程式主機環境載入憑證。

注意

如果你選擇使用安全主體來驗證並授權使用 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 繫結器應用程式中，kafka-binder-name 預設為 kafka。該配置 AzureKafkaSpringCloudStreamConfiguration 指定了的 KafkaBinderConfigurationPropertiesOAuth 安全參數。此設定用於在 KafkaOAuth2AuthenticateCallbackHandler 中啟用 Azure 身分識別。

在 4.4.0 之後的版本中，系統會自動為每個 Kafka 繫結器環境新增此屬性，因此你不需要手動新增。

使用受控識別進行 OAuth 驗證

要使用受管理身份，請啟用你的服務的管理身份，並指派 Azure 事件中樞 Data Receiver and Azure 事件中樞 Data Sender 角色。如需詳細資訊，請參閱為訪問許可權指派 Azure 角色。
在您的 application.yml 檔案中設定下列屬性：
```
spring:
  cloud:
    azure:
      credential:
        managed-identity-enabled: true
```
重要

如果你使用使用者指派的管理身份，也請將該屬性 spring.cloud.azure.credential.client-id 與你的使用者指派管理身份客戶端 ID 一起加入。

樣品

請參見 GitHub 上的 azure-spring-boot-samples 倉庫。

使用連接字串驗證

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

Spring Cloud Azure 5.x
Spring Cloud Azure 4.x

注意

自 5.0.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.implementation.eventhubs.kafka.AzureEventHubsKafkaAutoConfiguration

如果你使用的版本 spring-cloud-dependencies 是 2022.0.0，你會遇到例外 java.lang.IllegalStateException: kafka_context has not been refreshed yet。若要解決此問題，請升級至更高版本。

注意

自 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 雲端，您可以使用受控識別。只要確保主體有足夠的權限讀取資源元資料即可。

注意

若要使用 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 倉庫。

意見反應

此頁面對您有幫助嗎？

Last updated on 2026-09-21

Spring Cloud Azure Kafka 支援

支援的 Kafka 版本

支援的驗證類型

運作方式

OAuth 認證驗證

一般連接字串驗證

配置

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

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

相依性設定

基本用法

使用 OAuth 驗證

Spring Kafka 應用程式支援

相依性設定

組態更新

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

相依性設定

配置

使用受控識別進行 OAuth 驗證

樣品

使用連接字串驗證

相依性設定

配置

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

使用 Azure Resource Manager 擷取連接字串

樣品

意見反應

其他資源