Mulai cepat: Mengirim peristiwa ke dan menerima peristiwa dari Azure Event Hubs menggunakan .NET

  • Artikel

Dalam mulai cepat ini, Anda mempelajari cara mengirim peristiwa ke pusat aktivitas lalu menerima peristiwa tersebut dari hub peristiwa menggunakan pustaka .NET Azure.Messaging.EventHubs .

Catatan

Mulai cepat adalah bagi Anda untuk dengan cepat meningkatkan layanan. Jika Anda sudah terbiasa dengan layanan ini, Anda mungkin ingin melihat sampel .NET untuk Azure Event Hubs di repositori .NET SDK kami di GitHub: Sampel Azure Event Hubs di GitHub, Sampel prosesor peristiwa di GitHub.

Prasyarat

Jika Anda baru menggunakan Azure Event Hubs, lihat Gambaran umum Azure Event Hubs sebelum Anda melalui mulai cepat ini.

Untuk menyelesaikan mulai cepat ini, Anda memerlukan prasyarat berikut:

  • Langganan Microsoft Azure. Untuk menggunakan layanan Azure, termasuk Azure Event Hubs, Anda memerlukan langganan. Jika Anda belum memiliki akun Azure, Anda dapat mendaftar untuk coba gratis atau memanfaatkan pelanggan MSDN saat Anda membuat akun.
  • Microsoft Visual Studio 2022. Pustaka klien Azure Event Hubs memanfaatkan fitur baru yang diperkenalkan di C# 8.0. Anda masih dapat menggunakan pustaka dengan versi bahasa C# sebelumnya, tetapi sintaks baru tidak tersedia. Untuk memanfaatkan sintaks penuh, sebaiknya Anda mengompilasi dengan .NET Core SDK 3.0 atau lebih tinggi dan versi bahasa komputer diatur ke latest. Jika Anda menggunakan Visual Studio, versi sebelum Visual Studio 2022 tidak kompatibel dengan alat yang diperlukan untuk membangun proyek C# 8.0. Visual Studio 2022, termasuk edisi Komunitas gratis, dapat diunduh di sini.
  • Membuat ruang nama Azure Event Hubs dan pusat aktivitas. Langkah pertama adalah menggunakan portal Azure untuk membuat namespace layanan Azure Event Hubs dan pusat aktivitas di namespace layanan. Kemudian, dapatkan kredensial manajemen yang perlu dikomunikasikan oleh aplikasi Anda dengan pusat aktivitas. Untuk membuat namespace layanan dan pusat aktivitas, lihat Mulai Cepat: Membuat hub peristiwa menggunakan portal Azure.

Mengautentikasi aplikasi ke Azure

Mulai cepat ini menunjukkan kepada Anda dua cara menyambungkan ke Azure Event Hubs:

  • Tanpa kata sandi (autentikasi Microsoft Entra)
  • String koneksi

Opsi pertama menunjukkan cara menggunakan prinsip keamanan Anda di Azure Active Directory dan kontrol akses berbasis peran (RBAC) untuk menyambungkan ke namespace Layanan Pusat Aktivitas. Anda tidak perlu khawatir tentang memiliki string koneksi yang dikodekan secara permanen dalam kode Anda atau dalam file konfigurasi atau dalam penyimpanan aman seperti Azure Key Vault.

Opsi kedua menunjukkan cara menggunakan string koneksi untuk menyambungkan ke namespace Layanan Pusat Aktivitas. Jika Anda baru menggunakan Azure, Anda mungkin menemukan opsi string koneksi lebih mudah diikuti. Sebaiknya gunakan opsi tanpa kata sandi di aplikasi dunia nyata dan lingkungan produksi. Untuk informasi selengkapnya, lihat Autentikasi dan otorisasi. Anda juga dapat membaca selengkapnya tentang autentikasi tanpa kata sandi di halaman gambaran umum.

Menetapkan peran ke pengguna Microsoft Entra Anda

