Bagikan melalui

Pemicu Azure Event Hubs untuk Azure Functions

  • Artikel

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 pengaturan dan detail 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.

Keputusan penskalaan Azure Event Hubs untuk paket Konsumsi dan Premium dilakukan melalui Penskalaan Berbasis Target. Untuk informasi selengkapnya, lihat Penskalaan Berbasis Target.

Untuk informasi tentang cara Azure Functions merespons peristiwa yang dikirim ke aliran peristiwa pusat aktivitas menggunakan pemicu, lihat Mengintegrasikan Azure Event Hubs dengan fungsi tanpa server di Azure.

Penting

Artikel ini menggunakan tab untuk mendukung beberapa versi model pemrograman Node.js. Model v4 umumnya tersedia dan dirancang untuk memiliki pengalaman yang lebih fleksibel dan intuitif untuk pengembang JavaScript dan TypeScript. Untuk detail selengkapnya tentang cara kerja model v4, lihat panduan pengembang Node.js Azure Functions. Untuk mempelajari selengkapnya tentang perbedaan antara v3 dan v4, lihat panduan migrasi.

Azure Functions mendukung dua model pemrograman untuk Python. Cara Anda menentukan pengikatan tergantung pada model pemrograman yang Anda pilih.

Model pemrograman Python v2 memungkinkan Anda menentukan pengikatan menggunakan dekorator langsung dalam kode fungsi Python Anda. Untuk informasi selengkapnya, lihat panduan pengembang Python.

Artikel ini mendukung kedua model pemrograman.

Contoh

Contoh berikut menunjukkan fungsi C# yang dipicu berdasarkan pusat aktivitas, tempat string pesan input ditulis ke log:

{
    private readonly ILogger<EventHubsFunction> _logger;

    public EventHubsFunction(ILogger<EventHubsFunction> logger)
    {
        _logger = logger;
    }

    [Function(nameof(EventHubFunction))]
    [FixedDelayRetry(5, "00:00:10")]
    [EventHubOutput("dest", Connection = "EventHubConnection")]
    public string EventHubFunction(
        [EventHubTrigger("src", Connection = "EventHubConnection")] string[] input,
        FunctionContext context)
    {
        _logger.LogInformation("First Event Hubs triggered message: {msg}", input[0]);

        var message = $"Output message created at {DateTime.Now}";
        return message;
    }

Contoh berikut menunjukkan fungsi TypeScript pemicu Azure Event Hubs. Fungsi ini membaca metadata acara dan mencatat pesan.

import { app, InvocationContext } from '@azure/functions';

export async function eventHubTrigger1(message: unknown, context: InvocationContext): Promise<void> {
    context.log('Event hub function processed message:', message);
    context.log('EnqueuedTimeUtc =', context.triggerMetadata.enqueuedTimeUtc);
    context.log('SequenceNumber =', context.triggerMetadata.sequenceNumber);
    context.log('Offset =', context.triggerMetadata.offset);
}

app.eventHub('eventHubTrigger1', {
    connection: 'myEventHubReadConnectionAppSetting',
    eventHubName: 'MyEventHub',
    cardinality: 'one',
    handler: eventHubTrigger1,
});

Untuk menerima peristiwa dalam batch, atur cardinality ke many, seperti yang ditunjukkan dalam contoh berikut.

import { app, InvocationContext } from '@azure/functions';

export async function eventHubTrigger1(messages: unknown[], context: InvocationContext): Promise<void> {
    context.log(`Event hub function processed ${messages.length} messages`);
    for (let i = 0; i < messages.length; i++) {
        context.log('Event hub message:', messages[i]);
        context.log(`EnqueuedTimeUtc = ${context.triggerMetadata.enqueuedTimeUtcArray[i]}`);
        context.log(`SequenceNumber = ${context.triggerMetadata.sequenceNumberArray[i]}`);
        context.log(`Offset = ${context.triggerMetadata.offsetArray[i]}`);
    }
}

app.eventHub('eventHubTrigger1', {
    connection: 'myEventHubReadConnectionAppSetting',
    eventHubName: 'MyEventHub',
    cardinality: 'many',
    handler: eventHubTrigger1,
});

Contoh berikut menunjukkan fungsi JavaScript pemicu Azure Event Hubs. Fungsi ini membaca metadata acara dan mencatat pesan.

const { app } = require('@azure/functions');

app.eventHub('eventHubTrigger1', {
    connection: 'myEventHubReadConnectionAppSetting',
    eventHubName: 'MyEventHub',
    cardinality: 'one',
    handler: (message, context) => {
        context.log('Event hub function processed message:', message);
        context.log('EnqueuedTimeUtc =', context.triggerMetadata.enqueuedTimeUtc);
        context.log('SequenceNumber =', context.triggerMetadata.sequenceNumber);
        context.log('Offset =', context.triggerMetadata.offset);
    },
});

Untuk menerima peristiwa dalam batch, atur cardinality ke many, seperti yang ditunjukkan dalam contoh berikut.

const { app } = require('@azure/functions');

app.eventHub('eventHubTrigger1', {
    connection: 'myEventHubReadConnectionAppSetting',
    eventHubName: 'MyEventHub',
    cardinality: 'many',
    handler: (messages, context) => {
        context.log(`Event hub function processed ${messages.length} messages`);
        for (let i = 0; i < messages.length; i++) {
            context.log('Event hub message:', messages[i]);
            context.log(`EnqueuedTimeUtc = ${context.triggerMetadata.enqueuedTimeUtcArray[i]}`);
            context.log(`SequenceNumber = ${context.triggerMetadata.sequenceNumberArray[i]}`);
            context.log(`Offset = ${context.triggerMetadata.offsetArray[i]}`);
        }
    },
});

Berikut adalah kode PowerShell:

param($eventHubMessages, $TriggerMetadata)

Write-Host "PowerShell eventhub trigger function called for message array: $eventHubMessages"

$eventHubMessages | ForEach-Object { Write-Host "Processed message: $_" }

Contoh berikut menunjukkan pengikatan pemicu Azure Event Hubs dan fungsi Python yang menggunakan pengikatan. Fungsi ini membaca metadata acara dan mencatat pesan. Contohnya tergantung pada apakah Anda menggunakan model pemrograman Python v1 atau v2.

import logging
import azure.functions as func

app = func.FunctionApp()

@app.function_name(name="EventHubTrigger1")
@app.event_hub_message_trigger(arg_name="myhub", 
                               event_hub_name="<EVENT_HUB_NAME>",
                               connection="<CONNECTION_SETTING>") 
def test_function(myhub: func.EventHubEvent):
    logging.info('Python EventHub trigger processed an event: %s',
                myhub.get_body().decode('utf-8'))

Contoh berikut menunjukkan pengikatan pemicu Azure Event Hubs yang mencatat isi pesan pemicu Azure 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 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>.

Contoh berikut mengilustrasikan penggunaan SystemProperties dan opsi Pengikatan lainnya secara ekstensif untuk introspeksi Peristiwa lebih lanjut bersama dengan menyediakan jalur yang terbentuk BlobOutput dengan baik yaitu hierarkis Tanggal.

package com.example;
import java.util.Map;
import java.time.ZonedDateTime;

import com.microsoft.azure.functions.annotation.*;
import com.microsoft.azure.functions.*;

/**
 * Azure Functions with Event Hub trigger.
 * and Blob Output using date in path along with message partition ID
 * and message sequence number from EventHub Trigger Properties
 */
public class EventHubReceiver {

    @FunctionName("EventHubReceiver")
    @StorageAccount("bloboutput")

    public void run(
            @EventHubTrigger(name = "message",
                eventHubName = "%eventhub%",
                consumerGroup = "%consumergroup%",
                connection = "eventhubconnection",
                cardinality = Cardinality.ONE)
            String message,

            final ExecutionContext context,

            @BindingName("Properties") Map<String, Object> properties,
            @BindingName("SystemProperties") Map<String, Object> systemProperties,
            @BindingName("PartitionContext") Map<String, Object> partitionContext,
            @BindingName("EnqueuedTimeUtc") Object enqueuedTimeUtc,

            @BlobOutput(
                name = "outputItem",
                path = "iotevents/{datetime:yy}/{datetime:MM}/{datetime:dd}/{datetime:HH}/" +
                       "{datetime:mm}/{PartitionContext.PartitionId}/{SystemProperties.SequenceNumber}.json")
            OutputBinding<String> outputItem) {

        var et = ZonedDateTime.parse(enqueuedTimeUtc + "Z"); // needed as the UTC time presented does not have a TZ
                                                             // indicator
        context.getLogger().info("Event hub message received: " + message + ", properties: " + properties);
        context.getLogger().info("Properties: " + properties);
        context.getLogger().info("System Properties: " + systemProperties);
        context.getLogger().info("partitionContext: " + partitionContext);
        context.getLogger().info("EnqueuedTimeUtc: " + et);

        outputItem.setValue(message);
    }
}

Atribut

Pustaka C# proses dalam proses dan terisolasi menggunakan atribut untuk mengonfigurasi pemicu. Skrip C# sebagai gantinya menggunakan file konfigurasi function.json seperti yang dijelaskan dalam panduan pembuatan skrip C#.

Gunakan EventHubTriggerAttribute untuk menentukan pemicu pada pusat aktivitas, 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.

Dekorator

Hanya berlaku untuk model pemrograman Python v2.

Untuk fungsi Python v2 yang ditentukan menggunakan dekorator, properti berikut pada event_hub_message_trigger:

Properti Deskripsi
arg_name Nama variabel yang mewakili blob dalam kode fungsi.
event_hub_name Nama event hub. Ketika nama event hub juga ada dalam string koneksi, nilai tersebut menimpa properti ini di runtime.
connection Nama pengaturan aplikasi atau kumpulan pengaturan yang menentukan cara menyambungkan ke Azure Event Hubs. Lihat Koneksi.

Untuk fungsi Python yang ditentukan dengan menggunakan function.json, lihat bagian Konfigurasi .

Anotasi

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

Konfigurasi

Hanya berlaku untuk model pemrograman Python v1.

Tabel berikut menjelaskan properti yang bisa Anda atur pada objek yang options diteruskan ke app.eventHub() metode .

Properti Deskripsi
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.
koneksi Nama pengaturan aplikasi atau kumpulan pengaturan yang menentukan cara menyambungkan ke Azure Event Hubs. Lihat Koneksi.

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.
arah 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.
koneksi Nama pengaturan aplikasi atau kumpulan pengaturan yang menentukan cara menyambungkan ke Azure Event Hubs. Lihat Koneksi.

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

Penggunaan

Untuk mempelajari selengkapnya tentang bagaimana pemicu Azure Event Hubs dan skala pemicu IoT Hub, lihat Mengonsumsi Peristiwa dengan Azure Functions.

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

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 Body yang 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.

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 Tipe Deskripsi
PartitionContext PartitionContext Instans PartitionContext.
EnqueuedTimeUtc DateTime Waktu yang telah ditentukan 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. Ini mungkin menentukan:

Jika nilai yang dikonfigurasi adalah kecocokan persis untuk pengaturan tunggal dan kecocokan awalan untuk pengaturan lainnya, kecocokan persis akan 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 ekstensi versi 5.x atau yang lebih tinggi, alih-alih menggunakan string koneksi dengan rahasia, Anda dapat meminta aplikasi menggunakan identitas Microsoft Entra. 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:

Properti Templat variabel lingkungan Deskripsi Contoh nilai
Namespace yang Sepenuhnya Memenuhi Syarat <CONNECTION_NAME_PREFIX>__fullyQualifiedNamespace Namespace Pusat Aktivitas sepenuhnya memenuhi syarat. myeventhubns.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 oleh 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. Untuk sebagian besar layanan Azure, ini berarti Anda perlu menetapkan peran di Azure RBAC, menggunakan peran bawaan atau kustom yang menyediakan izin tersebut.

Penting

Beberapa izin mungkin diekspos oleh layanan target yang tidak diperlukan untuk semua konteks. Jika memungkinkan, patuhi prinsip hak istimewa paling rendah, dengan memberikan identitas hanya hak istimewa yang diperlukan. 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 dapat untuk namespace Layanan Pusat Aktivitas, atau 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 pengaturan yang tersedia.

Langkah berikutnya