Azure IoT Hub-utlösare för Azure Functions

  • Artikel

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

Information om konfiguration och konfigurationsinformation finns i översikten.

Viktigt!

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

Använd funktionsutlösaren för att svara på en händelse som skickas till en händelseström för händelsehubben. Du måste ha läsbehörighet till den underliggande händelsehubben för att kunna konfigurera utlösaren. När funktionen utlöses skrivs meddelandet som skickas till funktionen som en sträng.

Event Hubs-skalningsbeslut för förbruknings- och Premium-planer görs via målbaserad skalning. Mer information finns i Målbaserad skalning.

Information om hur Azure Functions svarar på händelser som skickas till en händelseström för händelsehubben med utlösare finns i Integrera händelsehubbar med serverlösa funktioner i Azure.

Viktigt!

Den här artikeln använder flikar för att stödja flera versioner av Node.js programmeringsmodellen. V4-modellen är allmänt tillgänglig och är utformad för att ha en mer flexibel och intuitiv upplevelse för JavaScript- och TypeScript-utvecklare. Mer information om hur v4-modellen fungerar finns i utvecklarguiden för Azure Functions Node.js. Mer information om skillnaderna mellan v3 och v4 finns i migreringsguiden.

Azure Functions stöder två programmeringsmodeller för Python. Hur du definierar dina bindningar beror på din valda programmeringsmodell.

Med programmeringsmodellen Python v2 kan du definiera bindningar med hjälp av dekoratörer direkt i python-funktionskoden. Mer information finns i utvecklarguiden för Python.

Den här artikeln stöder båda programmeringsmodellerna.

Exempel

I följande exempel visas en C#-funktion som utlöses baserat på en händelsehubb, där indatameddelandesträngen skrivs till loggarna:

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

I följande exempel visas en TypeScript-funktion för Event Hubs-utlösare. Funktionen läser händelsemetadata och loggar meddelandet.

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

Om du vill ta emot händelser i en batch anger du cardinality till many, som du ser i följande exempel.

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

I följande exempel visas en JavaScript-funktion för Event Hubs-utlösare. Funktionen läser händelsemetadata och loggar meddelandet.

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

Om du vill ta emot händelser i en batch anger du cardinality till many, som du ser i följande exempel.

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

Här är PowerShell-koden:

param($eventHubMessages, $TriggerMetadata)

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

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

I följande exempel visas en Event Hubs-utlösarbindning och en Python-funktion som använder bindningen. Funktionen läser händelsemetadata och loggar meddelandet. Exemplet beror på om du använder python-programmeringsmodellen v1 eller v2.

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

I följande exempel visas en Event Hubs-utlösarbindning som loggar meddelandetexten för Event Hubs-utlösaren.

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

I Java Functions-körningsbiblioteket använder du anteckningen EventHubTrigger på parametrar vars värde kommer från händelsehubben. Parametrar med dessa anteckningar gör att funktionen körs när en händelse kommer. Den här anteckningen kan användas med interna Java-typer, POJO:er eller null-värden med hjälp av Optional<T>.

I följande exempel visas omfattande användning av SystemProperties och andra bindningsalternativ för ytterligare introspektion av händelsen tillsammans med att tillhandahålla en välformulerad BlobOutput sökväg som är datumhierarki.

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

Attribut

C#-bibliotek för både process- och isolerad arbetsprocess använder attribut för att konfigurera utlösaren. C#-skriptet använder i stället en function.json konfigurationsfil enligt beskrivningen i C#-skriptguiden.

EventHubTriggerAttribute Använd för att definiera en utlösare på en händelsehubb som stöder följande egenskaper.

Parametrar beskrivning
EventHubName Namnet på händelsehubben. När händelsehubbens namn också finns i anslutningssträng åsidosätter det värdet den här egenskapen vid körning. Kan refereras i appinställningar, till exempel %eventHubName%
ConsumerGroup En valfri egenskap som anger den konsumentgrupp som används för att prenumerera på händelser i hubben. När den $Default utelämnas används konsumentgruppen.
Anslutning Namnet på en appinställning eller inställningssamling som anger hur du ansluter till Event Hubs. Mer information finns i Anslut ions.

Dekoratörer

Gäller endast för python v2-programmeringsmodellen.

För Python v2-funktioner som definierats med hjälp av en dekoratör, följande egenskaper på cosmos_db_trigger:

Property beskrivning
arg_name Namnet på variabeln som representerar händelseobjektet i funktionskoden.
event_hub_name Namnet på händelsehubben. När händelsehubbens namn också finns i anslutningssträng åsidosätter det värdet den här egenskapen vid körning.
connection Namnet på en appinställning eller inställningssamling som anger hur du ansluter till Event Hubs. Se Anslut ioner.

Information om Python-funktioner som definierats med hjälp av function.json finns i avsnittet Konfiguration .

Kommentarer

I Java Functions-körningsbiblioteket använder du EventHubTrigger-kommentaren, som stöder följande inställningar:

Konfiguration

Gäller endast programmeringsmodellen Python v1.

I följande tabell förklaras de egenskaper som du kan ange för objektet options som skickas app.eventHub() till metoden.

Property beskrivning
eventHubName Namnet på händelsehubben. När händelsehubbens namn också finns i anslutningssträng åsidosätter det värdet den här egenskapen vid körning. Kan refereras via appinställningar%eventHubName%
consumerGroup En valfri egenskap som anger den konsumentgrupp som används för att prenumerera på händelser i hubben. Om den $Default utelämnas används konsumentgruppen.
Kardinalitet Ange till many för att aktivera batchbearbetning. Om det utelämnas eller anges till oneskickas ett enda meddelande till funktionen.
Anslutning Namnet på en appinställning eller inställningssamling som anger hur du ansluter till Event Hubs. Se Anslut ioner.

I följande tabell förklaras de egenskaper för utlösarkonfiguration som du anger i filen function.json , som skiljer sig beroende på körningsversion.

function.json egenskap beskrivning
typ Måste anges till eventHubTrigger. Den här egenskapen anges automatiskt när du skapar utlösaren i Azure-portalen.
riktning Måste anges till in. Den här egenskapen anges automatiskt när du skapar utlösaren i Azure-portalen.
Namn Namnet på variabeln som representerar händelseobjektet i funktionskoden.
eventHubName Namnet på händelsehubben. När händelsehubbens namn också finns i anslutningssträng åsidosätter det värdet den här egenskapen vid körning. Kan refereras via appinställningar%eventHubName%
consumerGroup En valfri egenskap som anger den konsumentgrupp som används för att prenumerera på händelser i hubben. Om den $Default utelämnas används konsumentgruppen.
Kardinalitet Ange till many för att aktivera batchbearbetning. Om det utelämnas eller anges till oneskickas ett enda meddelande till funktionen.
Anslutning Namnet på en appinställning eller inställningssamling som anger hur du ansluter till Event Hubs. Se Anslut ioner.

När du utvecklar lokalt lägger du till dina programinställningar i den local.settings.json filen i Values samlingen.

Användning

Mer information om hur Event Hubs-utlösare och IoT Hub-utlösare skalar finns i Använda händelser med Azure Functions.

Vilken parametertyp som stöds av Event Hubs-utdatabindningen beror på functions-körningsversionen, tilläggspaketversionen och den C#-modalitet som används.

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.

Parametertypen kan vara något av följande:

  • Alla inbyggda Java-typer som int, String, byte[].
  • Null-värden med valfritt.
  • Valfri POJO-typ.

Mer information finns i EventHubTrigger-referensen.

Händelsemetadata

Event Hubs-utlösaren innehåller flera metadataegenskaper. Metadataegenskaper kan användas som en del av bindningsuttryck i andra bindningar eller som parametrar i koden. Egenskaperna kommer från klassen EventData .

Property Type Beskrivning
PartitionContext PartitionContext Instansen PartitionContext .
EnqueuedTimeUtc DateTime Den köade tiden i UTC.
Offset string Förskjutningen av data i förhållande till händelsehubbens partitionsström. Förskjutningen är en markör eller identifierare för en händelse i Event Hubs-strömmen. Identifieraren är unik i en partition av Event Hubs-strömmen.
PartitionKey string Partitionen som händelsedata ska skickas till.
Properties IDictionary<String,Object> Användaregenskaperna för händelsedata.
SequenceNumber Int64 Händelsens logiska sekvensnummer.
SystemProperties IDictionary<String,Object> Systemegenskaperna, inklusive händelsedata.

Se kodexempel som använder dessa egenskaper tidigare i den här artikeln.

anslutningar

Egenskapen connection är en referens till miljökonfigurationen som innehåller namnet på en programinställning som innehåller en anslutningssträng. Du kan hämta den här anslutningssträng genom att välja knappen Anslut ionsinformation för namnområdet. Anslutningssträng måste vara för ett Event Hubs-namnområde, inte själva händelsehubben.

Anslutningssträng måste ha minst läsbehörighet för att aktivera funktionen.

Den här anslutningssträng ska lagras i en programinställning med ett namn som matchar det värde som anges av connection egenskapen för bindningskonfigurationen.

Kommentar

Identitetsbaserade anslutningar stöds inte av IoT Hub-utlösaren. Om du behöver använda hanterade identiteter från slutpunkt till slutpunkt kan du i stället använda IoT Hub-routning för att skicka data till en händelsehubb som du styr. På så sätt kan utgående routning autentiseras med hanterad identitet som händelsen kan läsas från den händelsehubben med hjälp av hanterad identitet.

host.json egenskaper

Filen host.json innehåller inställningar som styr händelsehubbens utlösarbeteende. Mer information om tillgängliga inställningar finns i avsnittet host.json inställningar .

Nästa steg