Saat mengembangkan secara lokal, pastikan bahwa akun pengguna yang tersambung ke Azure Event Hubs memiliki izin yang benar. Anda memerlukan peran Pemilik Data Azure Event Hubs untuk mengirim dan menerima pesan. Untuk menetapkan sendiri peran ini, Anda memerlukan peran Administrator Akses Pengguna, atau peran lain yang menyertakan tindakan.Microsoft.Authorization/roleAssignments/write Anda dapat menetapkan peran Azure RBAC kepada pengguna menggunakan portal Azure, Azure CLI, atau Azure PowerShell. Pelajari selengkapnya tentang cakupan yang tersedia untuk penetapan peran di halaman gambaran umum cakupan .

Contoh berikut menetapkan peran ke Azure Event Hubs Data Owner akun pengguna Anda, yang menyediakan akses penuh ke sumber daya Azure Event Hubs. Dalam skenario nyata, ikuti Prinsip Hak Istimewa Paling Sedikit untuk memberi pengguna hanya izin minimum yang diperlukan untuk lingkungan produksi yang lebih aman.

Peran bawaan Azure untuk Azure Event Hubs

Untuk Azure Event Hubs, pengelolaan namespace layanan dan semua sumber daya terkait melalui portal Azure dan API manajemen sumber daya Azure sudah dilindungi menggunakan model Azure RBAC. Azure menyediakan peran bawaan Azure di bawah ini untuk mengotorisasi akses ke namespace Layanan Pusat Aktivitas:

  • Pemilik Data Azure Event Hubs: Memungkinkan akses data ke namespace Layanan Pusat Aktivitas dan entitasnya (antrean, topik, langganan, dan filter)
  • Pengirim Data Azure Event Hubs: Gunakan peran ini untuk memberi pengirim akses ke namespace layanan Azure Event Hubs dan entitasnya.
  • Penerima Data Azure Event Hubs: Gunakan peran ini untuk memberi penerima akses ke namespace Layanan Azure Event Hubs dan entitasnya.

Jika Anda ingin membuat peran kustom, lihat Hak yang diperlukan untuk operasi Azure Event Hubs.

Penting

Dalam kebanyakan kasus, akan memakan waktu satu atau dua menit agar penetapan peran disebarluaskan di Azure. Dalam kasus yang jarang terjadi, mungkin perlu waktu hingga delapan menit. Jika Anda menerima kesalahan autentikasi saat pertama kali menjalankan kode, tunggu beberapa saat dan coba lagi.

  1. Di portal Azure, temukan namespace Layanan Pusat Aktivitas Anda menggunakan bilah pencarian utama atau navigasi kiri.

  2. Pada halaman gambaran umum, pilih Kontrol akses (IAM) dari menu sebelah kiri.

  3. Di halaman Kontrol akses (IAM), pilih tab Penetapan peran.

  4. Pilih + Tambahkan dari menu atas lalu Tambahkan penetapan peran dari menu drop-down yang dihasilkan.

    Cuplikan layar yang menampilkan cara menetapkan peran.

  5. Gunakan kotak pencarian untuk memfilter hasil ke peran yang diinginkan. Untuk contoh ini, cari Azure Event Hubs Data Owner dan pilih hasil yang cocok. Kemudian pilih Berikutnya.

  6. Di bagian Tetapkan akses ke, pilih Pengguna, grup, atau perwakilan layanan, lalu pilih + Pilih anggota.

  7. Dalam dialog, cari nama pengguna Microsoft Entra Anda (biasanya alamat email user@domain Anda) lalu pilih Pilih di bagian bawah dialog.

  8. Pilih Tinjau + tetapkan untuk masuk ke halaman akhir, lalu Tinjau + tetapkan lagi untuk menyelesaikan proses.

Luncurkan Visual Studio dan masuk ke Azure

Anda dapat mengotorisasi akses ke namespace bus layanan menggunakan langkah-langkah berikut:

  1. Luncurkan Visual Studio. Jika Anda melihat jendela Mulai , pilih tautan Lanjutkan tanpa kode di panel kanan.

  2. Pilih tombol Masuk di kanan atas Visual Studio.

    Cuplikan layar memperlihatkan tombol untuk masuk ke Azure menggunakan Visual Studio.

  3. Masuk menggunakan akun Microsoft Entra yang Anda tetapkan perannya sebelumnya.

    Cuplikan layar yang menampilkan pemilihan akun.

