Azure Event Hubs-eseményindító az Azure Functionshez

  • Cikk

Ez a cikk bemutatja, hogyan használható az Azure Event Hubs-eseményindító az Azure Functionshez. Az Azure Functions támogatja az Event Hubs eseményindító- és kimeneti kötéseit .

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

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 a környezeti konfigurációra mutató hivatkozás, amely meghatározza, hogy az alkalmazásnak hogyan kell csatlakoznia az Event Hubshoz. A következőt határozhatja meg:

Ha a konfigurált érték egy adott beállítás pontos egyezése, a többi beállítás előtagja pedig egyezik, akkor a rendszer a pontos egyezést használja.

Kapcsolati sztring

Ezt a kapcsolati sztring a névtér Csatlakozás ion Information gombjára kattintva szerezheti be, és nem magát az eseményközpontot. A kapcsolati sztring egy Event Hubs-névtérnek kell lennie, nem magának az eseményközpontnak.

Eseményindítók esetén a kapcsolati sztring legalább "olvasási" engedélyekkel kell rendelkeznie a függvény aktiválásához. Kimeneti kötésekhez használva a kapcsolati sztring "küldési" engedéllyel kell rendelkeznie ahhoz, hogy üzeneteket küldjön az eseménystreambe.

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.

Identitásalapú kapcsolatok

Ha a bővítmény 5.x vagy újabb verzióját használja, ahelyett, hogy titkos kapcsolati sztring használ, az alkalmazás Microsoft Entra-identitást használhat. Ehhez meg kell határoznia a beállításokat egy közös előtag alatt, amely leképezi a connection tulajdonságot az eseményindító és a kötés konfigurációjában.

Ebben a módban a bővítményhez a következő tulajdonságok szükségesek:

Tulajdonság Környezeti változó sablonja Leírás Példaérték
Teljes névtér <CONNECTION_NAME_PREFIX>__fullyQualifiedNamespace A teljes mértékben minősített Event Hubs-névtér. myeventhubns.servicebus.windows.net

További tulajdonságok is beállíthatók a kapcsolat testreszabásához. Tekintse meg az identitásalapú kapcsolatok gyakori tulajdonságait.

Feljegyzés

Ha Azure-alkalmazás konfigurációt vagy Key Vaultot használ a felügyelt identitáskapcsolatok beállításainak megadásához, a beállítások neveinek egy érvényes kulcselválasztót kell használniuk, például : a __ helyett, / hogy a nevek megfelelően legyenek feloldva.

Például: <CONNECTION_NAME_PREFIX>:fullyQualifiedNamespace.

Az Azure Functions szolgáltatásban üzemeltetett identitásalapú kapcsolatok felügyelt identitást használnak. A rendszer alapértelmezés szerint a rendszer által hozzárendelt identitást használja, bár a felhasználó által hozzárendelt identitás megadható a credential tulajdonságokkal együtt clientID . Vegye figyelembe, hogy a felhasználó által hozzárendelt identitás erőforrás-azonosítóval való konfigurálása nem támogatott. Ha más környezetekben, például helyi fejlesztésben fut, a rendszer ehelyett a fejlesztői identitást használja, bár ez testre szabható. Lásd: Helyi fejlesztés identitásalapú kapcsolatokkal.

Engedély megadása az identitáshoz

Bármilyen identitást is használ, rendelkeznie kell a kívánt műveletek végrehajtásához szükséges engedélyekkel. A legtöbb Azure-szolgáltatás esetében ez azt jelenti, hogy egy szerepkört kell hozzárendelnie az Azure RBAC-ben beépített vagy egyéni szerepkörökkel, amelyek biztosítják ezeket az engedélyeket.

Fontos

A célszolgáltatás bizonyos engedélyeket közzétehet, amelyek nem minden környezethez szükségesek. Ahol lehetséges, tartsa be a minimális jogosultság elvét, és csak az identitáshoz szükséges jogosultságokat adja meg. Ha például az alkalmazásnak csak adatforrásból kell olvasnia, használjon olyan szerepkört, amely csak olvasási engedéllyel rendelkezik. Nem lenne helyénvaló olyan szerepkört hozzárendelni, amely lehetővé teszi az írást is a szolgáltatáshoz, mivel ez túlzott engedély lenne egy olvasási művelethez. Hasonlóképpen meg szeretné győződni arról, hogy a szerepkör-hozzárendelés csak az elolvasandó erőforrásokra terjed ki.

Létre kell hoznia egy szerepkör-hozzárendelést, amely futásidőben hozzáférést biztosít az eseményközponthoz. A szerepkör-hozzárendelés hatóköre lehet egy Event Hubs-névtér vagy maga az eseményközpont. A tulajdonoshoz hasonló felügyeleti szerepkörök nem elegendőek. Az alábbi táblázat olyan beépített szerepköröket mutat be, amelyek az Event Hubs-bővítmény normál működésben való használatakor ajánlottak. Előfordulhat, hogy az alkalmazás további engedélyeket igényel az Ön által írt kód alapján.

Kötés típusa Példa beépített szerepkörökre
Eseményindító Azure Event Hubs-adatátvevő, Azure Event Hubs-adattulajdonos
Kimeneti kötés Azure Event Hubs-adatküldő

host.json beállítások

A host.json fájl olyan beállításokat tartalmaz, amelyek szabályozzák az Event Hubs eseményindítók 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