Azure IoT Hub-eseményindító az Azure Functionshez

  • Cikk

Ez a cikk bemutatja, hogyan használhatók az Azure Functions-kötések az IoT Hubhoz. Az IoT Hub támogatása az Azure Event Hubs-kötésen alapul.

A beállítással és a konfigurációval kapcsolatos információkért tekintse meg az áttekintést.

Fontos

Bár a következő kódminták az Event Hub API-t használják, a megadott szintaxis az IoT Hub-függvényekre vonatkozik.

A függvény-eseményindítóval válaszolhat egy eseményközpont eseményfolyamának küldött eseményre. Az eseményindító beállításához olvasási hozzáféréssel kell rendelkeznie a mögöttes eseményközponthoz. A függvény aktiválásakor a függvénynek átadott üzenet sztringként lesz begépelve.

Az Event Hubs skálázási döntései a használati és prémium csomagok esetében célalapú skálázáson keresztül érhetők el. További információ: Célalapú skálázás.

További információ arról, hogy az Azure Functions hogyan reagál az eseményközpont eseményfolyamára eseményindítókkal küldött eseményekre: Az Event Hubs integrálása kiszolgáló nélküli függvényekkel az Azure-ban.

Fontos

Ez a cikk lapokat használ a Node.js programozási modell több verziójának támogatásához. A v4-modell általánosan elérhető, és úgy lett kialakítva, hogy rugalmasabb és intuitívabb felhasználói élményt nyújtson JavaScript- és TypeScript-fejlesztők számára. A v4-modell működésével kapcsolatos további információkért tekintse meg az Azure Functions Node.js fejlesztői útmutatóját. A v3 és a v4 közötti különbségekről a migrálási útmutatóban olvashat bővebben.

Az Azure Functions két Python-programozási modellt támogat. A kötések definiálásának módja a választott programozási modelltől függ.

A Python v2 programozási modell lehetővé teszi, hogy a kötéseket dekorátorokkal definiálja közvetlenül a Python-függvénykódban. További információt a Python fejlesztői útmutatójában talál.

Ez a cikk mindkét programozási modellt támogatja.

Példa

Az alábbi példa egy eseményközpont alapján aktivált C# függvényt mutat be, ahol a bemeneti üzenet sztringje a naplókba van írva:

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

Az alábbi példa egy Event Hubs-eseményindító TypeScript-függvényt mutat be. A függvény beolvassa az esemény metaadatait , és naplózza az üzenetet.

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

Ha eseményeket szeretne fogadni egy kötegben, állítsa a cardinality következő példában látható módon many.

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

Az alábbi példa egy Event Hubs-trigger JavaScript-függvényt mutat be. A függvény beolvassa az esemény metaadatait , és naplózza az üzenetet.

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

Ha eseményeket szeretne fogadni egy kötegben, állítsa a cardinality következő példában látható módon many.

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

A PowerShell-kód a következő:

param($eventHubMessages, $TriggerMetadata)

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

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

Az alábbi példa egy Event Hubs-eseményindító-kötést és egy Python-függvényt mutat be, amely a kötést használja. A függvény beolvassa az esemény metaadatait , és naplózza az üzenetet. A példa attól függ, hogy a v1 vagy v2 Python programozási modellt használja-e.

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

Az alábbi példa egy Event Hubs-eseményindító-kötést mutat be, amely naplózza az Event Hubs-eseményindító üzenettörzsét.

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

A Java-függvények futtatókörnyezeti kódtárában használja a széljegyzetet azon EventHubTrigger paramétereken, amelyek értéke az eseményközpontból származik. Az ilyen széljegyzeteket tartalmazó paraméterek miatt a függvény egy esemény érkezésekor fut. Ez a széljegyzet natív Java-típusokkal, POJ-kkal vagy null értékű értékekkel használható a használatával Optional<T>.

Az alábbi példa az esemény további bevezető lehetőségeinek széles körű használatát SystemProperties és egyéb kötési lehetőségeket mutatja be, valamint egy jól formázott BlobOutput , hierarchikus Dátum elérési utat biztosít.

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

Attribútumok

A folyamaton belüli és az izolált feldolgozói folyamat C# kódtárai attribútummal konfigurálják az eseményindítót. A C#-szkript ehelyett egy function.json konfigurációs fájlt használ a C#-szkriptelési útmutatóban leírtak szerint.

EventHubTriggerAttribute Az eseményközpontban az alábbi tulajdonságokat támogató eseményindítót definiálhat.

