Freigeben über

Azure IoT Hub-Bindungen für Azure Functions

  • Artikel

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

Wichtig

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

Aktion type
Reagieren auf Ereignisse, die an einen IoT Hub-Ereignisdatenstrom gesendet werden. Trigger

Installieren der Erweiterung

Das NuGet-Erweiterungspaket, das Sie installieren, hängt vom C#-Modus ab, den Sie in Ihrer Funktions-App verwenden:

Funktionen werden in einem isolierten C#-Workerprozess ausgeführt. Weitere Informationen finden Sie im Leitfaden zum Ausführen von Azure Functions (C#) in einem isolierten Workerprozess.

Die Funktionalität der Erweiterung ist abhängig von der Erweiterungsversion unterschiedlich:

Diese Version führt die Möglichkeit zur Verbindungsherstellung mithilfe einer Identität anstelle eines Geheimnisses ein. Ein Tutorial zum Konfigurieren Ihrer Funktions-Apps mit verwalteten Identitäten finden Sie im Tutorial zum Erstellen einer Funktions-App mit identitätsbasierten Verbindungen.

Diese Version unterstützt die Konfiguration von Triggern und Bindungen über die .NET Aspire-Integration.

Fügen Sie ihrem Projekt die Erweiterung hinzu, indem Sie das NuGet-Paket, Version 5.x, installieren.

Installieren des Pakets

Die Event Hubs-Erweiterung ist Teil eines Erweiterungspakets, das in Ihrer Projektdatei „host.json“ angegeben wird. Möglicherweise müssen Sie dieses Paket ändern, um die Version der Bindung zu ändern, oder wenn Pakete noch nicht installiert sind. Weitere Informationen finden Sie unter Erweiterungspakete.

Diese Version führt die Möglichkeit zur Verbindungsherstellung mithilfe einer Identität anstelle eines Geheimnisses ein. Ein Tutorial zum Konfigurieren Ihrer Funktions-Apps mit verwalteten Identitäten finden Sie im Tutorial zum Erstellen einer Funktions-App mit identitätsbasierten Verbindungen.

Sie können diese Version der Erweiterung aus dem Erweiterungspaket v3 hinzufügen, indem Sie den folgenden Code in Ihrer Datei host.json hinzufügen oder ersetzen:

{
    "version": "2.0",
    "extensionBundle": {
        "id": "Microsoft.Azure.Functions.ExtensionBundle",
        "version": "[3.3.0, 4.0.0)"
    }
}

Weitere Informationen finden Sie unter Aktualisierung Ihrer Erweiterungen.

Bindungstypen

Die für .NET unterstützten Bindungstypen hängen sowohl vom Erweiterungsversions- als auch vom C#-Ausführungsmodus ab, der eine der folgenden Optionen sein kann:

Eine Klassenbibliothek in einem isolierten Workerprozess ist eine kompilierte C#-Funktion, die in einem von der Runtime isolierten Prozess ausgeführt wird.

Wählen Sie eine Version aus, um für den Modus und die Version Details zum Bindungstyp anzuzeigen.

Der isolierte Workerprozess unterstützt Parametertypen gemäß den folgenden Tabellen. Unterstützung für die Bindung an Typen aus Azure.Messaging.EventHubs befindet sich in der Vorschauphase.

Event Hubs-Trigger

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.

Event Hubs-Ausgabebindung

Wenn die Funktion ein einzelnes Ereignis schreiben soll, kann die Event Hubs-Ausgabebindung 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 Ein Objekt, das das Ereignis darstellt. Functions versucht, einen POCO-Typ (Plain-Old CLR Object) in JSON-Daten zu serialisieren.

Wenn die Funktion mehrere Ereignisse schreiben soll, kann die Event Hubs-Ausgabebindung an die folgenden Typen gebunden werden:

type BESCHREIBUNG
T[], wobei T einer der einzelnen Ereignistypen ist Ein Array, das mehrere Ereignisse enthält. Jeder Eintrag stellt ein Ereignis dar.

Erstellen und verwenden Sie für andere Ausgabeszenarien einen EventHubProducerClient mit anderen Typen von Azure.Messaging.EventHubs direkt. Ein Beispiel für die Verwendung der Abhängigkeitsinjektion zum Erstellen eines Clienttyps aus dem Azure SDK finden Sie unter Registrieren von Azure-Clients .

Einstellungen für „host.json“

Die Datei host.json enthält Einstellungen, die das Verhalten für Event Hubs-Trigger steuern. Die Konfiguration unterscheidet sich abhängig von der Version der Erweiterung.

{
    "version": "2.0",
    "extensions": {
        "eventHubs": {
            "maxEventBatchSize" : 100,
            "minEventBatchSize" : 25,
            "maxWaitTime" : "00:05:00",            
            "batchCheckpointFrequency" : 1,
            "prefetchCount" : 300,
            "transportType" : "amqpWebSockets",
            "webProxy" : "https://proxyserver:8080",
            "customEndpointAddress" : "amqps://company.gateway.local",
            "targetUnprocessedEventThreshold" : 75,
            "initialOffsetOptions" : {
                "type" : "fromStart",
                "enqueuedTimeUtc" : ""
            },
            "clientRetryOptions":{
                "mode" : "exponential",
                "tryTimeout" : "00:01:00",
                "delay" : "00:00:00.80",
                "maximumDelay" : "00:01:00",
                "maximumRetries" : 3
            }
        }
    }
}
Eigenschaft Standard Beschreibung
maxEventBatchSize2 100 Die maximale Anzahl der Ereignisse, die in einem Batch für einen einzelnen Aufruf enthalten sind. Die Anzahl muss mindestens 1 sein.
minEventBatchSize1 1 Die Mindestanzahl von Ereignissen, die in einem Batch gewünscht sind. Das Minimum gilt nur, wenn die Funktion mehrere Ereignisse empfängt, und muss kleiner als maxEventBatchSize sein.
Die Mindestgröße ist nicht streng garantiert. Ein partieller Batch wird versendet, wenn ein vollständiger Batch nicht vorbereitet werden kann, bevor maxWaitTime abgelaufen ist. Partielle Batches sind auch für den ersten Aufruf der Funktion nach der Skalierung wahrscheinlich.
maxWaitTime1 00:01:00 Das maximale Intervall, das der Trigger warten sollte, um einen Batch zu füllen, bevor die Funktion aufgerufen wird. Die Wartezeit wird nur berücksichtigt, wenn minEventBatchSize größer als 1 ist, und wird andernfalls ignoriert. Wenn weniger als minEventBatchSize Ereignisse verfügbar waren, bevor die Wartezeit verstrichen ist, wird die Funktion mit einem partiellen Batch aufgerufen. Die längste zulässige Wartezeit beträgt 10 Minuten.

HINWEIS: Dieses Intervall ist keine strikte Garantie für den genauen Zeitpunkt, zu dem die Funktion aufgerufen wird. Es gibt eine kleine Fehlertoleranz aufgrund der Timergenauigkeit. Wenn die Skalierung erfolgt, kann der erste Aufruf mit einem partiellen Batch schneller erfolgen oder bis zu doppelt so lange dauern wie die konfigurierte Wartezeit.
batchCheckpointFrequency 1 Die Anzahl der zu verarbeitenden Batches, bevor ein Prüfpunkt für den Event Hub erstellt wird
prefetchCount 300 Die Anzahl der Ereignisse, die von Event Hubs dringend angefordert und in einem lokalen Cache gespeichert werden, um Lesezugriffe zu ermöglichen, um das Warten auf einen Netzwerkvorgang zu vermeiden
transportType amqpTcp Das Protokoll und der Transport, die für die Kommunikation mit Event Hubs verwendet werden. Verfügbare Optionen: amqpTcp, amqpWebSockets
webProxy NULL Der Proxy, der für die Kommunikation mit Event Hubs über Websockets verwendet werden soll. Ein Proxy kann nicht mit dem amqpTcp-Datentransport verwendet werden.
customEndpointAddress NULL Die Adresse, die beim Herstellen einer Verbindung mit Event Hubs verwendet werden soll, sodass Netzwerkanforderungen über ein Anwendungsgateway oder einen anderen Pfad weitergeleitet werden können, der für die Hostumgebung benötigt wird. Der vollqualifizierte Namespace für den Event Hub wird weiterhin benötigt, wenn eine benutzerdefinierte Endpunktadresse verwendet wird, und er muss explizit oder über die Verbindungszeichenfolge angegeben werden.
targetUnprocessedEventThreshold1 NULL Die gewünschte Anzahl nicht verarbeiteter Ereignisse pro Funktionsinstanz. Dieser Schwellenwert wird bei der zielbasierten Skalierung verwendet, um den von der Option maxEventBatchSize abgeleiteten standardmäßigen Skalierungsschwellenwert zu überschreiben. Wenn der Wert festgelegt ist, wird die Gesamtzahl der unverarbeiteten Ereignisse durch diesen Wert geteilt, um die Anzahl der benötigten Funktionsinstanzen zu bestimmen. Die Instanzanzahl wird auf eine Zahl aufgerundet, die eine ausgewogene Partitionsverteilung erstellt.
initialOffsetOptions/type fromStart Der Punkt innerhalb des Ereignisdatenstroms, von dem aus die Verarbeitung gestartet wird, wenn im Speicher kein Prüfpunkt vorhanden ist. Gilt für alle Partitionen. Weitere Informationen finden Sie in der OffsetType-Dokumentation. Verfügbare Optionen: fromStart, fromEnd, fromEnqueuedTime
initialOffsetOptions/enqueuedTimeUtc NULL Gibt für das Ereignis des Datenstroms den Zeitpunkt der Einreihung in die Warteschlange an, ab dem mit der Verarbeitung begonnen werden soll. Wenn initialOffsetOptions/type als fromEnqueuedTime konfiguriert wird, ist diese Einstellung obligatorisch. Es werden Zeitangaben in allen Formaten unterstützt, die von DateTime.Parse() unterstützt werden, z. B. 2020-10-26T20:31Z. Der Eindeutigkeit halber sollten Sie auch eine Zeitzone angeben. Wenn keine Zeitzone angegeben wird, wird von Functions die lokale Zeitzone des Computers übernommen, auf dem die Funktions-App ausgeführt wird. Bei der Ausführung in Azure ist dies „UTC“.
clientRetryOptions/mode exponential Die Methode, die zum Berechnen von Wiederholungsverzögerungen verwendet werden soll Im exponentiellen Modus werden Wiederholungsversuche mit einer Verzögerung basierend auf einer Wartezeitstrategie ausgeführt, bei der jeder Versuch die Wartezeit erhöht, bevor ein neuer Versuch beginnt. Im fixen Modus werden Versuche in festen Abständen wiederholt, und jede Verzögerung hat die gleiche Dauer. Verfügbare Optionen: exponential, fixed
clientRetryOptions/tryTimeout 00:01:00 Die maximale Dauer, die pro Versuch auf den Abschluss eines Event Hubs-Vorgangs gewartet werden soll
clientRetryOptions/delay 00:00:00.80 Der Verzögerungs- oder Wartezeitfaktor, der zwischen Wiederholungsversuchen angewendet werden soll
clientRetryOptions/maximumDelay 00:00:01 Die maximale zugelassene Verzögerung zwischen Wiederholungsversuchen
clientRetryOptions/maximumRetries 3 Die maximale Anzahl von Wiederholungsversuchen, bevor der zugeordnete Vorgang als fehlgeschlagen angesehen wird

1 Verwenden von minEventBatchSize und maxWaitTime erfordert v5.3.0 des Microsoft.Azure.WebJobs.Extensions.EventHubs-Pakets oder eine höhere Version.

2 Der Standardwert maxEventBatchSize wurde in v6.0.0 des Microsoft.Azure.WebJobs.Extensions.EventHubs-Pakets geändert. In früheren Versionen war er „10“.

Die clientRetryOptions werden verwendet, um Vorgänge zwischen dem Functions-Host und Event Hubs (z. B. Abrufen von Ereignissen und Senden von Ereignissen) zu wiederholen. Informationen zum Anwenden von Wiederholungsrichtlinien auf einzelne Funktionen finden Sie in der Anleitung Fehlerbehandlung und Wiederholungen in Azure Functions.

Eine Referenz für „host.json“ in Azure Functions 2x und höheren Versionen finden Sie in der host.json-Referenz für Azure Functions 2.x oder höher.

Nächste Schritte