Share via

Pemicu Azure IoT Hub untuk Azure Functions

  • Artikel

Kumpulan artikel ini menjelaskan cara bekerja dengan pengikatan Azure Functions untuk IoT Hub. Dukungan IoT Hub didasarkan pada Pengikatan Azure Event Hubs.

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

Penting

Sementara sampel kode berikut menggunakan Event Hub API, sintaks yang diberikan berlaku untuk fungsi IoT Hub.

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 cosmos_db_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 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.

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 terhadap konfigurasi lingkungan yang berisi nama pengaturan aplikasi yang berisi string koneksi. Anda bisa mendapatkan string koneksi ini dengan memilih tombol Informasi Koneksi untuk namespace layanan. String koneksi harus untuk namespace Pusat Aktivitas, bukan pusat aktivitas itu sendiri.

String koneksi ini harus memiliki setidaknya izin "baca" untuk mengaktifkan fungsi tersebut.

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

Catatan

Koneksi berbasis identitas tidak didukung oleh pemicu IoT Hub. Jika Anda perlu menggunakan identitas terkelola end-to-end, Anda dapat menggunakan Perutean IoT Hub untuk mengirim data ke pusat aktivitas yang Anda kontrol sebagai gantinya. Dengan begitu, perutean keluar dapat diautentikasi dengan identitas terkelola, peristiwa dapat dibaca dari pusat aktivitas tersebut menggunakan identitas terkelola.

properti host.json

File host.json berisi pengaturan yang mengontrol perilaku pemicu Event Hub, Hub Peristiwa. Lihat bagian pengaturan host.json untuk detail pengaturan yang tersedia.

Langkah berikutnya