Paraméterek Leírás
EventHubName Az eseményközpont neve. Ha az eseményközpont neve is szerepel a kapcsolati sztring, ez az érték futásidőben felülbírálja ezt a tulajdonságot. Az alkalmazásbeállításokban, például a %eventHubName%
ConsumerGroup Nem kötelező tulajdonság, amely beállítja a központban lévő eseményekre való feliratkozáshoz használt fogyasztói csoportot . Ha nincs megadva, a rendszer a $Default fogyasztói csoportot használja.
Kapcsolat Egy alkalmazásbeállítás vagy beállításgyűjtemény neve, amely meghatározza, hogyan csatlakozhat az Event Hubshoz. További információ: Csatlakozás.

Dekorátorok

Csak a Python v2 programozási modellre vonatkozik.

A dekoratőrrel definiált Python v2-függvények esetében a következő tulajdonságok a cosmos_db_triggerkövetkezők:

Tulajdonság Leírás
arg_name Annak a változónak a neve, amely a függvénykód eseményelemét jelöli.
event_hub_name Az eseményközpont neve. Ha az eseményközpont neve is szerepel a kapcsolati sztring, ez az érték futásidőben felülbírálja ezt a tulajdonságot.
connection Egy alkalmazásbeállítás vagy beállításgyűjtemény neve, amely meghatározza, hogyan csatlakozhat az Event Hubshoz. Lásd: Csatlakozás ions.

A function.json használatával definiált Python-függvények esetében lásd a Konfiguráció szakaszt.

Jegyzetek

A Java-függvények futtatókörnyezeti kódtárában használja az EventHubTrigger jegyzetet, amely a következő beállításokat támogatja:

Konfiguráció

Csak a Python v1 programozási modellre vonatkozik.

Az alábbi táblázat a metódusnak app.eventHub() átadott objektumon options beállítható tulajdonságokat ismerteti.

Tulajdonság Leírás
eventHubName Az eseményközpont neve. Ha az eseményközpont neve is szerepel a kapcsolati sztring, ez az érték futásidőben felülbírálja ezt a tulajdonságot. Az alkalmazásbeállításokon keresztül hivatkozhat gombra%eventHubName%
consumerGroup Nem kötelező tulajdonság, amely beállítja a központban lévő eseményekre való feliratkozáshoz használt fogyasztói csoportot . Ha nincs megadva, a rendszer a $Default fogyasztói csoportot használja.
Számossága many A kötegelés engedélyezéséhez állítsa be. Ha nincs megadva vagy be van állítva one, a függvény egyetlen üzenetet ad át.
Kapcsolat Egy alkalmazásbeállítás vagy beállításgyűjtemény neve, amely meghatározza, hogyan csatlakozhat az Event Hubshoz. Lásd: Csatlakozás ions.

Az alábbi táblázat a function.json fájlban beállított triggerkonfigurációs tulajdonságokat ismerteti, amelyek futásidejű verziónként eltérőek.

function.json tulajdonság Leírás
type A beállításnak a eventHubTriggerkövetkezőnek kell lennie: . Ez a tulajdonság automatikusan be van állítva, amikor létrehozza az eseményindítót az Azure Portalon.
direction A beállításnak a inkövetkezőnek kell lennie: . Ez a tulajdonság automatikusan be van állítva, amikor létrehozza az eseményindítót az Azure Portalon.
név Annak a változónak a neve, amely a függvénykód eseményelemét jelöli.
eventHubName Az eseményközpont neve. Ha az eseményközpont neve is szerepel a kapcsolati sztring, ez az érték futásidőben felülbírálja ezt a tulajdonságot. Az alkalmazásbeállításokon keresztül hivatkozhat gombra%eventHubName%
consumerGroup Nem kötelező tulajdonság, amely beállítja a központban lévő eseményekre való feliratkozáshoz használt fogyasztói csoportot . Ha nincs megadva, a rendszer a $Default fogyasztói csoportot használja.
Számossága many A kötegelés engedélyezéséhez állítsa be. Ha nincs megadva vagy be van állítva one, a függvény egyetlen üzenetet ad át.
Kapcsolat Egy alkalmazásbeállítás vagy beállításgyűjtemény neve, amely meghatározza, hogyan csatlakozhat az Event Hubshoz. Lásd: Csatlakozás ions.

Helyi fejlesztéskor adja hozzá az alkalmazásbeállításokat a gyűjtemény local.settings.json fájljáhozValues.

Használat

Az Event Hubs eseményindítóinak és az IoT Hub-eseményindítók méretezésének további megismeréséhez tekintse meg az Események felhasználása az Azure Functions szolgáltatással című témakört.

Az Event Hubs kimeneti kötés által támogatott paramétertípus a Functions futtatókörnyezet verziójától, a bővítménycsomag verziójától és a használt C# módtól függ.

Ha azt szeretné, hogy a függvény egyetlen eseményt dolgoz fel, az Event Hubs-eseményindító a következő típusokhoz kapcsolódhat:

Típus Leírás
string Az esemény sztringként. Akkor használja, ha az esemény egyszerű szöveg.
byte[] Az esemény bájtja.
JSON szerializálható típusok Ha egy esemény JSON-adatokat tartalmaz, a Functions megpróbálja deszerializálni a JSON-adatokat egy egyszerű régi CLR-objektum (POCO) típusba.
Azure.Messaging.EventHubs.EventData1 Az eseményobjektum.
Ha az Event Hubs SDK-k bármely régebbi verziójából migrál, vegye figyelembe, hogy ez a verzió nem támogatja az örökölt Body típust az EventBody javára.

Ha azt szeretné, hogy a függvény feldolgozza az események kötegét, az Event Hubs-eseményindító a következő típusokhoz kapcsolódhat:

Típus Leírás
string[] A kötegből származó események tömbje sztringként. Minden bejegyzés egy eseményt jelöl.
EventData[]1 A kötegből származó események tömbje az Azure.Messaging.EventHubs.EventData példányaként. Minden bejegyzés egy eseményt jelöl.
T[] ahol T egy JSON szerializálható típus1 A kötegből származó események tömbje egyéni POCO-típus példányaként. Minden bejegyzés egy eseményt jelöl.

1 Ezeknek a típusoknak a használatához hivatkoznia kell a Microsoft.Azure.Functions.Worker.Extensions.EventHubs 5.5.0-s vagy újabb verziójára, valamint az SDK-típuskötések gyakori függőségeire.

A paraméter típusa a következők egyike lehet:

  • Bármilyen natív Java-típus, például int, String, byte[].
  • Null értékű értékek opcionális használatával.
  • Bármilyen POJO-típus.

További információkért tekintse meg az EventHubTrigger referenciáját.

Esemény metaadatai

Az Event Hubs-eseményindító számos metaadat-tulajdonságot biztosít. A metaadat-tulajdonságok a kötési kifejezések részeként használhatók más kötésekben vagy a kód paramétereiként. A tulajdonságok az EventData osztályból származnak.

Tulajdonság Típus Leírás
PartitionContext PartitionContext A PartitionContext példány.
EnqueuedTimeUtc DateTime Az enqueued time in UTC.
Offset string Az adatok eltolása az eseményközpont partíciófolyamához képest. Az eltolás egy esemény jelölője vagy azonosítója az Event Hubs-adatfolyamban. Az azonosító egyedi az Event Hubs-stream partíción belül.
PartitionKey string Az a partíció, amelyre az eseményadatokat el kell küldeni.
Properties IDictionary<String,Object> Az eseményadatok felhasználói tulajdonságai.
SequenceNumber Int64 Az esemény logikai sorszáma.
SystemProperties IDictionary<String,Object> A rendszer tulajdonságai, beleértve az eseményadatokat is.

Tekintse meg a jelen cikk korábbi, ezeket a tulajdonságokat használó kódokat .

Kapcsolatok

A connection tulajdonság egy olyan környezeti konfigurációra mutató hivatkozás, amely egy kapcsolati sztring tartalmazó alkalmazásbeállítás nevét tartalmazza. Ezt a kapcsolati sztring a névtér Csatlakozás ion Information gombjának kiválasztásával szerezheti be. A kapcsolati sztring egy Event Hubs-névtérnek kell lennie, nem magának az eseményközpontnak.

A kapcsolati sztring legalább "olvasási" engedéllyel kell rendelkeznie a függvény aktiválásához.

Ezt a kapcsolati sztring a kötéskonfiguráció tulajdonsága által connection megadott értéknek megfelelő névvel rendelkező alkalmazásbeállításban kell tárolni.

Feljegyzés

Az identitásalapú kapcsolatokat az IoT Hub-eseményindító nem támogatja. Ha a felügyelt identitásokat a végpontok között kell használnia, az IoT Hub Routing használatával adatokat küldhet egy ön által felügyelt eseményközpontba. Ily módon a kimenő útválasztás felügyelt identitással hitelesíthető, amelyről az esemény felügyelt identitással olvasható.

host.json tulajdonságok

A host.json fájl olyan beállításokat tartalmaz, amelyek szabályozzák az Eseményközpont eseményindítóinak viselkedését. Az elérhető beállításokkal kapcsolatos részletekért tekintse meg a host.json beállítások szakaszát.

Következő lépések