Freigeben über

Azure IoT Hub-Trigger für Azure Functions

  • Artikel

Dieser Artikel erläutert das Arbeiten mit Azure Functions-Bindungen für IoT Hub. Die IoT Hub-Unterstützung basiert auf der Azure Event Hubs-Bindung.

Informationen zu Setup- und Konfigurationsdetails finden Sie in der Übersicht.

Wichtig

Die folgenden Codebeispiele verwenden zwar die Event Hub-API, aber die Syntax gilt auch für IoT Hub-Funktionen.

Der Funktionstrigger kann verwendet werden, um auf ein Ereignis zu reagieren, das an einen Event Hub-Datenstrom gesendet wird. Sie benötigen Lesezugriff auf den zugrunde liegenden Event Hub, um den Trigger einzurichten. Beim Auslösen der Funktion wird die an die Funktion übergebene Nachricht als Zeichenfolge eingegeben.

Skalierungsentscheidungen von Event Hubs für Verbrauchs- und Premium-Pläne werden über zielbasierte Skalierung getroffen. Weitere Informationen finden Sie unter Zielbasierte Skalierung.

Informationen dazu, wie Azure Functions auf Ereignisse reagiert, die mithilfe von Triggern an einen Event Hub-Ereignisdatenstrom gesendet werden, finden Sie unter Integrieren von Event Hubs mit serverlosen Funktionen in Azure.

Wichtig

In diesem Artikel werden Registerkarten verwendet, um mehrere Versionen des Node.js-Programmiermodells zu unterstützen. Das v4-Modell ist allgemein verfügbar und bietet JavaScript- und TypeScript-Entwicklern eine flexiblere und intuitivere Erfahrung. Weitere Informationen zur Funktionsweise des v4-Modells finden Sie im Azure Functions Node.js-Entwicklerhandbuch. Weitere Informationen zu den Unterschieden zwischen v3 und v4 finden Sie im Migrationshandbuch.

Azure Functions unterstützt zwei Programmiermodelle für Python. Wie Sie Ihre Bindung definieren, hängt vom gewählten Python-Programmiermodell ab.

Mit dem Python v2-Programmiermodell können Sie Bindungen mithilfe von Decorators direkt im Python-Funktionscode definieren. Weitere Informationen finden Sie im Python Developer-Leitfaden.

In diesem Artikel werden beide Programmiermodelle unterstützt.

Beispiel

Das folgende Beispiel zeigt eine C#-Funktion, die basierend auf einem Event Hub ausgelöst wird. Dabei wird die Eingabenachrichtenzeichenfolge in die Protokolle geschrieben:

{
    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;
    }

Das folgende Beispiel zeigt eine TypeScript-Funktion für den Event Hubs-Trigger. Die Funktion liest Ereignismetadaten und protokolliert die Meldung.

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,
});

Legen Sie zum Empfangen von Ereignissen in einem Batch cardinality auf many fest, wie im folgenden Beispiel gezeigt.

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,
});

Das folgende Beispiel zeigt eine JavaScript-Funktion für den Event Hubs-Trigger. Die Funktion liest Ereignismetadaten und protokolliert die Meldung.

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);
    },
});

Legen Sie zum Empfangen von Ereignissen in einem Batch cardinality auf many fest, wie im folgenden Beispiel gezeigt.

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]}`);
        }
    },
});

Dies ist der PowerShell-Code:

param($eventHubMessages, $TriggerMetadata)

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

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

Das folgende Beispiel zeigt eine Event Hubs-Triggerbindung sowie eine Python-Funktion, die die Bindung verwendet. Die Funktion liest Ereignismetadaten und protokolliert die Meldung. Das Beispiel hängt davon ab, ob Sie das Python-Programmiermodell v1 oder v2 verwenden.

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'))

Das folgende Beispiel zeigt eine Event Hubs-Triggerbindung, die den Nachrichtentext des Event Hubs-Triggers protokolliert.

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

Verwenden Sie die EventHubTrigger-Anmerkung in der Laufzeitbibliothek für Java-Funktionen für Parameter, deren Wert aus dem Event Hub stammt. Parameter mit diesen Anmerkungen führen dazu, dass die Funktion ausgeführt wird, wenn ein Ereignis empfangen wird. Diese Anmerkung kann mit nativen Java-Typen, POJOs oder Werten mit Optional<T>, die NULL-Werte annehmen können, verwendet werden.

Das folgende Beispiel veranschaulicht die umfassende Verwendung von SystemProperties und anderen Bindungsoptionen für die weitere Introspektion des Ereignisses sowie die Bereitstellung eines ordnungsgemäß formatierten BlobOutput-Pfads mit Datumshierarchie.

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);
    }
}

Attributes

Sowohl von C#-Bibliotheken vom Typ In-Process als auch von C#-Bibliotheken vom Typ isolierter Workerprozess wird ein Attribut verwendet, um den Trigger zu definieren. Das C#-Skript verwendet stattdessen eine Konfigurationsdatei function.json, wie im C#-Skript-Handbuch beschrieben.

Verwenden Sie EventHubTriggerAttribute, um einen Trigger für einen Event Hub zu definieren. Dabei werden die folgenden Eigenschaften unterstützt:

Parameter BESCHREIBUNG
EventHubName Der Name des Event Hubs. Wenn der Event Hub-Name auch in der Verbindungszeichenfolge enthalten ist, setzt dieser Wert diese Eigenschaft zur Laufzeit außer Kraft. Sie können App-Einstellungen verwenden, um darauf zu verweisen (Beispiel: %eventHubName%).
ConsumerGroup Eine optionale Eigenschaft, die zum Festlegen der Consumergruppe verwendet wird, mit der Ereignisse im Hub abonniert werden. Wird sie nicht angegeben, wird die Consumergruppe $Default verwendet.
Connection Der Name einer App-Einstellung oder -Einstellungssammlung, die angibt, wie eine Verbindung mit Event Hubs hergestellt wird. Weitere Informationen finden Sie unter Verbindungen.

Decorator-Elemente

Gilt nur für das Python v2-Programmiermodell.

Für Python v2-Funktionen, die mithilfe eines Decorators definiert wurden, gelten die folgenden Eigenschaften für event_hub_message_trigger:

Eigenschaft BESCHREIBUNG
arg_name Der Name der Variablen, die das Ereigniselement im Funktionscode darstellt.
event_hub_name Der Name des Event Hubs. Wenn der Event Hub-Name auch in der Verbindungszeichenfolge enthalten ist, setzt dieser Wert diese Eigenschaft zur Laufzeit außer Kraft.
connection Der Name einer App-Einstellung oder -Einstellungssammlung, die angibt, wie eine Verbindung mit Event Hubs hergestellt wird. Siehe Verbindungen.

Informationen zu Python-Funktionen, die mithilfe von function.json definiert wurden, finden Sie im Abschnitt Konfiguration.

Anmerkungen

Verwenden Sie in der Runtimebibliothek für Java-Funktionen die Anmerkung EventHubTrigger. Diese unterstützt die folgenden Einstellungen:

Konfiguration

Gilt nur für das Python v1-Programmiermodell.

In der folgenden Tabelle werden die Eigenschaften erläutert, die Sie für das options-Objekt festlegen können, das an die app.eventHub()-Methode übergeben wurde.

Eigenschaft Beschreibung
eventHubName Der Name des Event Hubs. Wenn der Event Hub-Name auch in der Verbindungszeichenfolge enthalten ist, setzt dieser Wert diese Eigenschaft zur Laufzeit außer Kraft. Darauf kann über App-Einstellungen %eventHubName% verwiesen werden.
consumerGroup Eine optionale Eigenschaft, die zum Festlegen der Consumergruppe verwendet wird, mit der Ereignisse im Hub abonniert werden. Wird sie nicht angegeben, wird die Consumergruppe $Default verwendet.
cardinality Legen Sie hierfür many fest, um Batchverarbeitung zu aktivieren. Wenn diese Eigenschaft nicht angegeben oder auf one festgelegt ist, wird eine einzelne Nachricht an die Funktion übergeben.
connection Der Name einer App-Einstellung oder -Einstellungssammlung, die angibt, wie eine Verbindung mit Event Hubs hergestellt wird. Siehe Verbindungen.

Die folgende Tabelle gibt Aufschluss über die Triggerkonfigurationseigenschaften, die Sie in der Datei function.json festlegen (unterscheidet sich je nach Runtimeversion).

Eigenschaft von „function.json“ BESCHREIBUNG
type Muss auf eventHubTrigger festgelegt sein. Diese Eigenschaft wird automatisch festgelegt, wenn Sie den Trigger im Azure Portal erstellen.
direction Muss auf in festgelegt sein. Diese Eigenschaft wird automatisch festgelegt, wenn Sie den Trigger im Azure Portal erstellen.
name Der Name der Variablen, die das Ereigniselement im Funktionscode darstellt.
eventHubName Der Name des Event Hubs. Wenn der Event Hub-Name auch in der Verbindungszeichenfolge enthalten ist, setzt dieser Wert diese Eigenschaft zur Laufzeit außer Kraft. Darauf kann über App-Einstellungen %eventHubName% verwiesen werden.
consumerGroup Eine optionale Eigenschaft, die zum Festlegen der Consumergruppe verwendet wird, mit der Ereignisse im Hub abonniert werden. Wird sie nicht angegeben, wird die Consumergruppe $Default verwendet.
cardinality Legen Sie hierfür many fest, um Batchverarbeitung zu aktivieren. Wenn diese Eigenschaft nicht angegeben oder auf one festgelegt ist, wird eine einzelne Nachricht an die Funktion übergeben.
connection Der Name einer App-Einstellung oder -Einstellungssammlung, die angibt, wie eine Verbindung mit Event Hubs hergestellt wird. Siehe Verbindungen.

Wenn Sie die Entwicklung lokal ausführen, fügen Sie Ihre Anwendungseinstellungen in der Datei local.settings.json in der Values-Sammlung hinzu.

Verwendung

Weitere Informationen zum Auslösen von Event Hubs und IoT Hub Triggerskalen finden Sie unter Nutzen von Ereignissen mit Azure Functions.

Der von der Event Hubs-Ausgabebindung unterstützte Parametertyp hängt von der Version der Functions-Runtime, von der Version des Erweiterungspakets sowie von der verwendeten C#-Modalität ab.

Wenn die Funktion ein einzelnes Ereignis verarbeiten soll, kann der Event Hubs-Trigger an die folgenden Typen gebunden werden:

type BESCHREIBUNG
string Das Ereignis als Zeichenfolge. Verwenden Sie diesen Parameter, wenn es sich bei dem Ereignis um einfachen Text handelt.
byte[] Die Bytes der Ereignisnachricht.
Serialisierbare JSON-Typen Wenn ein Ereignis JSON-Daten enthält, versucht Azure Functions, die JSON-Daten in einen POCO-Objekttyp (plain-old CLR Object) zu deserialisieren.
Azure.Messaging.EventHubs.EventData1 Das Ereignisobjekt.
Wenn Sie aus älteren Versionen der Event Hubs SDKs migrieren, beachten Sie, dass diese Version Unterstützung für den Legacytyp Body zugunsten von EventBody einstellt.

Wenn die Funktion einen Ereignisbatch verarbeiten soll, kann der Event Hubs-Trigger an die folgenden Typen gebunden werden:

type BESCHREIBUNG
string[] Ein Array von Ereignissen aus dem Batch als Zeichenfolgen. Jeder Eintrag stellt ein Ereignis dar.
EventData[] 1 Ein Array von Ereignissen aus dem Batch als Instanzen von Azure.Messaging.EventHubs.EventData. Jeder Eintrag stellt ein Ereignis dar.
T[], wobei T ein serialisierbarer JSON-Typ ist1. Ein Array von Ereignissen aus dem Batch als Instanzen eines benutzerdefinierten POCO-Typs. Jeder Eintrag stellt ein Ereignis dar.

1 Um diese Typen zu verwenden, müssen Sie auf Microsoft.Azure.Functions.Worker.Extensions.EventHubs 5.5.0 oder höher und die gemeinsamen Abhängigkeiten für SDK-Typbindungen verweisen.

Beim Parametertyp kann es sich um eine der folgenden Optionen handeln:

  • Beliebiger nativer Java-Typ wie „int“, „String“ oder „byte[]“
  • Nullable-Werte unter Verwendung von „Optional“
  • Beliebiger POJO-Typ

Weitere Informationen finden Sie in der Referenz zu EventHubTrigger.

Ereignismetadaten

Der Event Hubs-Trigger stellt mehrere Metadateneigenschaften bereit. Metadateneigenschaften können als Teil der Bindungsausdrücke in anderen Bindungen oder als Parameter im Code verwendet werden. Die Eigenschaften stammen aus der EventData-Klasse.

Eigenschaft Typ BESCHREIBUNG
PartitionContext PartitionContext Die PartitionContext-Instanz.
EnqueuedTimeUtc DateTime Die in die Warteschlange eingereihte Uhrzeit in UTC.
Offset string Der Offset der Daten relativ zum Event Hub-Partitionsdatenstrom. Der Offset ist ein Marker oder ein Bezeichner für ein Ereignis innerhalb des Event Hubs-Datenstroms. Der Bezeichner ist innerhalb einer Partition des Event Hubs-Datenstroms eindeutig.
PartitionKey string Die Partition, an die Ereignisdaten gesendet werden sollen.
Properties IDictionary<String,Object> Die Benutzereigenschaften der Ereignisdaten.
SequenceNumber Int64 Die Protokollfolgenummer des Ereignisses.
SystemProperties IDictionary<String,Object> Die Systemeigenschaften, einschließlich der Ereignisdaten.

Codebeispiele mit diesen Eigenschaften finden Sie weiter oben in diesem Artikel.

Verbindungen

Die connection-Eigenschaft ist ein Verweis auf eine Umgebungskonfiguration, die den Namen einer Anwendungseinstellung mit einer Zeichenfolge enthält. Sie erhalten diese Zeichenfolge, indem Sie die Schaltfläche Verbindungsinformationen für den Namespace auswählen. Die Verbindungszeichenfolge muss für einen Event Hubs-Namespace und nicht für den Event Hub selbst sein.

Die Verbindungszeichenfolge muss mindestens über Leseberechtigungen verfügen, um die Funktion zu aktivieren.

Diese Verbindungszeichenfolge sollte in einer Anwendungseinstellung mit einem Namen gespeichert werden, der mit dem von der connection-Eigenschaft der Bindungskonfiguration angegebenen Wert übereinstimmt.

Hinweis

Identitätsbasierte Verbindungen werden vom IoT Hub-Trigger nicht unterstützt. Wenn Sie verwaltete Identitäten durchgängig verwenden müssen, können Sie stattdessen IoT Hub-Routing verwenden, um Daten an einen von Ihnen kontrollierten Event Hub zu senden. Auf diese Weise kann das ausgehende Routing mit einer verwalteten Identität authentifiziert werden. Das Ereignis kann mithilfe der verwalteten Identität aus diesem Event Hub gelesen werden.

Eigenschaften von „host.json“

Die Datei host.json enthält Einstellungen, die das Verhalten des Event Hub-Triggers steuern. Informationen zu verfügbaren Einstellungen finden Sie im Abschnitt Einstellungen für „host.json“.

Nächste Schritte