Delen via

Azure IoT Hub-bindingen voor Azure Functions

  • Artikel

In deze reeks artikelen wordt uitgelegd hoe u kunt werken met Azure Functions-bindingen voor IoT Hub. De IoT Hub-ondersteuning is gebaseerd op de Azure Event Hubs-binding.

Belangrijk

Hoewel in de volgende codevoorbeelden de Event Hub-API wordt gebruikt, is de opgegeven syntaxis van toepassing voor IoT Hub-functies.

Actie Type
Reageren op gebeurtenissen die zijn verzonden naar een IoT Hub-gebeurtenisstroom. Trigger

De extensie installeren

Het NuGet-extensiepakket dat u installeert, is afhankelijk van de C#-modus die u gebruikt in uw functie-app:

Functies worden uitgevoerd in een geïsoleerd C#-werkproces. Zie De handleiding voor het uitvoeren van C# Azure Functions in een geïsoleerd werkproces voor meer informatie.

De functionaliteit van de extensie varieert afhankelijk van de extensieversie:

Deze versie introduceert de mogelijkheid om verbinding te maken met behulp van een identiteit in plaats van een geheim. Zie de zelfstudie over het maken van een functie-app met op identiteit gebaseerde verbindingen voor een zelfstudie over het configureren van uw functie-apps met beheerde identiteiten.

Deze versie ondersteunt de configuratie van triggers en bindingen via .NET Aspire-integratie.

Voeg de extensie toe aan uw project door het NuGet-pakket versie 5.x te installeren.

Bundel installeren

De Event Hubs-extensie maakt deel uit van een extensiebundel, die is opgegeven in uw host.json projectbestand. Mogelijk moet u deze bundel wijzigen om de versie van de binding te wijzigen of als bundels nog niet zijn geïnstalleerd. Zie uitbreidingsbundel voor meer informatie.

Deze versie introduceert de mogelijkheid om verbinding te maken met behulp van een identiteit in plaats van een geheim. Zie de zelfstudie over het maken van een functie-app met op identiteit gebaseerde verbindingen voor een zelfstudie over het configureren van uw functie-apps met beheerde identiteiten.

U kunt deze versie van de extensie toevoegen vanuit de extensiebundel v3 door de volgende code toe te voegen of te vervangen in uw host.json bestand:

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

Zie Uw extensies bijwerken voor meer informatie.

Bindingstypen

De bindingstypen die voor .NET worden ondersteund, zijn afhankelijk van zowel de extensieversie als de C#-uitvoeringsmodus. Dit kan een van de volgende opties zijn:

Een geïsoleerde werkprocesklassebibliotheek gecompileerde C#-functie wordt uitgevoerd in een proces dat is geïsoleerd van de runtime.

Kies een versie om de details van het bindingstype voor de modus en versie weer te geven.

Het geïsoleerde werkproces ondersteunt parametertypen volgens de onderstaande tabellen. Ondersteuning voor binding met typen van Azure.Messaging.EventHubs is in preview.

Event Hubs-trigger

Wanneer u wilt dat de functie één gebeurtenis verwerkt, kan de Event Hubs-trigger worden gekoppeld aan de volgende typen:

Type Description
string De gebeurtenis als een tekenreeks. Gebruik deze tekst wanneer de gebeurtenis eenvoudige tekst is.
byte[] De bytes van de gebeurtenis.
JSON serialiseerbare typen Wanneer een gebeurtenis JSON-gegevens bevat, probeert Functions deSerialiseren van de JSON-gegevens in een niet-oud POCO-type (CLR-object).
Azure.Messaging.EventHubs.EventData1 Het gebeurtenisobject.
Als u migreert van oudere versies van de Event Hubs SDK's, moet u er rekening mee houden dat deze versie geen ondersteuning meer biedt voor het verouderde Body type ten gunste van EventBody.

Wanneer u wilt dat de functie een batch gebeurtenissen verwerkt, kan de Event Hubs-trigger verbinding maken met de volgende typen:

Type Description
string[] Een matrix met gebeurtenissen uit de batch, als tekenreeksen. Elke vermelding vertegenwoordigt één gebeurtenis.
EventData[] 1 Een matrix met gebeurtenissen uit de batch, als exemplaren van Azure.Messaging.EventHubs.EventData. Elke vermelding vertegenwoordigt één gebeurtenis.
T[] waarbij T een JSON serialiseerbaar type1 is Een matrix met gebeurtenissen uit de batch, als exemplaren van een aangepast POCO-type. Elke vermelding vertegenwoordigt één gebeurtenis.

1 Als u deze typen wilt gebruiken, moet u verwijzen naar Microsoft.Azure.Functions.Worker.Extensions.EventHubs 5.5.0 of hoger en de algemene afhankelijkheden voor SDK-typebindingen.

Event Hubs-uitvoerbinding

Wanneer u wilt dat de functie één gebeurtenis schrijft, kan de Event Hubs-uitvoerbinding worden gekoppeld aan de volgende typen:

Type Description
string De gebeurtenis als een tekenreeks. Gebruik deze tekst wanneer de gebeurtenis eenvoudige tekst is.
byte[] De bytes van de gebeurtenis.
JSON serialiseerbare typen Een object dat de gebeurtenis vertegenwoordigt. Functions probeert een eenvoudig oud CLR-objecttype (POCO) te serialiseren in JSON-gegevens.

Wanneer u wilt dat de functie meerdere gebeurtenissen schrijft, kan de Event Hubs-uitvoerbinding worden gekoppeld aan de volgende typen:

Type Description
T[] waarbij T een van de gebeurtenistypen voor één gebeurtenis is Een matrix met meerdere gebeurtenissen. Elke vermelding vertegenwoordigt één gebeurtenis.

Voor andere uitvoerscenario's maakt en gebruikt u rechtstreeks een EventHubProducerClient met andere typen van Azure.Messaging.EventHubs . Zie Azure-clients registreren voor een voorbeeld van het gebruik van afhankelijkheidsinjectie om een clienttype te maken op basis van de Azure SDK.

host.json-instellingen

Het bestand host.json bevat instellingen waarmee het gedrag van de Event Hubs-trigger wordt bepaald. De configuratie verschilt, afhankelijk van de extensieversie.

{
    "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
            }
        }
    }
}
Eigenschappen Standaard Beschrijving
maxEventBatchSize2 100 Het maximum aantal gebeurtenissen dat in een batch is opgenomen voor één aanroep. Moet ten minste 1 zijn.
minEventBatchSize1 1 Het minimale aantal gebeurtenissen dat in een batch is gewenst. Het minimum geldt alleen wanneer de functie meerdere gebeurtenissen ontvangt en kleiner moet zijn dan maxEventBatchSize.
De minimale grootte is niet strikt gegarandeerd. Een gedeeltelijke batch wordt verzonden wanneer een volledige batch niet kan worden voorbereid voordat de maxWaitTime batch is verstreken. Gedeeltelijke batches zijn ook waarschijnlijk voor de eerste aanroep van de functie nadat de schaal is uitgevoerd.
maxWaitTime1 00:01:00 Het maximale interval dat de trigger moet wachten om een batch te vullen voordat de functie wordt aangeroepen. De wachttijd wordt alleen overwogen wanneer minEventBatchSize deze groter is dan 1 en anders wordt genegeerd. Als er minder dan minEventBatchSize gebeurtenissen beschikbaar waren voordat de wachttijd is verstreken, wordt de functie aangeroepen met een gedeeltelijke batch. De langst toegestane wachttijd is 10 minuten.

