Azure IoT Hub-bindningar för Azure Functions

  • Artikel

Den här uppsättningen artiklar beskriver hur du arbetar med Azure Functions-bindningar för IoT Hub. IoT Hub-stödet baseras på Azure Event Hubs-bindningen.

Viktigt!

Följande kodexempel använder Event Hub-API:et, men den angivna syntaxen gäller för IoT Hub-funktioner.

Åtgärd Typ
Svara på händelser som skickas till en IoT Hub-händelseström. Utlösare

Installera tillägget

Vilket NuGet-tilläggspaket du installerar beror på vilket C#-läge du använder i funktionsappen:

Funktioner körs i en isolerad C#-arbetsprocess. Mer information finns i Guide för att köra C# Azure Functions i en isolerad arbetsprocess.

Funktionerna i tillägget varierar beroende på tilläggsversionen:

Den här versionen introducerar möjligheten att ansluta med hjälp av en identitet i stället för en hemlighet. En självstudiekurs om hur du konfigurerar dina funktionsappar med hanterade identiteter finns i självstudien skapa en funktionsapp med identitetsbaserade anslutningar.

Lägg till tillägget i projektet genom att installera NuGet-paketet version 5.x.

Installera paket

Event Hubs-tillägget är en del av ett tilläggspaket som anges i din host.json projektfil. Du kan behöva ändra det här paketet för att ändra versionen av bindningen, eller om paket inte redan är installerade. Mer information finns i tilläggspaketet.

Den här versionen introducerar möjligheten att ansluta med hjälp av en identitet i stället för en hemlighet. En självstudiekurs om hur du konfigurerar dina funktionsappar med hanterade identiteter finns i självstudien skapa en funktionsapp med identitetsbaserade anslutningar.

Du kan lägga till den här versionen av tillägget från tilläggspaketet v3 genom att lägga till eller ersätta följande kod i host.json filen:

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

Mer information finns i Uppdatera dina tillägg.

Bindningstyper

Vilka bindningstyper som stöds för .NET beror på både tilläggsversionen och C#-körningsläget, vilket kan vara något av följande:

Ett isolerat arbetsprocessklassbibliotek kompilerade C#-funktioner körs i en process som är isolerad från körningen.

Välj en version för att se information om bindningstyp för läget och versionen.

Den isolerade arbetsprocessen stöder parametertyper enligt tabellerna nedan. Stöd för bindning till typer från Azure.Messaging.EventHubs finns i förhandsversionen.

Event Hubs-utlösare

När du vill att funktionen ska bearbeta en enskild händelse kan Event Hubs-utlösaren binda till följande typer:

Typ Beskrivning
string Händelsen som en sträng. Använd när händelsen är enkel text.
byte[] Byte för händelsen.
JSON-serialiserbara typer När en händelse innehåller JSON-data försöker Functions deserialisera JSON-data till en vanlig CLR-objekttyp (POCO).
Azure.Messaging.EventHubs.EventData1 Händelseobjektet.
Om du migrerar från äldre versioner av Event Hubs SDK:er bör du tänka på att den här versionen tar bort stödet för den äldre Body typen till förmån för EventBody.

När du vill att funktionen ska bearbeta en batch med händelser kan Event Hubs-utlösaren binda till följande typer:

Typ Beskrivning
string[] En matris med händelser från batchen, som strängar. Varje post representerar en händelse.
EventData[]1 En matris med händelser från batchen, som instanser av Azure.Messaging.EventHubs.EventData. Varje post representerar en händelse.
T[] där T är en JSON-serialiserbar typ1 En matris med händelser från batchen, som instanser av en anpassad POCO-typ. Varje post representerar en händelse.

1 Om du vill använda dessa typer måste du referera till Microsoft.Azure.Functions.Worker.Extensions.EventHubs 5.5.0 eller senare och de vanliga beroendena för SDK-typbindningar.

Event Hubs-utdatabindning

När du vill att funktionen ska skriva en enskild händelse kan Event Hubs-utdatabindningen binda till följande typer:

Typ Beskrivning
string Händelsen som en sträng. Använd när händelsen är enkel text.
byte[] Byte för händelsen.
JSON-serialiserbara typer Ett objekt som representerar händelsen. Functions försöker serialisera en vanlig CLR-objekttyp (POCO) till JSON-data.

När du vill att funktionen ska skriva flera händelser kan Event Hubs-utdatabindningen binda till följande typer:

Typ Beskrivning
T[] där T är en av de enskilda händelsetyperna En matris som innehåller flera händelser. Varje post representerar en händelse.

För andra utdatascenarier skapar och använder du typer från Microsoft.Azure.EventHubs direkt.

host.json inställningar

Filen host.json innehåller inställningar som styr beteendet för Event Hubs-utlösaren. Konfigurationen skiljer sig beroende på tilläggsversionen.

