Dukungan Spring Cloud Azure Kafka

Berlaku untuk: ✅ Version 4.20.0, ✅ Version 5.25.0, ✅ Version 6.5.0, ✅ Version 7.4.0

Dukungan Spring Cloud Azure Kafka membantu aplikasi Spring mengautentikasi dan terhubung ke Azure Event Hubs dengan menggunakan kredensial OAuth atau string koneksi. Artikel ini menjelaskan jenis autentikasi, opsi konfigurasi, dependensi, dan skenario penggunaan yang didukung.

Versi Kafka yang didukung

Versi starter saat ini kompatibel dengan Apache Kafka Clients 2.0.0 dan menggunakan Java 8 atau lebih tinggi.

Jenis autentikasi yang didukung

Starter ini mendukung jenis autentikasi berikut:

Autentikasi string koneksi biasa
- Autentikasi langsung dengan string koneksi
- Autentikasi string koneksi berbasis ARM
Autentikasi kredensial OAuth
- Autentikasi identitas terkelola
- Autentikasi nama pengguna/kata sandi
- Autentikasi service principal
- DefaultAzureCredential autentikasi

Cara kerjanya

Autentikasi kredensial OAuth

Bagian ini menjelaskan alur kerja keseluruhan autentikasi Spring Cloud Azure OAuth.

Spring Cloud Azure pertama-tama membangun salah satu jenis kredensial berikut, tergantung pada konfigurasi autentikasi aplikasi:

ClientSecretCredential
ClientCertificateCredential
UsernamePasswordCredential
ManagedIdentityCredential

Jika aplikasi tidak menggunakan salah satu jenis kredensial ini, aplikasi menggunakan rantai DefaultAzureTokenCredential kredensial untuk mendapatkan kredensial dari properti aplikasi, variabel lingkungan, identitas terkelola, atau IDEs. Untuk informasi selengkapnya, lihat autentikasi Spring Cloud Azure.

Autentikasi string koneksi biasa

Untuk mode autentikasi string koneksi, Anda dapat menggunakan autentikasi string koneksi secara langsung atau menggunakan Azure Resource Manager untuk mengambil string koneksi. Untuk informasi selengkapnya tentang penggunaan, lihat bagian Penggunaan dasar untuk autentikasi string koneksi.

Nota

Sejak versi 4.3.0, autentikasi string koneksi tidak digunakan lagi demi autentikasi OAuth.

Konfigurasi

Properti yang dapat dikonfigurasi saat menggunakan dukungan Kafka dengan autentikasi OAuth

Spring Cloud Azure for Kafka mendukung dua tingkat opsi konfigurasi berikut:

Properti Spring Cloud Azure untuk Event Hubs Kafka
Opsi konfigurasi autentikasi global credential dan profile dengan awalan spring.cloud.azure.
Konfigurasi tingkat khusus Kafka. Konfigurasi tingkat Kafka juga tersedia untuk binder Spring Boot dan Spring Cloud Stream pada cakupan common, consumer, producer, atau admin, yang masing-masing memiliki prefiks berbeda.

Properti global diekspos melalui com.azure.spring.cloud.autoconfigure.context.AzureGlobalProperties. Properti khusus Kafka diekspos melalui org.springframework.boot.autoconfigure.kafka.KafkaProperties (Spring Boot) dan org.springframework.cloud.stream.binder.kafka.properties.KafkaBinderConfigurationProperties (pengikat Spring Cloud Stream).

Daftar berikut ini memperlihatkan semua opsi konfigurasi yang didukung.