OPMERKING: Dit interval is geen strikte garantie voor de exacte timing waarop de functie wordt aangeroepen. Er is een kleine foutmarge vanwege de precisie van de timer. Wanneer het schalen plaatsvindt, kan de eerste aanroep met een gedeeltelijke batch sneller plaatsvinden of kan het tot twee keer zo lang duren als de geconfigureerde wachttijd.
batchCheckpointFrequency 1 Het aantal batches dat moet worden verwerkt voordat u een controlepunt voor de Event Hub maakt.
prefetchCount 300 Het aantal gebeurtenissen dat graag wordt aangevraagd bij Event Hubs en wordt bewaard in een lokale cache om leesbewerkingen toe te staan om te voorkomen dat er wordt gewacht op een netwerkbewerking
transportType amqpTcp Het protocol en het transport dat wordt gebruikt voor communicatie met Event Hubs. Beschikbare opties: amqpTcp, amqpWebSockets
webProxy Nul De proxy die moet worden gebruikt voor communicatie met Event Hubs via websockets. Een proxy kan niet worden gebruikt met het amqpTcp transport.
customEndpointAddress Nul Het adres dat moet worden gebruikt bij het tot stand brengen van een verbinding met Event Hubs, zodat netwerkaanvragen kunnen worden gerouteerd via een toepassingsgateway of een ander pad dat nodig is voor de hostomgeving. De volledig gekwalificeerde naamruimte voor de Event Hub is nog steeds nodig wanneer een aangepast eindpuntadres wordt gebruikt en moet expliciet of via de verbindingsreeks worden opgegeven.
targetUnprocessedEventThreshold1 Nul Het gewenste aantal niet-verwerkte gebeurtenissen per functie-exemplaar. De drempelwaarde wordt gebruikt bij het schalen op basis van doel om de standaarddrempelwaarde voor schalen te overschrijven die is afgeleid van de maxEventBatchSize optie. Wanneer dit is ingesteld, wordt het totale aantal niet-verwerkte gebeurtenissen gedeeld door deze waarde om het aantal benodigde functie-exemplaren te bepalen. Het aantal exemplaren wordt naar boven afgerond op een getal waarmee een evenwichtige partitieverdeling wordt gemaakt.
initialOffsetOptions/type fromStart De locatie in de gebeurtenisstroom om te beginnen met verwerken wanneer er geen controlepunt in de opslag aanwezig is. Dit is van toepassing op alle partities. Zie de OffsetType-documentatie voor meer informatie. Beschikbare opties: fromStart, fromEndfromEnqueuedTime
initialOffsetOptions/enqueuedTimeUtc Nul Hiermee wordt de wachtrijtijd aangegeven van de gebeurtenis in de gegevensstroom waar de verwerking moet beginnen. Wanneer initialOffsetOptions/type is geconfigureerd als fromEnqueuedTime, is deze instelling verplicht. Ondersteunt tijd in alle indelingen die worden ondersteund door DateTime.Parse(), zoals 2020-10-26T20:31Z. U kunt het best ook een tijdzone opgeven. Als er geen tijdzone is opgegeven, gebruikt Functions de lokale tijdzone van de computer waarop de functie-app wordt uitgevoerd. Als u Azure gebruikt, is dat UTC.
clientRetryOptions/modus exponentieel De methode die moet worden gebruikt voor het berekenen van vertragingen voor opnieuw proberen. Nieuwe pogingen in de exponentiële modus met een vertraging op basis van een back-off-strategie waarbij elke poging de duur verhoogt die wordt gewacht voordat het opnieuw wordt geprobeerd. In de vaste modus worden pogingen geprobeerd met vaste intervallen, waarbij elke vertraging een consistente duur heeft. Beschikbare opties: exponential, fixed
clientRetryOptions/tryTimeout 00:01:00 De maximale duur om te wachten totdat een Event Hubs-bewerking is voltooid, per poging.
clientRetryOptions/delay 00:00:00.80 De vertragings- of uitstelfactor die moet worden toegepast tussen nieuwe pogingen.
clientRetryOptions/maximumDelay 00:00:01 De maximale vertraging die moet worden toegestaan tussen nieuwe pogingen.
clientRetryOptions/maximumRetries 3 Het maximum aantal nieuwe pogingen voordat de gekoppelde bewerking is mislukt.

1 Gebruikt minEventBatchSize en maxWaitTime vereist v5.3.0 van het Microsoft.Azure.WebJobs.Extensions.EventHubs pakket of een latere versie.

2 De standaardwaarde maxEventBatchSize is gewijzigd in v6.0.0 van het Microsoft.Azure.WebJobs.Extensions.EventHubs pakket. In eerdere versies was dit 10.

De clientRetryOptions bewerkingen worden gebruikt om bewerkingen opnieuw uit te voeren tussen de Functions-host en Event Hubs (zoals het ophalen van gebeurtenissen en het verzenden van gebeurtenissen). Raadpleeg de richtlijnen voor foutafhandeling en nieuwe pogingen van Azure Functions voor informatie over het toepassen van beleid voor nieuwe pogingen op afzonderlijke functies.

Zie Naslaginformatie over host.json voor Azure Functions voor naslaginformatie over host.json in Azure Functions 2.x en hoger.

Volgende stappen