Pemicu dan pengikatan Azure Event Hubs untuk Azure Functions

  • Artikel

Artikel ini menjelaskan cara bekerja dengan pengikatan Azure Event Hubs untuk Azure Functions. Azure Functions mendukung pemicu dan pengikatan output untuk Event Hubs.

Perbuatan Jenis
Menanggapi peristiwa yang dikirim ke aliran peristiwa event hub. Pemicu
Menulis peristiwa ke aliran peristiwa Pengikatan output

Menginstal ekstensi

Paket NuGet ekstensi yang Anda instal bergantung pada mode C# yang Anda gunakan di aplikasi fungsi Anda:

Functions dijalankan dalam proses pekerja C# yang terisolasi. Untuk mempelajari selengkapnya, lihat Panduan untuk menjalankan C# Azure Functions dalam proses pekerja yang terisolasi.

Fungsionalitas ekstensi tersebut bervariasi tergantung pada versi ekstensi:

Versi ini memperkenalkan kemampuan untuk menyambungkan menggunakan identitas alih-alih rahasia. Untuk tutorial cara mengonfigurasi aplikasi fungsi Anda dengan identitas terkelola, lihat tutorial membuat aplikasi fungsi dengan koneksi berbasis identitas.

Tambahkan ekstensi ke proyek Anda dengan menginstal paket NuGet, versi 5.x.

Memasang bundel

Ekstensi Azure Event Hubs adalah bagian dari bundel ekstensi, yang ditentukan dalam file proyek host.json. Anda mungkin perlu mengubah bundel ini untuk mengubah versi pengikatan, atau jika bundel belum terinstal. Untuk mempelajari lebih lanjut, lihat bundel ekstensi.

Versi ini memperkenalkan kemampuan untuk menyambungkan menggunakan identitas alih-alih rahasia. Untuk tutorial cara mengonfigurasi aplikasi fungsi Anda dengan identitas terkelola, lihat tutorial membuat aplikasi fungsi dengan koneksi berbasis identitas.

Anda dapat menambahkan versi ekstensi ini dari bundel ekstensi v3 dengan menambahkan atau mengganti kode berikut dalam file host.json:

{
    "version": "2.0",
    "extensionBundle": {
        "id": "Microsoft.Azure.Functions.ExtensionBundle",
        "version": "[3.3.0, 4.0.0)"
    }
}

Untuk mempelajari selengkapnya, lihat Perbarui ekstensi Anda.

Jenis pengikatan

Jenis pengikatan yang didukung untuk .NET bergantung pada versi ekstensi dan mode eksekusi C#, yang dapat menjadi salah satu hal berikut:

Pustaka kelas proses pekerja terisolasi yang dikompilasi fungsi C# berjalan dalam proses yang diisolasi dari runtime.

Pilih versi untuk melihat detail jenis pengikatan untuk mode dan versi.

Proses pekerja yang terisolasi mendukung jenis parameter sesuai dengan tabel di bawah ini. Dukungan untuk pengikatan ke jenis dari Azure.Messaging.EventHubs sedang dalam pratinjau.

Pemicu Azure Event Hubs

Saat Anda ingin fungsi memproses satu peristiwa, pemicu Azure Event Hubs dapat mengikat ke jenis berikut:

Tipe Deskripsi
string Peristiwa sebagai string. Gunakan saat peristiwa adalah teks sederhana.
byte[] Byte peristiwa.
Jenis yang bisa diserialisasikan JSON Saat peristiwa berisi data JSON, Functions mencoba mendeserialisasi data JSON ke dalam jenis objek CLR (POCO) yang sudah lama.
Azure.Messaging.EventHubs.EventData1 Objek peristiwa.
Jika Anda bermigrasi dari versi SDK Azure Event Hubs yang lebih lama, perhatikan bahwa versi ini menghilangkan dukungan untuk jenis warisan Bodyyang mendukung EventBody.

Saat Anda ingin fungsi memproses batch peristiwa, pemicu Azure Event Hubs dapat mengikat ke jenis berikut:

Tipe Deskripsi
string[] Array peristiwa dari batch, sebagai string. Setiap entri mewakili satu peristiwa.
EventData[]1 Array peristiwa dari batch, sebagai instans Azure.Messaging.EventHubs.EventData. Setiap entri mewakili satu peristiwa.
T[] di mana T adalah JSON tipeyang dapat diserialisasikan 1 Array peristiwa dari batch, sebagai instans jenis POCO kustom. Setiap entri mewakili satu peristiwa.

1 Untuk menggunakan jenis ini, Anda perlu mereferensikan Microsoft.Azure.Functions.Worker.Extensions.EventHubs 5.5.0 atau yang lebih baru dan dependensi umum untuk pengikatan jenis SDK.

Pengikatan output Azure Event Hubs

Saat Anda ingin fungsi menulis satu peristiwa, pengikatan output Azure Event Hubs dapat mengikat ke jenis berikut:

Tipe Deskripsi
string Peristiwa sebagai string. Gunakan saat peristiwa adalah teks sederhana.
byte[] Byte peristiwa.
Jenis yang bisa diserialisasikan JSON Objek yang mewakili peristiwa. Functions mencoba menserialisasikan jenis objek CLR (POCO) lama biasa ke dalam data JSON.

Saat Anda ingin fungsi menulis beberapa peristiwa, pengikatan output Azure Event Hubs dapat mengikat ke jenis berikut:

Tipe Deskripsi
T[] di mana T adalah salah satu jenis peristiwa tunggal Array yang berisi beberapa peristiwa. Setiap entri mewakili satu peristiwa.

Untuk skenario output lainnya, buat dan gunakan jenis dari Microsoft.Azure.EventHubs secara langsung.

Pengaturan host.json

File host.json berisi pengaturan yang mengontrol perilaku pemicu Pusat Aktivitas. Konfigurasinya berbeda bergantung pada versi ekstensi.

{
    "version": "2.0",
    "extensions": {
        "eventHubs": {
            "maxEventBatchSize" : 100,
            "minEventBatchSize" : 25,
            "maxWaitTime" : "00:05:00",            
            "batchCheckpointFrequency" : 1,
            "prefetchCount" : 300,
            "transportType" : "amqpWebSockets",
            "webProxy" : "https://proxyserver:8080",
            "customEndpointAddress" : "amqps://company.gateway.local",
            "targetUnprocessedEventThreshold" : 75,
            "initialOffsetOptions" : {
                "type" : "fromStart",
                "enqueuedTimeUtc" : ""
            },
            "clientRetryOptions":{
                "mode" : "exponential",
                "tryTimeout" : "00:01:00",
                "delay" : "00:00:00.80",
                "maximumDelay" : "00:01:00",
                "maximumRetries" : 3
            }
        }
    }
}
Properti Default Deskripsi
maxEventBatchSize2 100 Jumlah maksimum peristiwa yang disertakan dalam batch untuk satu pemanggilan. Harus minimal 1.
minEventBatchSize1 1 Jumlah minimum peristiwa yang diinginkan dalam batch. Minimum hanya berlaku ketika fungsi menerima beberapa peristiwa dan harus kurang dari maxEventBatchSize.
Ukuran minimum tidak dijamin secara ketat. Batch parsial dikirim ketika batch penuh tidak dapat disiapkan sebelum maxWaitTime telah berlalu. Batch parsial juga kemungkinan untuk pemanggilan fungsi pertama setelah penskalaan terjadi.
maxWaitTime1 00:01:00 Interval maksimum pemicu harus menunggu untuk mengisi batch sebelum memanggil fungsi. Waktu tunggu hanya dipertimbangkan ketika minEventBatchSize lebih besar dari 1 dan diabaikan. Jika kurang dari minEventBatchSize peristiwa tersedia sebelum waktu tunggu berlalu, fungsi dipanggil dengan batch parsial. Waktu tunggu terlama yang diizinkan adalah 10 menit.

CATATAN: Interval ini bukan jaminan yang ketat untuk waktu yang tepat di mana fungsi dipanggil. Ada magin kecil kesalahan karena presisi timer. Saat penskalaan terjadi, pemanggilan pertama dengan batch parsial dapat terjadi lebih cepat atau mungkin memakan waktu tunggu hingga dua kali lipat dari waktu tunggu yang dikonfigurasi.
batchCheckpointFrequency 1 Jumlah batch yang akan diproses sebelum membuat titik pemeriksaan untuk pusat aktivitas.
prefetchCount 300 Jumlah peristiwa yang diminta dengan bersemangat dari Azure Event Hubs dan diadakan di cache lokal untuk memungkinkan pembacaan agar tidak menunggu operasi jaringan
transportType amqpTcp Protokol dan transportasi yang digunakan untuk berkomunikasi dengan Pusat Aktivitas. Opsi yang tersedia: amqpTcp, amqpWebSockets
webProxy nihil Proksi yang digunakan untuk berkomunikasi dengan Pusat Aktivitas melalui soket web. Proksi tidak dapat digunakan dengan transportasi amqpTcp.
customEndpointAddress nihil Alamat yang digunakan saat membuat koneksi ke Azure Event Hubs, memungkinkan permintaan jaringan dirutekan melalui gateway aplikasi atau jalur lain yang diperlukan untuk lingkungan host. Namespace layanan yang sepenuhnya memenuhi syarat untuk pusat aktivitas masih diperlukan ketika alamat titik akhir kustom digunakan dan harus ditentukan secara eksplisit atau melalui string koneksi.
targetUnprocessedEventThreshold1 nihil Jumlah peristiwa yang tidak diolah yang diinginkan per instans fungsi. Ambang batas digunakan dalam penskalakan berbasis target untuk mengambil alih ambang penskalan default yang disimpulkan dari maxEventBatchSize opsi . Ketika diatur, jumlah peristiwa total yang tidak diproscesikan dibagi dengan nilai ini untuk menentukan jumlah instans fungsi yang diperlukan. Jumlah instans akan dibulatkan ke atas ke angka yang membuat distribusi partisi seimbang.
initialOffsetOptions/type fromStart Lokasi di aliran peristiwa untuk mulai memproses saat titik pemeriksaan tidak ada di penyimpanan. Berlaku untuk semua partisi. Untuk informasi selengkapnya, lihat Dokumentasi OffsetType. Opsi yang tersedia: fromStart, fromEnd, fromEnqueuedTime
initialOffsetOptions/enqueuedTimeUtc nihil Menentukan waktu pengantrean acara di aliran dari tempat mulai memproses. Kapan initialOffsetOptions/type dikonfigurasi sebagai fromEnqueuedTime, pengaturan ini wajib. Mendukung waktu dalam format apa pun yang didukung oleh DateTime.Parse(), seperti 2020-10-26T20:31Z. Untuk kejelasan, Anda juga harus menentukan zona waktu. Ketika zona waktu tidak ditentukan, Functions mengasumsikan zona waktu lokal mesin yang menjalankan aplikasi fungsi, yaitu UTC saat berjalan di Azure.
clientRetryOptions/mode eksponensial Pendekatan yang digunakan untuk menghitung penundaan coba ulang. Mode eksponensial mencoba kembali upaya dengan penundaan berdasarkan strategi back-off di mana setiap upaya akan meningkatkan durasi yang ditunggu sebelum mencoba kembali. Mode tetap mencoba kembali pada interval tetap dengan setiap penundaan memiliki durasi yang konsisten. Opsi yang tersedia: exponential, fixed
clientRetryOptions/tryTimeout 00:01:00 Durasi maksimum dalam menunggu operasi Pusat Aktivitas hingga selesai, per upaya.
clientRetryOptions/delay 00:00:00.80 Faktor penundaan atau back-off untuk diterapkan di antara upaya coba ulang.
clientRetryOptions/maximumDelay 00:00:01 Penundaan maksimum yang diizinkan antara upaya percobaan ulang.
clientRetryOptions/maximumRetries 3 Jumlah maksimum upaya coba ulang sebelum mempertimbangkan operasi terkait sebagai gagal.

1 Menggunakan minEventBatchSize dan maxWaitTime memerlukan v5.3.0 dari Microsoft.Azure.WebJobs.Extensions.EventHubs paket, atau versi yang lebih baru.

2 Default maxEventBatchSize berubah dalam v6.0.0 dari Microsoft.Azure.WebJobs.Extensions.EventHubs paket. Dalam versi sebelumnya, ini adalah 10.

clientRetryOptions digunakan untuk mencoba kembali operasi antara host Functions dan Event Hubs (seperti mengambil peristiwa dan mengirim peristiwa). Lihat panduan tentang penanganan kesalahan Azure Functions dan coba lagi untuk informasi tentang menerapkan kebijakan coba lagi ke fungsi individual.

Untuk referensi host.json di Azure Functions 2.x dan versi seterusnya, lihat referensi host.json untuk Azure Functions.

Langkah berikutnya