properti Spring Cloud Azure untuk Event Hubs Kafka
- Properti: spring.cloud.azure.eventhubs.kafka.enabled
- Deskripsi: apakah akan mengaktifkan koneksi gratis kredensial ke Azure Event Hubs for Kafka, nilai defaultnya adalah true.
Opsi konfigurasi autentikasi global Spring Cloud Azure
- Awalan: spring.cloud.azure
- Opsi yang didukung: spring.cloud.azure.credential.*, spring.cloud.azure.profile.*
Untuk daftar lengkap opsi konfigurasi global, lihat Properti konfigurasi global.
Konfigurasi umum Spring Boot Kafka
- Awalan: spring.kafka.properties.azure
- Contoh: spring.kafka.properties.azure.credential.*
Opsi konfigurasi konsumen Spring Kafka
- Awalan: spring.kafka.consumer.properties.azure
- Contoh: spring.kafka.consumer.properties.azure.credential.*
Opsi konfigurasi produsen Spring Kafka
- Awalan: spring.kafka.producer.properties.azure
- Contoh: spring.kafka.producer.properties.azure.credential.*
Opsi konfigurasi admin Spring Kafka
- Awalan: spring.kafka.admin.properties.azure
- Contoh: spring.kafka.admin.properties.azure.credential.*
Konfigurasi umum Spring Cloud Stream Kafka Binder
- Awalan: spring.cloud.stream.kafka.binder.configuration.azure
- Contoh: spring.cloud.stream.kafka.binder.configuration.azure.credential.*
Konfigurasi konsumen Spring Cloud Stream Kafka Binder
- Awalan: spring.cloud.stream.kafka.binder.consumer-properties.azure
- Contoh: spring.cloud.stream.kafka.binder.consumer-properties.azure.credential.*
Konfigurasi produsen untuk Spring Cloud Stream Kafka Binder
- Awalan: spring.cloud.stream.kafka.binder.producer-properties.azure
- Contoh: spring.cloud.stream.kafka.binder.producer-properties.azure.credential.*
Konfigurasi admin Spring Cloud Stream Kafka Binder
- Prefiks: Tidak didukung, gunakan konfigurasi umum atau admin Spring Boot Kafka.

Tabel berikut menunjukkan opsi konfigurasi umum Spring Boot Kafka:

Nama	Deskripsi
`spring.kafka.properties.azure.credential.client-certificate-password`	Kata sandi dari file sertifikat.
`spring.kafka.properties.azure.credential.client-certificate-path`	Jalur ke file sertifikat PEM yang digunakan saat melakukan autentikasi service principal dengan Azure.
`spring.kafka.properties.azure.credential.client-id`	ID klien untuk digunakan saat melakukan autentikasi perwakilan layanan dengan Azure. Ini adalah properti warisan.
`spring.kafka.properties.azure.credential.client-secret`	Rahasia klien yang digunakan saat melakukan autentikasi service principal dengan Azure. Ini adalah properti warisan.
`spring.kafka.properties.azure.credential.managed-identity-enabled`	Apakah akan mengaktifkan identitas terkelola untuk mengautentikasi dengan Azure. Jika `true` dan `client-id` diatur, ID klien adalah ID klien identitas terkelola yang ditetapkan pengguna. Nilai defaultnya adalah `false`.
`spring.kafka.properties.azure.credential.password`	Kata sandi yang digunakan saat melakukan autentikasi nama pengguna/kata sandi dengan Azure.
`spring.kafka.properties.azure.credential.username`	Nama pengguna yang akan digunakan saat melakukan autentikasi nama pengguna/kata sandi dengan Azure.
`spring.kafka.properties.azure.profile.environment.active-directory-endpoint`	Endpoint Microsoft Entra yang akan dihubungkan ke.
`spring.kafka.properties.azure.profile.tenant-id`	ID Penyewa untuk sumber daya Azure. Nilai yang diizinkan untuk `tenant-id` adalah: `common`, `organizations`, `consumers`, atau ID penyewa.

Nota

Opsi konfigurasi di tingkat yang berbeda menerapkan aturan berikut. Opsi konfigurasi yang lebih spesifik memiliki prioritas yang lebih tinggi daripada yang umum. Misalnya:

Opsi konfigurasi umum Spring Kafka menggantikan opsi global.
Opsi konfigurasi konsumen Spring Kafka menggantikan opsi umum.
Opsi konfigurasi produsen Spring Kafka menggantikan opsi umum.
Opsi konfigurasi admin Spring Kafka menggantikan opsi umum.
Opsi Spring Cloud Stream Kafka Binder mengikuti pola yang sama.

Properti yang dapat dikonfigurasi saat menggunakan dukungan Kafka dengan autentikasi string koneksi biasa

Tabel berikut menunjukkan opsi konfigurasi umum Spring Boot Event Hubs untuk Kafka:

Harta benda	Deskripsi
`spring.cloud.azure.eventhubs.kafka.enabled`	Apakah akan mengaktifkan dukungan Azure Event Hubs Kafka. Nilai defaultnya adalah `true`.
`spring.cloud.azure.eventhubs.connection-string`	String koneksi Azure Event Hubs. Berikan nilai ini saat Anda ingin memberikan string koneksi secara langsung.
`spring.cloud.azure.eventhubs.namespace`	Namespace Azure Event Hubs. Berikan nilai ini saat Anda ingin mengambil informasi koneksi melalui Azure Resource Manager.
`spring.cloud.azure.eventhubs.resource.resource-group`	Grup sumber daya dari namespace Azure Event Hubs. Berikan nilai ini saat Anda ingin mengambil informasi koneksi melalui Azure Resource Manager.
`spring.cloud.azure.profile.subscription-id`	ID langganan. Berikan nilai ini saat Anda ingin mengambil informasi koneksi melalui Azure Resource Manager.