Mengirim peristiwa ke pusat aktivitas

Bagian ini menunjukkan kepada Anda cara membuat aplikasi konsol .NET Core untuk mengirim peristiwa ke pusat aktivitas yang Anda buat.

Membuat aplikasi konsol lokal

  1. Jika Anda sudah membuka Visual Studio 2022, pilih File pada menu, pilih Baru, lalu pilih Proyek. Jika tidak, luncurkan Visual Studio 2022 dan pilih Buat proyek baru jika Anda melihat jendela popup.

  2. Pada kotak dialog Buat proyek baru, lakukan langkah-langkah berikut ini: Jika Anda tidak melihat kotak dialog ini, pilih File pada menu, pilih Baru, lalu pilih Proyek.

    1. Untuk C# untuk bahasa pemrograman.

    2. Pilih Konsol untuk jenis aplikasi.

    3. Pilih Aplikasi Konsol dari daftar hasil.

    4. Kemudian, pilih Berikutnya.

      Gambar yang menunjukkan kotak dialog Proyek Baru

  3. Masukkan EventHubsSender untuk nama proyek, EventHubsQuickStart untuk nama solusi, lalu pilih Berikutnya.

    Gambar yang menunjukkan halaman tempat Anda memasukkan nama solusi dan proyek

  4. Di halaman Informasi tambahan, pilih Buat.

Menambahkan paket NuGet ke proyek

  1. Pilih Alat>NuGet Package Manager>Package Manager Console dari menu.

  2. Jalankan perintah berikut untuk menginstal paket Azure.Messaging.EventHubs dan Azure.Identity NuGet. Tekan ENTER untuk menjalankan perintah kedua.

    Install-Package Azure.Messaging.EventHubs
Install-Package Azure.Identity

Menulis kode untuk mengirim peristiwa ke pusat aktivitas

  1. Ganti kode yang ada dalam Program.cs file dengan kode sampel berikut. Kemudian, ganti <EVENT_HUB_NAMESPACE> nilai tempat penampung dan <HUB_NAME> untuk EventHubProducerClient parameter dengan nama namespace Layanan Pusat Aktivitas dan pusat aktivitas Anda. Misalnya: "spehubns0309.servicebus.windows.net" dan "spehub".

    Berikut langkah-langkah penting dari kode:

    1. Membuat objek EventHubProducerClient menggunakan namespace layanan dan nama hub peristiwa.
    2. Memanggil metode CreateBatchAsync pada objek EventHubProducerClient untuk membuat objek EventDataBatch .
    3. Tambahkan peristiwa ke batch menggunakan metode EventDataBatch.TryAdd.
    4. Mengirim batch pesan ke hub peristiwa menggunakan metode EventHubProducerClient.SendAsync.
    using Azure.Identity;
using Azure.Messaging.EventHubs;
using Azure.Messaging.EventHubs.Producer;
using System.Text;

// number of events to be sent to the event hub
int numOfEvents = 3;

// The Event Hubs client types are safe to cache and use as a singleton for the lifetime
// of the application, which is best practice when events are being published or read regularly.
// TODO: Replace the <EVENT_HUB_NAMESPACE> and <HUB_NAME> placeholder values
EventHubProducerClient producerClient = new EventHubProducerClient(
    "<EVENT_HUB_NAMESPACE>.servicebus.windows.net",
    "<HUB_NAME>",
    new DefaultAzureCredential());

// Create a batch of events 
using EventDataBatch eventBatch = await producerClient.CreateBatchAsync();

for (int i = 1; i <= numOfEvents; i++)
{
    if (!eventBatch.TryAdd(new EventData(Encoding.UTF8.GetBytes($"Event {i}"))))
    {
        // if it is too large for the batch
        throw new Exception($"Event {i} is too large for the batch and cannot be sent.");
    }
}

try
{
    // Use the producer client to send the batch of events to the event hub
    await producerClient.SendAsync(eventBatch);
    Console.WriteLine($"A batch of {numOfEvents} events has been published.");
    Console.ReadLine();
}
finally
{
    await producerClient.DisposeAsync();
}

  1. Bangun program, dan pastikan tidak ada kesalahan.

  2. Jalankan program dan tunggu pesan konfirmasi.

    A batch of 3 events has been published.

    Penting

    Jika Anda menggunakan autentikasi Tanpa Kata Sandi (Kontrol Akses Berbasis Peran Azure Active Directory), pilih Alat, lalu pilih Opsi. Di jendela Opsi , perluas Autentikasi Layanan Azure, dan pilih Pilihan Akun. Konfirmasikan bahwa Anda menggunakan akun yang ditambahkan ke peran Pemilik Data Azure Event Hubs di namespace layanan Azure Event Hubs.

  3. Pada halaman Namespace Layanan Pusat Aktivitas di portal Azure, Anda akan melihat tiga pesan masuk di bagan Pesan. Refresh halaman untuk memperbarui bagan jika diperlukan. Mungkin dibutuhkan waktu beberapa detik untuk menunjukkan bahwa pesan telah diterima.

    Gambar halaman portal Microsoft Azure untuk memverifikasi bahwa pusat aktivitas telah menerima peristiwa

    Catatan

    Untuk kode sumber lengkap dengan komentar informasi selengkapnya, lihat file ini di GitHub

Menerima peristiwa dari pusat aktivitas

Bagian ini menunjukkan cara menulis aplikasi konsol .NET Core yang menerima acara dari pusat aktivitas menggunakan prosesor acara. Prosesor peristiwa menyederhanakan penerimaan peristiwa dari hub peristiwa.

Membuat Akun Azure Storage dan kontainer blob

Dalam mulai cepat ini, Anda menggunakan Azure Storage sebagai penyimpanan titik pemeriksaan. Ikuti langkah-langkah berikut untuk membuat akun Azure Storage.

  1. Membuat akun Microsoft Azure Storage
  2. Membuat kontainer blob
  3. Autentikasi ke kontainer blob menggunakan autentikasi ID Microsoft Entra (tanpa kata sandi) atau string koneksi ke namespace layanan.

Ikuti rekomendasi ini saat menggunakan Azure Blob Storage sebagai penyimpanan titik pemeriksaan:

  • Gunakan kontainer terpisah untuk setiap grup konsumen. Anda dapat menggunakan akun penyimpanan yang sama, tetapi menggunakan satu kontainer per setiap grup.
  • Jangan gunakan kontainer untuk hal lain, dan jangan gunakan akun penyimpanan untuk hal lain.
  • Akun penyimpanan harus berada di wilayah yang sama dengan aplikasi yang disebarkan berada. Jika aplikasi lokal, coba pilih wilayah terdekat yang mungkin.

Pada halaman Akun penyimpanan di portal Azure, di bagian Blob service, pastikan bahwa pengaturan berikut dinonaktifkan.

  • Namespace hierarkis
  • Penghapusan sementara blob
  • Penerapan versi

Saat mengembangkan secara lokal, pastikan bahwa akun pengguna yang mengakses data blob memiliki izin yang benar. Anda akan memerlukan Kontributor Data Blob Penyimpanan untuk membaca dan menulis data blob. Untuk menetapkan sendiri peran ini, Anda harus diberi peran Administrator Akses Pengguna, atau peran lain yang menyertakan tindakan Microsoft.Authorization/roleAssignments/write . Anda dapat menetapkan peran Azure RBAC kepada pengguna menggunakan portal Azure, Azure CLI, atau Azure PowerShell. Anda dapat mempelajari selengkapnya tentang cakupan yang tersedia untuk penetapan peran di halaman gambaran umum cakupan.

Dalam skenario ini, Anda akan menetapkan izin ke akun pengguna, yang tercakup ke akun penyimpanan, untuk mengikuti Prinsip Hak Istimewa Paling Rendah. Praktik ini hanya memberi pengguna izin minimum yang diperlukan dan menciptakan lingkungan produksi yang lebih aman.

Contoh berikut akan menetapkan peran Kontributor Data Blob Penyimpanan ke akun pengguna Anda, yang menyediakan akses baca dan tulis ke data blob di akun penyimpanan Anda.

Penting

