Pemicu Azure Event Hubs untuk Azure Functions

  • Artikel
  • 11 menit untuk membaca

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

Untuk informasi tentang detail pengaturan dan konfigurasi, lihat gambaran umum.

Gunakan pemicu fungsi untuk merespons acara yang dikirim ke stream acara event hub. Anda harus memiliki akses baca ke event hub dasar untuk menyiapkan pemicu. Ketika fungsi dipicu, pesan yang diteruskan ke fungsi diketik sebagai string.

Contoh

Contoh berikut menunjukkan fungsi C# yang mencatat isi pesan pemicu Event Hubs.

[FunctionName("EventHubTriggerCSharp")]
public void Run([EventHubTrigger("samples-workitems", Connection = "EventHubConnectionAppSetting")] string myEventHubMessage, ILogger log)
{
    log.LogInformation($"C# function triggered to process a message: {myEventHubMessage}");
}

Untuk mendapatkan akses ke metadata peristiwa dalam kode fungsi, ikat ke objek EventData. Anda juga dapat mengakses properti yang sama dengan menggunakan ekspresi pengikatan dalam tanda tangan metode. Contoh berikut ini memperlihatkan kedua cara untuk mendapatkan data yang sama:

[FunctionName("EventHubTriggerCSharp")]
public void Run(
    [EventHubTrigger("samples-workitems", Connection = "EventHubConnectionAppSetting")] EventData myEventHubMessage,
    DateTime enqueuedTimeUtc,
    Int64 sequenceNumber,
    string offset,
    ILogger log)
{
    log.LogInformation($"Event: {Encoding.UTF8.GetString(myEventHubMessage.Body)}");
    // Metadata accessed by binding to EventData
    log.LogInformation($"EnqueuedTimeUtc={myEventHubMessage.SystemProperties.EnqueuedTimeUtc}");
    log.LogInformation($"SequenceNumber={myEventHubMessage.SystemProperties.SequenceNumber}");
    log.LogInformation($"Offset={myEventHubMessage.SystemProperties.Offset}");
    // Metadata accessed by using binding expressions in method parameters
    log.LogInformation($"EnqueuedTimeUtc={enqueuedTimeUtc}");
    log.LogInformation($"SequenceNumber={sequenceNumber}");
    log.LogInformation($"Offset={offset}");
}

Untuk menerima acara dalam batch, buat string atau EventData array.

Catatan

Saat menerima dalam batch Anda tidak dapat mengikat parameter metode seperti dalam contoh di atas dengan DateTime enqueuedTimeUtc dan harus menerimanya dari setiap objek EventData

[FunctionName("EventHubTriggerCSharp")]
public void Run([EventHubTrigger("samples-workitems", Connection = "EventHubConnectionAppSetting")] EventData[] eventHubMessages, ILogger log)
{
    foreach (var message in eventHubMessages)
    {
        log.LogInformation($"C# function triggered to process a message: {Encoding.UTF8.GetString(message.Body)}");
        log.LogInformation($"EnqueuedTimeUtc={message.SystemProperties.EnqueuedTimeUtc}");
    }
}

Contoh berikut menunjukkan pengikatan pemicu Event Hubs dalam file function.json dan fungsi JavaScript yang menggunakan pengikatan. Fungsi ini membaca metadata acara dan mencatat pesan.

Contoh berikut menunjukkan data pengikatan Azure Event Hubs dalam file function.json, yang berbeda untuk runtime Functions versi 1.x dibandingkan dengan versi yang lebih baru.

{
  "type": "eventHubTrigger",
  "name": "myEventHubMessage",
  "direction": "in",
  "eventHubName": "MyEventHub",
  "connection": "myEventHubReadConnectionAppSetting"
}

Berikut kode JavaScript:

module.exports = function (context, myEventHubMessage) {
    context.log('Function triggered to process a message: ', myEventHubMessage);
    context.log('EnqueuedTimeUtc =', context.bindingData.enqueuedTimeUtc);
    context.log('SequenceNumber =', context.bindingData.sequenceNumber);
    context.log('Offset =', context.bindingData.offset);

    context.done();
};