Penyiapan dependensi

Tambahkan dependensi berikut ke proyek Anda. Dependensi ini secara otomatis menyertakan spring-boot-starter dependensi dalam proyek Anda.

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

Nota

Ingatlah untuk menambahkan BOM spring-cloud-azure-dependencies bersama dengan dependensi sebelumnya. Untuk detailnya, lihat bagian Memulai panduan pengembang Spring Cloud Azure.

Penggunaan dasar

Bagian berikut menunjukkan skenario penggunaan aplikasi Spring Boot klasik.

Menggunakan autentikasi OAuth

Saat Anda menggunakan autentikasi OAuth yang disediakan Spring Cloud Azure untuk Kafka, Anda dapat mengonfigurasi kredensial tertentu dengan menggunakan konfigurasi sebelumnya. Atau, Anda dapat memilih untuk tidak mengonfigurasi kredensial apa pun. Dalam hal ini, Spring Cloud Azure memuat kredensial dari lingkungan. Bagian ini menjelaskan cara memuat kredensial dari lingkungan Azure CLI atau lingkungan hosting Azure Spring Apps.

Nota

Jika Anda memilih untuk menggunakan prinsip keamanan untuk mengautentikasi dan mengotorisasi dengan Microsoft Entra ID untuk mengakses sumber daya Azure, lihat bagian Otorisasi akses dengan Microsoft Entra ID untuk memastikan prinsip keamanan memiliki izin yang memadai untuk mengakses sumber daya Azure.

Bagian berikut menjelaskan skenario yang menggunakan pustaka ekosistem Spring yang berbeda dengan autentikasi OAuth.

Dukungan aplikasi Spring Kafka

Bagian ini menjelaskan skenario penggunaan untuk aplikasi Spring Boot yang menggunakan Spring Kafka atau pustaka Spring Integration Kafka.

Penyiapan dependensi

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

Pembaruan konfigurasi

Untuk menggunakan autentikasi OAuth, tentukan titik akhir Azure Event Hubs, seperti yang ditunjukkan dalam contoh berikut:

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

Dukungan aplikasi untuk binder Kafka Spring Cloud Stream

Bagian ini menjelaskan skenario penggunaan untuk aplikasi Spring Boot yang menggunakan pustaka Kafka binder Spring Cloud Stream.

Penyiapan dependensi

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

Konfigurasi

Untuk menggunakan autentikasi OAuth, tentukan titik akhir Azure Event Hubs, seperti yang ditunjukkan dalam contoh berikut:

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

Nota

Jika Anda menggunakan versi 4.3.0, atur spring.cloud.stream.binders.<kafka-binder-name>.environment.spring.main.sources=com.azure.spring.cloud.autoconfigure.kafka.AzureKafkaSpringCloudStreamConfiguration properti untuk mengaktifkan seluruh alur kerja autentikasi OAuth. kafka-binder-name secara bawaan adalah kafka dalam aplikasi binder Kafka tunggal. Konfigurasi AzureKafkaSpringCloudStreamConfiguration menentukan parameter keamanan OAuth untuk KafkaBinderConfigurationProperties. Konfigurasi ini digunakan KafkaOAuth2AuthenticateCallbackHandler untuk mengaktifkan identitas Azure.

Untuk versi setelah 4.4.0, properti ini ditambahkan secara otomatis untuk setiap lingkungan binder Kafka, sehingga Anda tidak perlu menambahkannya secara manual.

Menggunakan identitas terkelola untuk autentikasi OAuth

Untuk menggunakan identitas terkelola, aktifkan identitas terkelola untuk layanan Anda dan tetapkan peran Azure Event Hubs Data Receiver dan Azure Event Hubs Data Sender. Untuk informasi selengkapnya, lihat Menetapkan peran Azure untuk hak akses.
Konfigurasikan properti berikut dalam file application.yml Anda:
```
spring:
  cloud:
    azure:
      credential:
        managed-identity-enabled: true
```
Penting

Jika Anda menggunakan identitas terkelola yang ditetapkan pengguna, tambahkan juga properti spring.cloud.azure.credential.client-id dengan ID klien identitas terkelola yang ditetapkan pengguna Anda.

Contoh

Lihat repositori azure-spring-boot-samples di GitHub.