{
    "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
            }
        }
    }
}
Property Standardvärde beskrivning
maxEventBatchSize2 100 Det maximala antalet händelser som ingår i en batch för ett enda anrop. Måste vara minst 1.
minEventBatchSize1 1 Det minsta antalet händelser som önskas i en batch. Minimivärdet gäller endast när funktionen tar emot flera händelser och måste vara mindre än maxEventBatchSize.
Minimistorleken är inte strikt garanterad. En partiell batch skickas när en fullständig batch inte kan förberedas innan den maxWaitTime har förflutit. Partiella batchar är också sannolika för den första anropet av funktionen när skalningen har ägt rum.
maxWaitTime1 00:01:00 Det maximala intervall som utlösaren ska vänta med att fylla en batch innan funktionen anropas. Väntetiden beaktas endast när minEventBatchSize är större än 1 och ignoreras annars. Om mindre än minEventBatchSize händelser var tillgängliga innan väntetiden förflutit anropas funktionen med en partiell batch. Den längsta tillåtna väntetiden är 10 minuter.

Obs! Det här intervallet är inte en strikt garanti för den exakta tidpunkt som funktionen anropas för. Det finns en liten magin av fel på grund av timerprecision. När skalning sker kan det första anropet med en partiell batch ske snabbare eller ta upp till två gånger den konfigurerade väntetiden.
batchCheckpointFrequency 1 Antalet batchar som ska bearbetas innan du skapar en kontrollpunkt för händelsehubben.
prefetchCount 300 Antalet händelser som ivrigt begärs från Event Hubs och lagras i en lokal cache för att tillåta läsningar för att undvika att vänta på en nätverksåtgärd
transportType amqpTcp Protokollet och transporten som används för kommunikation med Event Hubs. Tillgängliga alternativ: amqpTcp, amqpWebSockets
Webproxy NULL Proxyn som ska användas för kommunikation med Event Hubs via webbsocketer. Det går inte att använda en proxy med transporten amqpTcp .
customEndpointAddress NULL Adressen som ska användas när du upprättar en anslutning till Event Hubs, vilket gör att nätverksbegäranden kan dirigeras via en programgateway eller annan sökväg som behövs för värdmiljön. Det fullständigt kvalificerade namnområdet för händelsehubben behövs fortfarande när en anpassad slutpunktsadress används och måste anges uttryckligen eller via anslutningssträng.
targetUnprocessedEventThreshold1 NULL Önskat antal obearbetade händelser per funktionsinstans. Tröskelvärdet används i målbaserad skalning för att åsidosätta standardvärdet för skalning som härleds från maxEventBatchSize alternativet. När den anges divideras det totala antalet obearbetade händelser med det här värdet för att fastställa antalet funktionsinstanser som behövs. Antalet instanser avrundas upp till ett tal som skapar en balanserad partitionsdistribution.
initialOffsetOptions/type fromStart Platsen i händelseströmmen som ska börja bearbetas när en kontrollpunkt inte finns i lagringen. Gäller för alla partitioner. Mer information finns i OffsetType-dokumentationen. Tillgängliga alternativ: fromStart, fromEnd, fromEnqueuedTime
initialOffsetOptions/enqueuedTimeUtc NULL Anger den köade tiden för händelsen i strömmen som bearbetningen ska börja bearbetas från. När initialOffsetOptions/type har konfigurerats som fromEnqueuedTimeär den här inställningen obligatorisk. Stöder tid i alla format som stöds av DateTime.Parse(), till exempel 2020-10-26T20:31Z. För tydlighetens skull bör du också ange en tidszon. När tidszonen inte har angetts förutsätter Functions den lokala tidszonen för datorn som kör funktionsappen, som är UTC när den körs i Azure.
clientRetryOptions/mode Exponentiell Den metod som ska användas för att beräkna fördröjningar av återförsök. Exponentiellt läge försöker igen med en fördröjning baserat på en back-off-strategi där varje försök ökar varaktigheten som det väntar innan du försöker igen. Återförsök i fast läge görs med fasta intervall där varje fördröjning har en konsekvent varaktighet. Tillgängliga alternativ: exponential, fixed
clientRetryOptions/tryTimeout 00:01:00 Den maximala varaktigheten för att vänta tills en Event Hubs-åtgärd har slutförts, per försök.
clientRetryOptions/delay 00:00:00.80 Fördröjnings- eller back-off-faktorn som ska tillämpas mellan återförsök.
clientRetryOptions/maximumDelay 00:00:01 Den maximala fördröjning som tillåts mellan återförsök.
clientRetryOptions/maximumRetries 3 Det maximala antalet återförsök innan du överväger att den associerade åtgärden ska ha misslyckats.

1 Användning minEventBatchSize och maxWaitTime kräver v5.3.0 av Microsoft.Azure.WebJobs.Extensions.EventHubs paketet eller en senare version.

2 Standardvärdet maxEventBatchSize ändrades i v6.0.0 i Microsoft.Azure.WebJobs.Extensions.EventHubs paketet. I tidigare versioner var detta 10.

clientRetryOptions Används för att försöka utföra åtgärder igen mellan Functions-värden och Event Hubs (till exempel att hämta händelser och skicka händelser). Mer information om hur du tillämpar återförsöksprinciper på enskilda funktioner finns i vägledningen om felhantering och återförsök i Azure Functions.

En referens till host.json i Azure Functions 2.x och senare finns i host.json referens för Azure Functions.

Nästa steg