Azure IoT Hub-trigger voor Azure Functions

  • Artikel

In dit artikel wordt uitgelegd hoe u werkt met Azure Functions-bindingen voor IoT Hub. De IoT Hub-ondersteuning is gebaseerd op de Azure Event Hubs-binding.

Zie het overzicht voor informatie over het instellen en configureren van details.

Belangrijk

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

Gebruik de functietrigger om te reageren op een gebeurtenis die naar een event hub-gebeurtenisstroom wordt verzonden. U moet leestoegang hebben tot de onderliggende event hub om de trigger in te stellen. Wanneer de functie wordt geactiveerd, wordt het aan de functie doorgegeven bericht getypeerd als een tekenreeks.

Event Hubs-schaalbeslissingen voor de Abonnementen Verbruik en Premium worden uitgevoerd via schalen op basis van doel. Zie Schalen op basis van doel voor meer informatie.

Zie Event Hubs integreren met serverloze functies in Azure voor informatie over hoe Azure Functions reageert op gebeurtenissen die zijn verzonden naar een Event Hub-gebeurtenisstroom met behulp van triggers.

Belangrijk

In dit artikel worden tabbladen gebruikt ter ondersteuning van meerdere versies van het Node.js programmeermodel. Het v4-model is algemeen beschikbaar en is ontworpen voor een flexibelere en intuïtievere ervaring voor JavaScript- en TypeScript-ontwikkelaars. Raadpleeg de ontwikkelaarshandleiding voor Azure Functions Node.js voor meer informatie over hoe het v4-model werkt. Raadpleeg de migratiehandleiding voor meer informatie over de verschillen tussen v3 en v4.

Azure Functions ondersteunt twee programmeermodellen voor Python. De manier waarop u uw bindingen definieert, is afhankelijk van het gekozen programmeermodel.

Met het Python v2-programmeermodel kunt u bindingen definiëren met behulp van decorators rechtstreeks in uw Python-functiecode. Zie de Ontwikkelaarshandleiding voor Python voor meer informatie.

Dit artikel ondersteunt beide programmeermodellen.

Opmerking

In het volgende voorbeeld ziet u een C#-functie die wordt geactiveerd op basis van een Event Hub, waarbij de tekenreeks voor het invoerbericht naar de logboeken wordt geschreven:

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

In het volgende voorbeeld ziet u een TypeScript-functie voor een Event Hubs-trigger. De functie leest gebeurtenismetagegevens en registreert het bericht.

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

Als u gebeurtenissen in een batch wilt ontvangen, stelt u in op cardinalitymany, zoals wordt weergegeven in het volgende voorbeeld.

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

In het volgende voorbeeld ziet u een Event Hubs-trigger javaScript-functie. De functie leest gebeurtenismetagegevens en registreert het bericht.

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

Als u gebeurtenissen in een batch wilt ontvangen, stelt u in op cardinalitymany, zoals wordt weergegeven in het volgende voorbeeld.

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

Dit is de PowerShell-code:

param($eventHubMessages, $TriggerMetadata)

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

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

In het volgende voorbeeld ziet u een Event Hubs-triggerbinding en een Python-functie die gebruikmaakt van de binding. De functie leest gebeurtenismetagegevens en registreert het bericht. Het voorbeeld is afhankelijk van of u het python-programmeermodel v1 of v2 gebruikt.

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

In het volgende voorbeeld ziet u een Event Hubs-triggerbinding waarmee de berichttekst van de Event Hubs-trigger wordt geregistreerd.

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

Gebruik in de Runtime-bibliotheek van Java-functies de EventHubTrigger aantekening voor parameters waarvan de waarde afkomstig is van de Event Hub. Door parameters met deze aantekeningen wordt de functie uitgevoerd wanneer er een gebeurtenis optreedt. Deze aantekening kan worden gebruikt met systeemeigen Java-typen, POJO's of nullbare waarden met Optional<T>.

In het volgende voorbeeld ziet u uitgebreid gebruik van SystemProperties en andere bindingsopties voor verdere introspectie van de gebeurtenis, samen met een goed gevormd BlobOutput pad dat datumhiërarchie is.

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

