Pengikatan Azure Service Bus untuk Azure Functions

  • Artikel

Azure Functions terintegrasi dengan Azure Service Bus melalui pemicu dan pengikatan. Mengintegrasikan dengan Bus Layanan memungkinkan Anda untuk membangun fungsi yang bereaksi terhadap dan mengirim antrean atau pesan topik.

Perbuatan Jenis
Menjalankan fungsi saat antrean Bus Layanan atau pesan topik dibuat Pemicu
Mengirim pesan Azure Service Bus 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.

Tambahkan ekstensi ke proyek Anda yang menginstal paket NuGet ini.

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 memungkinkan Anda untuk mengikat ke jenis dari Azure.Messaging.ServiceBus.

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

Memasang bundel

Pengikatan Bus Layanan adalah bagian dari bundel ekstensi, yang ditentukan dalam file proyek host.json Anda. 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.

Pemicu Azure Service Bus

Saat Anda ingin fungsi memproses satu pesan, pemicu Bus Layanan dapat mengikat ke jenis berikut:

Tipe Deskripsi
string Pesan sebagai string. Gunakan saat pesan adalah teks sederhana.
byte[] Byte pesan.
Jenis yang bisa diserialisasikan JSON Saat peristiwa berisi data JSON, Functions mencoba mendeserialisasi data JSON ke dalam jenis objek CLR (POCO) yang sudah lama.
ServiceBusReceivedMessage1 Objek pesan.

Saat mengikat ke ServiceBusReceivedMessage, Anda dapat secara opsional juga menyertakan parameter jenis ServiceBusMessageActions1,2 untuk melakukan tindakan penyelesaian pesan.

Saat Anda ingin fungsi memproses batch pesan, pemicu Bus Layanan dapat mengikat ke jenis berikut:

Tipe Deskripsi
T[] di mana T adalah salah satu jenis pesan tunggal Array peristiwa dari batch. Setiap entri mewakili satu peristiwa.

Saat mengikat ke ServiceBusReceivedMessage[], Anda dapat secara opsional juga menyertakan parameter jenis ServiceBusMessageActions1,2 untuk melakukan tindakan penyelesaian pesan.

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

2 Saat menggunakan ServiceBusMessageActions, atur AutoCompleteMessages properti atribut pemicu ke false. Ini mencegah runtime mencoba menyelesaikan pesan setelah pemanggilan fungsi berhasil.

Bus Layanan pengikatan output

Saat Anda ingin fungsi menulis satu pesan, pengikatan output Bus Layanan dapat mengikat ke jenis berikut:

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

Saat Anda ingin fungsi menulis beberapa pesan, pengikatan output Bus Layanan dapat mengikat ke jenis berikut:

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

Untuk skenario output lainnya, buat dan gunakan jenis dari Azure.Messaging.ServiceBus secara langsung.

Pengaturan host.json

Bagian ini menjelaskan pengaturan konfigurasi yang tersedia untuk pengikatan ini, yang bergantung pada versi runtime dan ekstensi.

{
    "version": "2.0",
    "extensions": {
        "serviceBus": {
            "clientRetryOptions":{
                "mode": "exponential",
                "tryTimeout": "00:01:00",
                "delay": "00:00:00.80",
                "maxDelay": "00:01:00",
                "maxRetries": 3
            },
            "prefetchCount": 0,
            "transportType": "amqpWebSockets",
            "webProxy": "https://proxyserver:8080",
            "autoCompleteMessages": true,
            "maxAutoLockRenewalDuration": "00:05:00",
            "maxConcurrentCalls": 16,
            "maxConcurrentSessions": 8,
            "maxMessageBatchSize": 1000,
            "minMessageBatchSize": 1,
            "maxBatchWaitTime": "00:00:30",
            "sessionIdleTimeout": "00:01:00",
            "enableCrossEntityTransactions": false
        }
    }
}

Pengaturan clientRetryOptions hanya berlaku untuk interaksi dengan layanan Bus Layanan. Ini tidak memengaruhi percobaan ulang eksekusi fungsi. Untuk informasi selengkapnya, lihat Coba lagi.

