Azure Event Hubs-utlösare för Azure Functions

  • Artikel

Den här artikeln beskriver hur du arbetar med Azure Event Hubs-utlösare för Azure Functions. Azure Functions stöder utlösar- och utdatabindningar för Event Hubs.

Information om konfiguration och konfigurationsinformation finns i översikten.

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 anger hur appen ska ansluta till Event Hubs. Den kan ange:

Om det konfigurerade värdet både är en exakt matchning för en enskild inställning och en prefixmatchning för andra inställningar används den exakta matchningen.

Connection string

Hämta den här anslutningssträng genom att klicka på knappen Anslut ionsinformation för namnområdet, inte själva händelsehubben. Anslutningssträng måste vara för ett Event Hubs-namnområde, inte själva händelsehubben.

När den används för utlösare måste anslutningssträng ha minst läsbehörighet för att aktivera funktionen. När den används för utdatabindningar måste anslutningssträng ha "skicka" behörighet att skicka meddelanden till händelseströmmen.

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.

Identitetsbaserade anslutningar

Om du använder version 5.x eller senare av tillägget kan du i stället för att använda en anslutningssträng med en hemlighet låta appen använda en Microsoft Entra-identitet. För att göra detta definierar du inställningar under ett vanligt prefix som mappar till connection egenskapen i utlösar- och bindningskonfigurationen.

I det här läget kräver tillägget följande egenskaper:

Property Miljövariabelmall beskrivning Exempelvärde
Fullständigt kvalificerat namnområde <CONNECTION_NAME_PREFIX>__fullyQualifiedNamespace Det fullständigt kvalificerade Event Hubs-namnområdet. myeventhubns.servicebus.windows.net

Ytterligare egenskaper kan anges för att anpassa anslutningen. Se Vanliga egenskaper för identitetsbaserade anslutningar.

Kommentar

När du använder Azure App Configuration eller Key Vault för att ange inställningar för hanterade identitetsanslutningar bör inställningsnamn använda en giltig nyckelavgränsare, till exempel : eller / i stället __ för att säkerställa att namnen matchas korrekt.

Exempel: <CONNECTION_NAME_PREFIX>:fullyQualifiedNamespace

När identitetsbaserade anslutningar finns i Azure Functions-tjänsten använder de en hanterad identitet. Den systemtilldelade identiteten används som standard, även om en användartilldelad identitet kan anges med credential egenskaperna och clientID . Observera att det inte går att konfigurera en användartilldelad identitet med ett resurs-ID. När den körs i andra sammanhang, till exempel lokal utveckling, används utvecklaridentiteten i stället, även om den kan anpassas. Se Lokal utveckling med identitetsbaserade anslutningar.

Bevilja behörighet till identiteten

Den identitet som används måste ha behörighet att utföra de avsedda åtgärderna. För de flesta Azure-tjänster innebär det att du måste tilldela en roll i Azure RBAC med hjälp av antingen inbyggda eller anpassade roller som ger dessa behörigheter.

Viktigt!

Vissa behörigheter kan exponeras av måltjänsten som inte är nödvändiga för alla kontexter. Om möjligt följer du principen om minsta behörighet och beviljar identiteten endast nödvändiga privilegier. Om appen till exempel bara behöver kunna läsa från en datakälla använder du en roll som bara har behörighet att läsa. Det skulle vara olämpligt att tilldela en roll som också tillåter skrivning till tjänsten, eftersom detta skulle vara överdriven behörighet för en läsåtgärd. På samma sätt vill du se till att rolltilldelningen endast är begränsad till de resurser som behöver läsas.

Du måste skapa en rolltilldelning som ger åtkomst till din händelsehubb vid körning. Omfånget för rolltilldelningen kan vara för ett Event Hubs-namnområde eller själva händelsehubben. Hanteringsroller som Ägare räcker inte. I följande tabell visas inbyggda roller som rekommenderas när du använder Event Hubs-tillägget i normal drift. Programmet kan kräva ytterligare behörigheter baserat på den kod du skriver.

Bindningstyp Exempel på inbyggda roller
Utlösare Azure Event Hubs-datamottagare, Azure Event Hubs-dataägare
Utdatabindning Azure Event Hubs Data Sender

host.json inställningar

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

Nästa steg