Untuk menerima acara dalam batch, atur cardinality ke many di file function.js, seperti yang diperlihatkan dalam contoh berikut.

{
  "type": "eventHubTrigger",
  "name": "eventHubMessages",
  "direction": "in",
  "eventHubName": "MyEventHub",
  "cardinality": "many",
  "connection": "myEventHubReadConnectionAppSetting"
}

Berikut kode JavaScript-nya:

module.exports = function (context, eventHubMessages) {
    context.log(`JavaScript eventhub trigger function called for message array ${eventHubMessages}`);

    eventHubMessages.forEach((message, index) => {
        context.log(`Processed message ${message}`);
        context.log(`EnqueuedTimeUtc = ${context.bindingData.enqueuedTimeUtcArray[index]}`);
        context.log(`SequenceNumber = ${context.bindingData.sequenceNumberArray[index]}`);
        context.log(`Offset = ${context.bindingData.offsetArray[index]}`);
    });

    context.done();
};

Contoh PowerShell lengkap tertunda.

Contoh berikut menunjukkan pengikatan pemicu Event Hubs dalam file function.json dan fungsi Python yang menggunakan pengikatan. Fungsi ini membaca metadata acara dan mencatat pesan.

Contoh berikut memperlihatkan data pengikatan Event Hub di file function.json.

{
  "type": "eventHubTrigger",
  "name": "event",
  "direction": "in",
  "eventHubName": "MyEventHub",
  "connection": "myEventHubReadConnectionAppSetting"
}

Berikut adalah kode Python:

import logging
import azure.functions as func


def main(event: func.EventHubEvent):
    logging.info(f'Function triggered to process a message: {event.get_body().decode()}')
    logging.info(f'  EnqueuedTimeUtc = {event.enqueued_time}')
    logging.info(f'  SequenceNumber = {event.sequence_number}')
    logging.info(f'  Offset = {event.offset}')

    # Metadata
    for key in event.metadata:
        logging.info(f'Metadata: {key} = {event.metadata[key]}')

Contoh berikut menunjukkan pemicu pengikatan Event Hubs yang mencatat isi pesan pemicu Event Hubs.

@FunctionName("ehprocessor")
public void eventHubProcessor(
  @EventHubTrigger(name = "msg",
                  eventHubName = "myeventhubname",
                  connection = "myconnvarname") String message,
       final ExecutionContext context )
       {
          context.getLogger().info(message);
 }

Di pustaka runtime fungsi Java, gunakan anotasi EventHubTrigger pada parameter yang nilainya akan berasal dari pusat aktivitas. Parameter dengan anotasi ini menyebabkan fungsi berjalan saat acara tiba. Anotasi ini dapat digunakan dengan jenis Java asli, POJO, atau nilai yang dapat diubah ke null menggunakan Optional<T>.

Atribut

Pustaka C# dalam proses dan proses terisolasi menggunakan atribut untuk mengonfigurasi pemicu. Skrip C# sebagai gantinya menggunakan file konfigurasi function.json.

Di pustaka kelas C#, gunakan EventHubTriggerAttribute, yang mendukung properti berikut.

Parameter Deskripsi
EventHubName Nama event hub. Ketika nama event hub juga ada dalam string koneksi, nilai tersebut menimpa properti ini di runtime. Dapat direferensikan dalam pengaturan aplikasi, seperti %eventHubName%
ConsumerGroup Properti opsional yang mengatur grup konsumen yang digunakan untuk berlangganan ke acara di hub. Jika dihilangkan, grup konsumen $Default digunakan.
Koneksi Nama pengaturan aplikasi atau kumpulan pengaturan yang menentukan cara menyambungkan ke Azure Event Hubs. Untuk mempelajari selengkapnya, lihat Koneksi.

Anotasi

Di pustaka runtime fungsi Java, gunakan anotasi EventHubTrigger, yang mendukung pengaturan berikut:

Konfigurasi

Tabel berikut menjelaskan properti konfigurasi pemicu yang Anda atur di file function.json, yang berbeda berdasarkan versi runtime.

Properti function.json Deskripsi
jenis Harus diatur ke eventHubTrigger. Properti ini diatur secara otomatis saat Anda membuat pemicu di portal Microsoft Azure.
petunjuk Harus diatur ke in. Properti ini diatur secara otomatis saat Anda membuat pemicu di portal Microsoft Azure.
nama Nama variabel yang mewakili blob dalam kode fungsi.
eventHubName Nama event hub. Ketika nama event hub juga ada dalam string koneksi, nilai tersebut menimpa properti ini di runtime. Dapat direferensikan melalui pengaturan aplikasi%eventHubName%
consumerGroup Properti opsional yang mengatur grup konsumen yang digunakan untuk berlangganan ke acara di hub. Jika dihilangkan, grup konsumen $Default digunakan.
kardinalitas Atur ke many untuk mengaktifkan pengelompokan. Jika dihilangkan atau diatur ke one, satu pesan diteruskan ke fungsi.
connection Nama pengaturan aplikasi atau kumpulan pengaturan yang menentukan cara menyambungkan ke Azure Event Hubs. Lihat Koneksi.

Saat Anda mengembangkan secara lokal, tambahkan pengaturan aplikasi Anda di file local.settings.json dalam koleksi Values.

Penggunaan

Untuk mempelajari selengkapnya cara pemicu Azure Event Hubs dan pemicu IoT Hub diskalakan, lihat pemicu Azure Event Hubs.

Jenis parameter yang didukung oleh pengikatan output Azure Event Hubs tergantung pada versi runtime Functions, versi paket ekstensi, dan modalitas C# yang digunakan.

Fungsi pustaka kelas C# dalam proses mendukung jenis berikut:

Versi EventData ini menghilangkan dukungan untuk jenis Body warisan demi EventBody.

Jenis parameter dapat berupa salah satu dari parameter berikut:

  • Setiap jenis Java asli seperti int, String, byte[].
  • Nilai yang dapat diubah ke null menggunakan Opsional.
  • Jenis POJO apa pun.

Untuk mempelajari selengkapnya, lihat referensi EventHubTrigger.

Metadata acara

Pemicu Event Hubs menyediakan beberapa properti metadata. Properti metadata ini dapat digunakan sebagai bagian dari ekspresi pengikatan dalam pengikatan lain atau sebagai parameter dalam kode Anda. Properti berasal dari kelas EventData.

Properti Jenis Deskripsi
PartitionContext PartitionContext Instans PartitionContext.
EnqueuedTimeUtc DateTime Waktu yang telah diantrekan dalam UTC.
Offset string Offset data yang relatif terhadap aliran partisi pusat aktivitas. Offset adalah penanda atau pengidentifikasi untuk acara dalam aliran Event Hubs. Pengidentifikasi unik dalam partisi aliran Event Hubs.
PartitionKey string Partisi tempat data acara harus dikirim.
Properties IDictionary<String,Object> Properti pengguna data acara.
SequenceNumber Int64 Nomor urutan logika acara.
SystemProperties IDictionary<String,Object> Properti sistem, termasuk data acara.

Lihat contoh kode yang menggunakan properti ini sebelumnya di artikel ini.

Koneksi

Properti connection adalah referensi ke konfigurasi lingkungan yang menentukan bagaimana aplikasi harus terhubung ke Pusat Aktivitas. Properti ini mungkin menentukan:

Jika nilai yang dikonfigurasi adalah kecocokan yang identik untuk pengaturan tunggal dan kecocokan awalan untuk pengaturan lain, kecocokan yang identik digunakan.

String koneksi

Dapatkan string koneksi ini dengan mengeklik tombol Informasi Koneksi untuk namespace, bukan pusat aktivitas itu sendiri. String koneksi harus untuk namespace Pusat Aktivitas, bukan pusat aktivitas itu sendiri.

Saat digunakan untuk pemicu, string koneksi harus memiliki setidaknya izin “baca” untuk mengaktifkan fungsi. Saat digunakan untuk binding output, string koneksi harus memiliki izin "kirim" untuk mengirim pesan ke aliran peristiwa.

String koneksi ini harus disimpan dalam pengaturan aplikasi dengan nama yang cocok dengan nilai yang ditentukan oleh properti connection konfigurasi pengikatan.