Properti Default Deskripsi
mode Exponential Pendekatan yang digunakan untuk menghitung penundaan coba ulang. Mode eksponensial default akan mencoba kembali upaya dengan penundaan berdasarkan strategi back-off di mana setiap upaya akan meningkatkan durasi tunggu sebelum mencoba ulang. Mode Fixed akan mencoba ulang upaya pada interval tetap dengan setiap penundaan memiliki durasi yang konsisten.
tryTimeout 00:01:00 Durasi maksimum untuk menunggu operasi per upaya.
penundaan 00:00:00.80 Faktor penundaan atau back-off untuk diterapkan di antara upaya coba ulang.
maxDelay 00:01:00 Penundaan maksimum antara upaya percobaan ulang
maxRetries 3 Jumlah maksimum upaya coba ulang sebelum mempertimbangkan operasi terkait sebagai gagal.
prefetchCount 0 Mendapat atau mengatur jumlah pesan yang dapat diminta oleh penerima pesan secara bersamaan.
transportType amqpTcp Protokol dan transportasi yang digunakan untuk berkomunikasi dengan Bus Layanan. Opsi yang tersedia: amqpTcp, amqpWebSockets
webProxy n/a Proksi yang digunakan untuk berkomunikasi dengan Bus Layanan melalui soket web. Proksi tidak dapat digunakan dengan transportasi amqpTcp.
autoCompleteMessages true Menentukan apakah akan menyelesaikan pesan secara otomatis atau tidak setelah eksekusi fungsi berhasil.
maxAutoLockRenewalDuration 00:05:00 Durasi maksimum di mana kunci pesan akan diperbarui secara otomatis. Pengaturan ini hanya berlaku untuk fungsi yang menerima satu pesan pada satu waktu.
maxConcurrentCalls 16 Jumlah maksimum panggilan serentak ke panggilan balik yang harus diinisiasi per instans yang diskalakan. Secara default, runtime Functions memproses beberapa pesan secara bersamaan. Pengaturan ini hanya digunakan ketika isSessionsEnabled properti atau atribut pada pemicu diatur ke false. Pengaturan ini hanya berlaku untuk fungsi yang menerima satu pesan pada satu waktu.
maxConcurrentSessions 8 Jumlah maksimum sesi yang dapat ditangani secara bersamaan per instans berskala. Pengaturan ini hanya digunakan ketika isSessionsEnabled properti atau atribut pada pemicu diatur ke true. Pengaturan ini hanya berlaku untuk fungsi yang menerima satu pesan pada satu waktu.
maxMessageBatchSize 1000 Jumlah maksimum pesan yang akan diteruskan ke setiap panggilan fungsi. Pengaturam ini hanya berlaku untuk fungsi yang menerima batch pesan.
minMessageBatchSize1 1 Jumlah minimum pesan yang diinginkan dalam batch. Minimum hanya berlaku ketika fungsi menerima beberapa pesan dan harus kurang dari maxMessageBatchSize.
Ukuran minimum tidak dijamin secara ketat. Batch parsial dikirim ketika batch penuh tidak dapat disiapkan sebelum maxBatchWaitTime telah berlalu.
maxBatchWaitTime1 00:00:30 Interval maksimum pemicu harus menunggu untuk mengisi batch sebelum memanggil fungsi. Waktu tunggu hanya dipertimbangkan ketika minMessageBatchSize lebih besar dari 1 dan diabaikan sebaliknya. Jika kurang dari minMessageBatchSize pesan yang tersedia sebelum waktu tunggu berlalu, fungsi dipanggil dengan batch parsial. Waktu tunggu terlama yang diizinkan adalah 50% dari durasi kunci pesan entitas, yang berarti maksimum yang diizinkan adalah 2 menit dan 30 detik. Jika tidak, Anda mungkin mendapatkan pengecualian kunci.

CATATAN: Interval ini bukan jaminan yang ketat untuk waktu yang tepat di mana fungsi dipanggil. Ada margin kecil kesalahan karena presisi timer.
sessionIdleTimeout n/a Jumlah maksimum waktu untuk menunggu pesan diterima untuk sesi yang saat ini aktif. Setelah waktu ini berlalu, sesi akan ditutup dan fungsi akan mencoba memproses sesi lain.
enableCrossEntityTransactions false Apakah akan mengaktifkan transaksi yang mencakup beberapa entitas pada namespace Bus Layanan atau tidak.

1 Menggunakan minMessageBatchSize dan maxBatchWaitTime memerlukan paket v5.10.0Microsoft.Azure.WebJobs.Extensions.ServiceBus, atau versi yang lebih baru.

Langkah berikutnya