Kenmerken

Zowel in-processals geïsoleerde werkproces C#-bibliotheken gebruiken kenmerk om de trigger te configureren. C#-script maakt in plaats daarvan gebruik van een function.json configuratiebestand, zoals beschreven in de handleiding voor C#-scripts.

Gebruik de EventHubTriggerAttribute opdracht om een trigger te definiëren op een Event Hub, die ondersteuning biedt voor de volgende eigenschappen.

Parameters Beschrijving
EventHubName De naam van de event hub. Wanneer de event hub-naam ook aanwezig is in de verbindingsreeks, overschrijft die waarde deze eigenschap tijdens runtime. Kan worden verwezen in app-instellingen, zoals %eventHubName%
ConsumerGroup Een optionele eigenschap waarmee de consumentengroep wordt ingesteld die wordt gebruikt om abonnementen te nemen op gebeurtenissen in de hub. Als u dit weglaat, wordt de $Default consumentengroep gebruikt.
Verbinding De naam van een app-instelling of instellingsverzameling die aangeeft hoe verbinding moet worden gemaakt met Event Hubs. Zie Verbinding maken ions voor meer informatie.

Decorators

Is alleen van toepassing op het Python v2-programmeermodel.

Voor Python v2-functies die zijn gedefinieerd met behulp van een decorator, zijn de volgende eigenschappen op het cosmos_db_triggervolgende:

Eigenschappen Beschrijving
arg_name De naam van de variabele die het gebeurtenisitem in functiecode vertegenwoordigt.
event_hub_name De naam van de event hub. Wanneer de event hub-naam ook aanwezig is in de verbindingsreeks, overschrijft die waarde deze eigenschap tijdens runtime.
connection De naam van een app-instelling of instellingsverzameling die aangeeft hoe verbinding moet worden gemaakt met Event Hubs. Zie Verbinding maken ions.

Zie de sectie Configuratie voor Python-functies die zijn gedefinieerd met behulp van function.json.

Aantekeningen

Gebruik in de Java Functions Runtime-bibliotheek de aantekening eventHubTrigger , die ondersteuning biedt voor de volgende instellingen:

Configuratie

Is alleen van toepassing op het Python v1-programmeermodel.

In de volgende tabel worden de eigenschappen uitgelegd die u kunt instellen voor het options object dat aan de app.eventHub() methode is doorgegeven.

Eigenschappen Beschrijving
eventHubName De naam van de event hub. Wanneer de event hub-naam ook aanwezig is in de verbindingsreeks, overschrijft die waarde deze eigenschap tijdens runtime. Kan worden verwezen via app-instellingen%eventHubName%
consumerGroup Een optionele eigenschap waarmee de consumentengroep wordt ingesteld die wordt gebruikt om abonnementen te nemen op gebeurtenissen in de hub. Als deze wordt weggelaten, wordt de $Default-consumentengroep gebruikt.
cardinality Stel in op many om batchverwerking mogelijk te maken. Als deze eigenschap wordt weggelaten of ingesteld op one, wordt er één bericht doorgegeven aan de functie.
verbinding De naam van een app-instelling of instellingsverzameling die aangeeft hoe verbinding moet worden gemaakt met Event Hubs. Zie Verbinding maken ions.

In de volgende tabel worden de eigenschappen van de triggerconfiguratie uitgelegd die u hebt ingesteld in het function.json-bestand , wat verschilt per runtimeversie.