Koneksi berbasis identitas

Jika Anda menggunakan versi ekstensi 5.x atau yang lebih tinggi, alih-alih menggunakan string koneksi dengan rahasia, Anda dapat membuat aplikasi menggunakan identitas Azure Active Directory. Untuk melakukan ini, Anda harus menentukan pengaturan di bawah awalan umum yang memetakan ke properti connection dalam konfigurasi pemicu dan pengikatan.

Dalam mode ini, ekstensi tersebut memerlukan properti berikut:

Catatan

Variabel lingkungan yang disediakan saat ini harus diawali dengan AzureWebJobs agar berfungsi dalam paket Konsumsi. Dalam paket Premium, awalan ini tidak diperlukan.

Properti Template variabel lingkungan Deskripsi Contoh nilai
Namespace yang Sepenuhnya Memenuhi Syarat AzureWebJobs<CONNECTION_NAME_PREFIX>__fullyQualifiedNamespace Namespace Pusat Aktivitas sepenuhnya memenuhi syarat. <event_hubs_namespace>.servicebus.windows.net

Properti tambahan dapat diatur untuk menyesuaikan koneksi. Lihat Properti umum untuk koneksi berbasis identitas.

Catatan

Saat menggunakan Azure App Configuration atau Key Vault guna menyediakan pengaturan untuk koneksi Identitas Terkelola, nama pengaturan harus menggunakan pemisah kunci yang valid seperti : atau / sebagai ganti __ untuk memastikan nama diselesaikan dengan benar.

Contohnya:<CONNECTION_NAME_PREFIX>:fullyQualifiedNamespace

Saat dihosting di layanan Azure Functions, koneksi berbasis identitas menggunakan identitas terkelola. Identitas yang ditetapkan sistem digunakan secara default, meskipun identitas yang ditetapkan pengguna dapat ditentukan dengan credential dan clientID properti. Perhatikan bahwa mengonfigurasi identitas yang ditetapkan pengguna dengan ID sumber daya tidak didukung. Saat dijalankan dalam konteks lain, seperti pengembangan lokal, identitas pengembang Anda digunakan sebagai gantinya, meskipun ini dapat dikustomisasi. Lihat Pengembangan lokal dengan koneksi berbasis identitas.

Memberikan izin kepada identitas

Identitas apa pun yang digunakan harus memiliki izin untuk melakukan tindakan yang dimaksudkan. Anda harus menetapkan peran di Azure RBAC, menggunakan peran bawaan atau kustom yang memberikan izin tersebut.

Penting

Beberapa izin mungkin diekspos oleh layanan yang tidak diperlukan untuk semua konteks. Jika memungkinkan, patuhi prinsip hak istimewa paling sedikit, yang hanya memberikan hak istimewa yang diperlukan identitas. Misalnya, jika aplikasi hanya perlu dapat membaca dari sumber data, gunakan peran yang hanya memiliki izin untuk membaca. Tidak pantas untuk menetapkan peran yang juga memungkinkan menulis ke layanan itu, karena ini akan menjadi izin yang berlebihan untuk operasi baca. Demikian pula, Anda ingin memastikan penetapan peran hanya mencakup sumber daya yang perlu dibaca.

Anda akan perlu membuat penetapan peran yang menyediakan akses ke pusat aktivitas Anda saat runtime. Cakupan penetapan peran harus untuk namespace Azure Event Hubs, bukan pusat aktivitas itu sendiri. Peran manajemen seperti Pemilik tidak cukup. Tabel berikut menunjukkan peran bawaan yang direkomendasikan saat menggunakan ekstensi Azure Event Hubs dalam operasi normal. Aplikasi Anda mungkin memerlukan izin tambahan berdasarkan kode yang Anda tulis.

Jenis pengikatan Peran bawaan contoh
Pemicu Penerima Data Azure Event Hubs, Pemilik Data Azure Event Hubs
Pengikatan output Azure Service Bus Data Sender

Pengaturan host.json

File host.json berisi pengaturan yang mengontrol perilaku pemicu Event Hubs. Lihat bagian pengaturan host.json untuk detail mengenai pengaturan yang tersedia.

Langkah berikutnya