Menggunakan autentikasi string koneksi

Anda dapat menggunakan autentikasi string koneksi secara langsung atau menggunakan Azure Resource Manager untuk mengambil string koneksi.

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

Nota

Sejak versi 5.0.0, saat menggunakan autentikasi string koneksi dengan kerangka kerja Spring Cloud Stream, Anda masih memerlukan properti berikut untuk memastikan bahwa string koneksi berfungsi. Nilai <kafka-binder-name> harus berupa kafka jika Anda tidak menyesuaikan nama binder Kafka: spring.cloud.stream.binders.<kafka-binder-name>.environment.spring.main.sources=com.azure.spring.cloud.autoconfigure.implementation.eventhubs.kafka.AzureEventHubsKafkaAutoConfiguration

Jika versi yang spring-cloud-dependencies Anda gunakan adalah 2022.0.0, Anda mengalami pengecualian java.lang.IllegalStateException: kafka_context has not been refreshed yet. Untuk mengatasi masalah ini, tingkatkan ke versi yang lebih tinggi.

Nota

Sejak versi 4.3.0, autentikasi string koneksi tidak digunakan lagi demi autentikasi OAuth.

Sejak versi 4.5.0, saat menggunakan autentikasi string koneksi dengan kerangka kerja Spring Cloud Stream, Anda memerlukan properti berikut untuk memastikan bahwa string koneksi berfungsi. Nilai <kafka-binder-name> harus bernilai kafka jika Anda tidak menyesuaikan nama binder Kafka: spring.cloud.stream.binders.<kafka-binder-name>.environment.spring.main.sources=com.azure.spring.cloud.autoconfigure.eventhubs.kafka.AzureEventHubsKafkaAutoConfiguration

Penyiapan dependensi

Tambahkan dependensi berikut jika Anda ingin memigrasikan aplikasi Apache Kafka Anda untuk menggunakan Azure Event Hubs untuk Kafka.

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

Jika Anda ingin mengambil string koneksi dengan menggunakan Azure Resource Manager, tambahkan dependensi berikut:

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

Konfigurasi

Gunakan string koneksi Event Hubs secara langsung

Cara paling sederhana untuk terhubung ke Azure Event Hubs for Kafka adalah dengan string koneksi. Cukup tambahkan properti berikut.

spring.cloud.azure.eventhubs.connection-string=${AZURE_EVENTHUBS_CONNECTION_STRING}

Menggunakan Azure Resource Manager untuk mengambil string koneksi

Jika Anda tidak ingin mengonfigurasi string koneksi di aplikasi, Anda dapat menggunakan Azure Resource Manager untuk mengambil string koneksi. Untuk mengautentikasi dengan Azure Resource Manager, Anda juga dapat menggunakan kredensial yang disimpan di Azure CLI atau alat pengembangan lokal lainnya seperti Visual Studio Code atau Intellij IDEA. Secara bergantian, Anda dapat menggunakan Identitas Terkelola jika aplikasi Anda disebarkan ke Azure Cloud. Cukup pastikan prinsipal memiliki izin yang memadai untuk membaca metadata sumber daya.

Nota

Untuk menggunakan Azure Resource Manager untuk mengambil string koneksi, cukup tambahkan properti berikut.

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

Contoh

Lihat repositori azure-spring-boot-samples di GitHub.

Saran dan Komentar

Apakah halaman ini membantu?

Last updated on 2026-09-21

Dukungan Spring Cloud Azure Kafka

Versi Kafka yang didukung

Jenis autentikasi yang didukung

Cara kerjanya

Autentikasi kredensial OAuth

Autentikasi string koneksi biasa

Konfigurasi

Properti yang dapat dikonfigurasi saat menggunakan dukungan Kafka dengan autentikasi OAuth

Properti yang dapat dikonfigurasi saat menggunakan dukungan Kafka dengan autentikasi string koneksi biasa

Penyiapan dependensi

Penggunaan dasar

Menggunakan autentikasi OAuth

Dukungan aplikasi Spring Kafka

Penyiapan dependensi

Pembaruan konfigurasi

Dukungan aplikasi untuk binder Kafka Spring Cloud Stream

Penyiapan dependensi

Konfigurasi

Menggunakan identitas terkelola untuk autentikasi OAuth

Contoh

Menggunakan autentikasi string koneksi

Penyiapan dependensi

Konfigurasi

Gunakan string koneksi Event Hubs secara langsung

Menggunakan Azure Resource Manager untuk mengambil string koneksi

Contoh

Saran dan Komentar

Sumber Daya Tambahan: