Bagikan melalui

Pemicu dan pengikatan Azure Event Hubs untuk Azure Functions

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.

Versi ini mendukung konfigurasi pemicu dan pengikatan melalui integrasi .NET Aspire.

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

Memasang bundel

Agar dapat menggunakan ekstensi pengikatan ini di aplikasi Anda, pastikan file host.json di akar proyek Anda berisi referensi ini extensionBundle :

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

Dalam contoh ini, version nilai [4.0.0, 5.0.0) menginstruksikan host Functions untuk menggunakan versi bundel yang setidaknya 4.0.0 tetapi kurang dari 5.0.0, yang mencakup semua versi potensial 4.x. Notasi ini secara efektif mempertahankan aplikasi Anda pada versi minor terbaru yang tersedia dari bundel ekstensi v4.x.

Jika memungkinkan, Anda harus menggunakan versi utama bundel ekstensi terbaru dan memungkinkan runtime untuk secara otomatis mempertahankan versi minor terbaru. Anda dapat melihat konten bundel terbaru pada halaman rilis bundel ekstensi. Untuk informasi selengkapnya, lihat Bundel ekstensi Azure Functions.

Jenis pengikatan

Jenis pengikatan yang didukung untuk .NET bergantung pada versi ekstensi dan mode eksekusi C#, yang dapat menjadi salah satu opsi 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:

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

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

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

Jenis 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 EventHubProducerClient dengan jenis lain dari Azure.Messaging.EventHubs secara langsung. Lihat Mendaftarkan klien Azure untuk contoh penggunaan injeksi dependensi untuk membuat jenis klien dari Azure SDK.

Jenis Pengikatan SDK

Jenis SDK untuk Azure EventHub ada di Pratinjau. Ikuti Pengikatan SDK Python untuk Sampel EventHub untuk mulai menggunakan Jenis SDK untuk Azure Event Hubs di Python.

Penting

Menggunakan pengikatan jenis SDK memerlukan model pemrograman Python v2.

Mengikat Jenis parameter Contoh-contoh
Pemicu EventHub EventData EventData

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 Bawaan 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 margin 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.

NOTA: Menetapkan nilai ini di atas 1 untuk paket hosting yang didukung oleh penskalaan berbasis target dapat menyebabkan perilaku penskalaan yang salah. Platform ini menghitung ukuran antrean yang belum diproses sebagai "posisi saat ini - posisi checkpoint", yang mungkin salah menunjukkan pesan yang belum diproses ketika batch telah diproses tetapi belum diperiksa, mencegah skala masuk yang tepat saat tidak ada pesan yang tersisa.
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 nol Proksi yang digunakan untuk berkomunikasi dengan Pusat Aktivitas melalui soket web. Proksi tidak dapat digunakan dengan transportasi amqpTcp.
customEndpointAddress nol 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 hub peristiwa masih diperlukan ketika alamat titik akhir kustom digunakan, dan harus ditentukan secara eksplisit atau melalui string koneksi.
targetUnprocessedEventThreshold1 nol 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 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 nol 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

  • Last updated on