Dalam kebanyakan kasus, dibutuhkan satu atau dua menit agar penetapan peran disebarluaskan di Azure, tetapi dalam kasus yang jarang terjadi mungkin perlu waktu hingga delapan menit. Jika Anda menerima kesalahan autentikasi saat pertama kali menjalankan kode, tunggu beberapa saat dan coba lagi.

  1. Di portal Azure, temukan akun penyimpanan Anda menggunakan bilah pencarian utama atau navigasi kiri.

  2. Di halaman gambaran umum akun penyimpanan, pilih Kontrol akses (IAM) dari menu kiri.

  3. Di halaman Kontrol akses (IAM), pilih tab Penetapan peran.

  4. Pilih + Tambahkan dari menu atas lalu Tambahkan penetapan peran dari menu drop-down yang dihasilkan.

    Cuplikan layar yang menunjukkan cara menetapkan peran akun penyimpanan.

  5. Gunakan kotak pencarian untuk memfilter hasil ke peran yang diinginkan. Untuk contoh ini, cari Kontributor Data Blob Penyimpanan dan pilih hasil yang cocok, lalu pilih Berikutnya.

  6. Di bagian Tetapkan akses ke, pilih Pengguna, grup, atau perwakilan layanan, lalu pilih + Pilih anggota.

  7. Dalam dialog, cari nama pengguna Microsoft Entra Anda (biasanya alamat email user@domain Anda) lalu pilih Pilih di bagian bawah dialog.

  8. Pilih Tinjau + tetapkan untuk masuk ke halaman akhir, lalu Tinjau + tetapkan lagi untuk menyelesaikan proses.

Membuat proyek untuk penerima

  1. Di jendela Penjelajah Solusi, klik kanan solusi EventHubQuickStart, arahkan ke Tambahkan, dan pilih Proyek Baru.
  2. Pilih Aplikasi konsol, lalu pilih Selanjutnya.
  3. Masukkan EventHubsReceiver untuk nama Proyek, dan pilih Buat.
  4. Di jendela Penjelajah Solusi, klik kanan EventHubsReceiver, lalu pilih Atur sebagai Proyek Startup.

Menambahkan paket NuGet ke proyek

  1. Pilih Alat>NuGet Package Manager>Package Manager Console dari menu.

  2. Di jendela Konsol Manajer Paket, konfirmasikan bahwa EventHubsReceiver dipilih sebagai proyek Default. Jika tidak, gunakan daftar drop-down untuk memilih EventHubsReceiver.

  3. Jalankan perintah berikut untuk menginstal paket Azure.Messaging.EventHubs dan Azure.Identity NuGet. Tekan ENTER untuk menjalankan perintah terakhir.

    Install-Package Azure.Messaging.EventHubs
Install-Package Azure.Messaging.EventHubs.Processor
Install-Package Azure.Identity

Memperbarui kode

Ganti konten Program.cs dengan kode berikut:

  1. Ganti kode yang ada dalam Program.cs file dengan kode sampel berikut. Kemudian, ganti <STORAGE_ACCOUNT_NAME> nilai tempat penampung dan <BLOB_CONTAINER_NAME> untuk BlobContainerClient URI. <EVENT_HUB_NAMESPACE> Ganti nilai tempat penampung dan <HUB_NAME> untuk EventProcessorClient juga.

    Berikut langkah-langkah penting dari kode:

    1. Membuat objek EventProcessorClient menggunakan namespace Layanan Pusat Aktivitas dan nama hub peristiwa. Anda perlu membangun objek BlobContainerClient untuk kontainer di penyimpanan Azure yang Anda buat sebelumnya.
    2. Menentukan penangan untuk peristiwa ProcessEventAsync dan ProcessErrorAsync dari objek EventProcessorClient.
    3. Mulai memproses peristiwa dengan meminta StartProcessingAsync pada objek EventProcessorClient.
    4. Berhenti memproses peristiwa setelah 30 detik dengan memanggil StopProcessingAsync pada objek EventProcessorClient .
    using Azure.Identity;
using Azure.Messaging.EventHubs;
using Azure.Messaging.EventHubs.Consumer;
using Azure.Messaging.EventHubs.Processor;
using Azure.Storage.Blobs;
using System.Text;

