Panduan Pemrograman .NET untuk Azure Event Hubs (paket Microsoft.Azure.EventHubs warisan)

Artikel ini membahas beberapa skenario umum dalam menulis kode menggunakan Azure Event Hubs. Ini mengasumsikan pemahaman awal tentang Pusat Aktivitas. Untuk gambaran umum konseptual Pusat Aktivitas, lihat gambaran umum Pusat Aktivitas.

Peringatan

Panduan ini untuk paket Microsoft.Azure.EventHubs lama. Kami menyarankan agar Anda memigrasikan kode untuk menggunakan paket Azure.Messaging.EventHubs terbaru.

Penerbit aktivitas

Anda mengirim aktivitas ke pusat aktivitas baik menggunakan HTTP POST maupun melalui koneksi AMQP 1.0. Pilihan yang akan digunakan dan waktu bergantung pada skenario tertentu yang ditangani. Koneksi AMQP 1.0 diukur sebagai koneksi broker di Bus Layanan dan lebih tepat dalam skenario dengan volume pesan yang sering kali lebih tinggi dan persyaratan latensi yang lebih rendah, karena menyediakan saluran olahpesan yang persisten.

Saat menggunakan API yang dikelola .NET, konstruksi utama untuk menerbitkan data ke Pusat Aktivitas adalah kelas EventHubClient dan EventData. EventHubClient menyediakan saluran komunikasi AMQP tempat aktivitas dikirim ke pusat aktivitas. Kelas EventData mewakili acara, dan digunakan untuk menerbitkan pesan ke pusat aktivitas. Kelas ini mencakup isi, beberapa metadata(Properties), dan informasi header(SystemProperties) tentang aktivitas tersebut. Properti lain ditambahkan ke objek EventData saat melewati pusat aktivitas.

Mulai

Kelas .NET yang mendukung Pusat Aktivitas disediakan dalam paket Microsoft.Azure.EventHubs NuGet. Anda dapat menginstal menggunakan penjelajah Solusi Visual Studio, atau Package Manager Console di Visual Studio. Untuk melakukannya, terbitkan perintah berikut di jendela Package Manager Console:

Install-Package Microsoft.Azure.EventHubs

Membuat pusat aktivitas

Anda dapat menggunakan portal Azure, Azure PowerShell, atau Azure CLI untuk membuat Pusat Aktivitas. Untuk detailnya, lihat Buat namespace Pusat Aktivitas dan pusat aktivitas menggunakan portal Azure.

Membuat klien Pusat Aktivitas

Kelas utama untuk berinteraksi dengan Pusat Aktivitas adalah Microsoft.Azure.EventHubs.EventHubClient. Anda dapat membuat instans kelas ini menggunakan metode CreateFromConnectionString, seperti ditunjukkan dalam contoh berikut:

private const string EventHubConnectionString = "Event Hubs namespace connection string";
private const string EventHubName = "event hub name";

var connectionStringBuilder = new EventHubsConnectionStringBuilder(EventHubConnectionString)
{
    EntityPath = EventHubName

};
eventHubClient = EventHubClient.CreateFromConnectionString(connectionStringBuilder.ToString());

Mengirim aktivitas ke pusat aktivitas

Anda mengirim aktivitas ke pusat aktivitas dengan membuat instans EventHubClient dan mengirimkannya secara asinkron melalui metode SendAsync. Metode ini mengambil satu parameter instans EventData dan secara asinkron mengirimkannya ke pusat aktivitas.

Serialisasi aktivitas

Kelas EventData memiliki dua konstruktor kelebihan beban yang mengambil berbagai parameter, byte, atau array byte, yang mewakili payload data aktivitas. Saat menggunakan JSON dengan EventData, Anda dapat menggunakan Encoding.UTF8.GetBytes() untuk mengambil array byte untuk string yang dikodekan JSON. Contohnya:

for (var i = 0; i < numMessagesToSend; i++)
{
    var message = $"Message {i}";
    Console.WriteLine($"Sending message: {message}");
    await eventHubClient.SendAsync(new EventData(Encoding.UTF8.GetBytes(message)));
}

Kunci partisi

Catatan

Jika Anda tidak terbiasa dengan partisi, lihat artikel ini.

Saat mengirim data aktivitas, Anda dapat menentukan nilai yang di-hash untuk menghasilkan penetapan partisi. Anda menentukan partisi menggunakan properti PartitionSender.PartitionID. Namun, keputusan untuk menggunakan partisi menyiratkan pilihan antara ketersediaan dan konsistensi. Untuk informasi selengkapnya, lihat Ketersediaan dan Konsistensi.

Operasi pengiriman aktivitas secara berkelompok

Mengirim aktivitas secara berkelompok dapat membantu meningkatkan throughput. Anda dapat menggunakan API CreateBatch untuk membuat objek data secara berkelompok yang nantinya dapat ditambahkan untuk panggilan SendAsync.