function.json-eigenschap Beschrijving
type Moet worden ingesteld op eventHubTrigger. Deze eigenschap wordt automatisch ingesteld wanneer u de trigger maakt in de Azure-portal.
direction Moet worden ingesteld op in. Deze eigenschap wordt automatisch ingesteld wanneer u de trigger maakt in de Azure-portal.
name De naam van de variabele die het gebeurtenisitem in functiecode vertegenwoordigt.
eventHubName De naam van de event hub. Wanneer de event hub-naam ook aanwezig is in de verbindingsreeks, overschrijft die waarde deze eigenschap tijdens runtime. Kan worden verwezen via app-instellingen%eventHubName%
consumerGroup Een optionele eigenschap waarmee de consumentengroep wordt ingesteld die wordt gebruikt om abonnementen te nemen op gebeurtenissen in de hub. Als deze wordt weggelaten, wordt de $Default-consumentengroep gebruikt.
cardinality Stel in op many om batchverwerking mogelijk te maken. Als deze eigenschap wordt weggelaten of ingesteld op one, wordt er één bericht doorgegeven aan de functie.
verbinding De naam van een app-instelling of instellingsverzameling die aangeeft hoe verbinding moet worden gemaakt met Event Hubs. Zie Verbinding maken ions.

Wanneer u lokaal ontwikkelt, voegt u uw toepassingsinstellingen toe aan het local.settings.json-bestand in de Values verzameling.

Gebruik

Zie Gebeurtenissen gebruiken met Azure Functions voor meer informatie over de schaal van Event Hubs-triggers en IoT Hub-triggers.

Het parametertype dat wordt ondersteund door de Event Hubs-uitvoerbinding, is afhankelijk van de runtimeversie van Functions, de versie van het extensiepakket en de gebruikte C#-modaliteit.

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.

Het parametertype kan een van de volgende zijn:

  • Systeemeigen Java-typen, zoals int, tekenreeks, byte[].
  • Null-waarden met optioneel.
  • Elk POJO-type.

Zie de naslaginformatie over EventHubTrigger voor meer informatie.

Gebeurtenismetagegevens

De Event Hubs-trigger biedt verschillende metagegevenseigenschappen. Metagegevenseigenschappen kunnen worden gebruikt als onderdeel van bindingsexpressies in andere bindingen of als parameters in uw code. De eigenschappen zijn afkomstig van de Event Data-klasse.

Eigenschap Type Description
PartitionContext PartitionContext Het PartitionContext-exemplaar.
EnqueuedTimeUtc DateTime De wachtrijtijd in UTC.
Offset string De verschuiving van de gegevens ten opzichte van de Event Hub-partitiestroom. De offset is een markering of id voor een gebeurtenis binnen de Event Hubs-stroom. De id is uniek binnen een partitie van de Event Hubs-stroom.
PartitionKey string De partitie waarnaar gebeurtenisgegevens moeten worden verzonden.
Properties IDictionary<String,Object> De gebruikerseigenschappen van de gebeurtenisgegevens.
SequenceNumber Int64 Het logische volgnummer van de gebeurtenis.
SystemProperties IDictionary<String,Object> De systeemeigenschappen, inclusief de gebeurtenisgegevens.

Zie codevoorbeelden die gebruikmaken van deze eigenschappen eerder in dit artikel.

Connecties

De connection eigenschap is een verwijzing naar de omgevingsconfiguratie met de naam van een toepassingsinstelling die een verbindingsreeks bevat. U kunt deze verbindingsreeks ophalen door de knop Verbinding maken ion Information voor de naamruimte te selecteren. De verbindingsreeks moet voor een Event Hubs-naamruimte zijn, niet voor de Event Hub zelf.

De verbindingsreeks moet ten minste leesmachtigingen hebben om de functie te activeren.

Deze verbindingsreeks moet worden opgeslagen in een toepassingsinstelling met een naam die overeenkomt met de waarde die is opgegeven door de connection eigenschap van de bindingsconfiguratie.

Notitie

Op identiteit gebaseerde verbindingen worden niet ondersteund door de IoT Hub-trigger. Als u beheerde identiteiten end-to-end wilt gebruiken, kunt u in plaats daarvan IoT Hub-routering gebruiken om gegevens te verzenden naar een Event Hub die u beheert. Op die manier kan uitgaande routering worden geverifieerd met een beheerde identiteit, kan de gebeurtenis worden gelezen vanuit die Event Hub met behulp van een beheerde identiteit.

host.json-eigenschappen

Het bestand host.json bevat instellingen waarmee het gedrag van de Event Hub-trigger wordt bepaald. Zie de sectie host.json instellingen voor meer informatie over beschikbare instellingen.

Volgende stappen