// Create a blob container client that the event processor will use
// TODO: Replace <STORAGE_ACCOUNT_NAME> and <BLOB_CONTATINAER_NAME> with actual names
BlobContainerClient storageClient = new BlobContainerClient(
    new Uri("https://<STORAGE_ACCOUNT_NAME>.blob.core.windows.net/<BLOB_CONTAINER_NAME>"),
    new DefaultAzureCredential());

// Create an event processor client to process events in the event hub
// TODO: Replace the <EVENT_HUBS_NAMESPACE> and <HUB_NAME> placeholder values
var processor = new EventProcessorClient(
    storageClient,
    EventHubConsumerClient.DefaultConsumerGroupName,
    "<EVENT_HUB_NAMESPACE>.servicebus.windows.net",
    "<HUB_NAME>",
    new DefaultAzureCredential());

// Register handlers for processing events and handling errors
processor.ProcessEventAsync += ProcessEventHandler;
processor.ProcessErrorAsync += ProcessErrorHandler;

// Start the processing
await processor.StartProcessingAsync();

// Wait for 30 seconds for the events to be processed
await Task.Delay(TimeSpan.FromSeconds(30));

// Stop the processing
await processor.StopProcessingAsync();

Task ProcessEventHandler(ProcessEventArgs eventArgs)
{
    // Write the body of the event to the console window
    Console.WriteLine("\tReceived event: {0}", Encoding.UTF8.GetString(eventArgs.Data.Body.ToArray()));
    Console.ReadLine();
    return Task.CompletedTask;
}

Task ProcessErrorHandler(ProcessErrorEventArgs eventArgs)
{
    // Write details about the error to the console window
    Console.WriteLine($"\tPartition '{eventArgs.PartitionId}': an unhandled exception was encountered. This was not expected to happen.");
    Console.WriteLine(eventArgs.Exception.Message);
    Console.ReadLine();
    return Task.CompletedTask;
}

  1. Bangun program, dan pastikan tidak ada kesalahan.

    Catatan

    Untuk kode sumber lengkap dengan komentar informasi selengkapnya, lihat file ini di GitHub.

  2. Jalankan aplikasi penerima.

  3. Anda akan melihat pesan bahwa acara telah diterima. Tekan ENTER setelah Anda melihat pesan peristiwa yang diterima.

    Received event: Event 1
Received event: Event 2
Received event: Event 3

    Peristiwa ini adalah tiga acara yang Anda kirim ke pusat acara sebelumnya dengan menjalankan program pengirim.

  4. Dalam portal Azure, Anda dapat memverifikasi bahwa ada tiga pesan keluar, yang dikirim Azure Event Hubs ke aplikasi penerima. Refresh halaman untuk memperbarui bagan. Mungkin dibutuhkan waktu beberapa detik untuk menunjukkan bahwa pesan telah diterima.

    Gambar halaman portal Microsoft Azure untuk memverifikasi bahwa pusat aktivitas telah menerima peristiwa

Validasi skema untuk aplikasi berbasis Azure Event Hubs SDK

Anda dapat menggunakan Azure Schema Registry untuk melakukan validasi skema saat melakukan streaming data dengan aplikasi berbasis Event Hubs SDK Anda. Azure Schema Registry of Event Hubs menyediakan repositori terpusat untuk mengelola skema dan Anda dapat dengan mulus menghubungkan aplikasi baru atau yang sudah ada dengan Schema Registry.

Untuk mempelajari selengkapnya, lihat Memvalidasi skema dengan Event Hubs SDK.

Sampel dan referensi

Mulai cepat ini menyediakan instruksi langkah demi langkah untuk mengimplementasikan skenario pengiriman batch peristiwa ke pusat aktivitas lalu menerimanya. Untuk sampel lainnya, pilih tautan berikut.

Untuk referensi pustaka .NET lengkap, lihat dokumentasi SDK kami.

Membersihkan sumber daya

Hapus grup sumber daya yang memiliki namespace Layanan Pusat Aktivitas atau hapus hanya namespace jika Anda ingin menyimpan grup sumber daya.

Konten terkait

Lihat tutorial berikut:

Tutorial: Memvisualisasikan anomali data dalam peristiwa real time yang dikirim ke Azure Event Hubs