Satu kelompok tidak boleh melebihi batas aktivitas 1 MB. Selain itu, setiap pesan secara berkelompok menggunakan identitas penerbit yang sama. Pengirim bertanggung jawab untuk memastikan bahwa kelompok tidak melebihi ukuran aktivitas maksimum. Jika ya, terjadi kesalahan Kirim oleh klien. Anda dapat menggunakan metode pembantu EventHubClient.CreateBatch untuk memastikan bahwa kelompok tidak melebihi 1 MB. Anda mendapatkan EventDataBatch kosong dari API CreateBatch dan kemudian menggunakan TryAdd agar menambahkan aktivitas untuk membuat kelompok.

Kirim secara asinkron dan kirim dalam skala besar

Anda mengirim aktivitas ke pusat aktivitas secara asinkron. Mengirim secara asinkron meningkatkan tingkat di mana klien mampu mengirim aktivitas. SendAsync mengembalikan objek Tugas. Anda dapat menggunakan kelas RetryPolicy pada klien untuk mengontrol opsi coba lagi bagi klien.

Konsumen aktivitas

Kelas EventProcessorHost memproses data dari Pusat Aktivitas. Anda harus menggunakan implementasi ini saat membangun pembaca aktivitas di platform .NET. EventProcessorHost menyediakan lingkungan runtime alur yang aman, berbagai proses, dan aman untuk penerapan prosesor aktivitas yang juga menyediakan manajemen titik pemeriksaan dan sewa partisi.

Untuk menggunakan kelas EventProcessorHost, Anda dapat menerapkan IEventProcessor. Antarmuka ini memuat empat metode:

Untuk memulai pemrosesan aktivitas, buat instans EventProcessorHost, yang menyediakan parameter yang sesuai untuk pusat aktivitas Anda. Contohnya:

var eventProcessorHost = new EventProcessorHost(
        EventHubName,
        PartitionReceiver.DefaultConsumerGroupName,
        EventHubConnectionString,
        StorageConnectionString,
        StorageContainerName);

Kemudian, panggil RegisterEventProcessorAsync untuk mendaftarkan penerapan IEventProcessor Anda dengan runtime:

await eventProcessorHost.RegisterEventProcessorAsync<SimpleEventProcessor>();

Pada titik ini, host berupaya untuk memperoleh sewa pada setiap partisi di pusat aktivitas menggunakan algoritma yang "serakah". Sewa ini berlangsung untuk jangka waktu tertentu dan kemudian harus diperbarui. Sebagai node baru, instans pekerja dalam hal ini, menjadi online, mereka melakukan reservasi sewa dan seiring waktu beban bergeser di antara node ketika masing-masing berupaya untuk memperoleh lebih banyak sewa.

Host Prosesor Aktivitas

Seiring waktu, keseimbangan tersambung. Kemampuan dinamis ini memungkinkan penskalaan otomatis berbasis CPU diterapkan pada para konsumen untuk peningkatan dan penurunan skala. Karena Pusat Aktivitas tidak memiliki konsep langsung jumlah pesan, rata-rata pemanfaatan CPU sering kali merupakan mekanisme terbaik untuk mengukur back end atau skala konsumen. Jika penerbit mulai memublikasikan lebih banyak aktivitas daripada yang dapat diproses konsumen, peningkatan CPU pada konsumen dapat digunakan untuk menyebabkan penskalaan otomatis pada jumlah instans pekerja.

Kelas EventProcessorHost juga menerapkan mekanisme titik pemeriksaan berbasis penyimpanan Azure. Mekanisme ini menyimpan offset berdasarkan per partisi, sehingga setiap konsumen dapat menentukan titik pemeriksaan terakhir dari konsumen sebelumnya. Sebagai transisi partisi di antara node melalui sewa, ini adalah mekanisme sinkronisasi yang memfasilitasi pergeseran beban.

Pencabutan penerbit

Selain fitur run-time lanjutan dari Host Prosesor Aktivitas, layanan Pusat Aktivitas memungkinkan pencabutan penerbit untuk memblokir penerbit tertentu agar tidak mengirim aktivitas ke pusat aktivitas. Fitur-fitur ini berguna jika token penerbit telah disusupi, atau pembaruan perangkat lunak menyebabkan mereka berperilaku tidak pantas. Dalam situasi ini, identitas penerbit, yang merupakan bagian dari token SAS mereka, dapat diblokir dari aktivitas penerbitan.

Catatan

Saat ini, hanya REST API yang mendukung fitur ( pencabutan penerbit) ini.

Langkah berikutnya

Untuk mempelajari selengkapnya tentang skenario Pusat Aktivitas, kunjungi tautan-tautan berikut: