Azure Event Hubs-trigger voor Azure Functions

  • Artikel

In dit artikel wordt uitgelegd hoe u kunt werken met azure Event Hubs-triggers voor Azure Functions. Azure Functions ondersteunt trigger- en uitvoerbindingen voor Event Hubs.

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

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 die aangeeft hoe de app verbinding moet maken met Event Hubs. Het kan het volgende opgeven:

Als de geconfigureerde waarde zowel een exacte overeenkomst is voor één instelling als een voorvoegselovereenkomst voor andere instellingen, wordt de exacte overeenkomst gebruikt.

Connection string

Verkrijg deze verbindingsreeks door te klikken op de knop Verbinding maken ion Information voor de naamruimte, niet op de Event Hub zelf. De verbindingsreeks moet voor een Event Hubs-naamruimte zijn, niet voor de Event Hub zelf.

Wanneer de verbindingsreeks wordt gebruikt voor triggers, moet de verbindingsreeks ten minste leesmachtigingen hebben om de functie te activeren. Wanneer de verbindingsreeks wordt gebruikt voor uitvoerbindingen, moet de verbindingsreeks machtigingen voor het verzenden van berichten naar de gebeurtenisstroom hebben.

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.

Op identiteit gebaseerde verbindingen

Als u versie 5.x of hoger van de extensie gebruikt, in plaats van een verbindingsreeks met een geheim te gebruiken, kunt u de app een Microsoft Entra-identiteit laten gebruiken. Hiervoor definieert u instellingen onder een gemeenschappelijk voorvoegsel dat wordt toegewezen aan de connection eigenschap in de trigger- en bindingsconfiguratie.

In deze modus vereist de extensie de volgende eigenschappen:

Eigenschappen Sjabloon voor omgevingsvariabele Beschrijving Voorbeeldwaarde
Volledig gekwalificeerde naamruimte <CONNECTION_NAME_PREFIX>__fullyQualifiedNamespace De volledig gekwalificeerde Event Hubs-naamruimte. myeventhubns.servicebus.windows.net

Er kunnen extra eigenschappen worden ingesteld om de verbinding aan te passen. Zie Algemene eigenschappen voor op identiteit gebaseerde verbindingen.

Notitie

Wanneer u Azure-app Configuratie of Key Vault gebruikt om instellingen voor beheerde identiteitverbindingen te bieden, moeten instellingsnamen een geldig sleutelscheidingsteken gebruiken, zoals : of / in plaats van de __ sleutelkluis om ervoor te zorgen dat namen correct worden omgezet.

Bijvoorbeeld: <CONNECTION_NAME_PREFIX>:fullyQualifiedNamespace.

Wanneer deze worden gehost in de Azure Functions-service, maken identiteitsverbindingen gebruik van een beheerde identiteit. De door het systeem toegewezen identiteit wordt standaard gebruikt, hoewel een door de gebruiker toegewezen identiteit kan worden opgegeven met de credential en clientID eigenschappen. Houd er rekening mee dat het configureren van een door de gebruiker toegewezen identiteit met een resource-id niet wordt ondersteund. Wanneer uw ontwikkelaarsidentiteit wordt uitgevoerd in andere contexten, zoals lokale ontwikkeling, wordt in plaats daarvan uw ontwikkelaarsidentiteit gebruikt, hoewel dit kan worden aangepast. Zie Lokale ontwikkeling met op identiteit gebaseerde verbindingen.

Toestemming verlenen aan de identiteit

Elke identiteit die wordt gebruikt, moet machtigingen hebben om de beoogde acties uit te voeren. Voor de meeste Azure-services betekent dit dat u een rol in Azure RBAC moet toewijzen met behulp van ingebouwde of aangepaste rollen die deze machtigingen bieden.

Belangrijk

Sommige machtigingen worden mogelijk weergegeven door de doelservice die niet nodig is voor alle contexten. Waar mogelijk moet u zich houden aan het principe van minimale bevoegdheid, waarbij de identiteit alleen vereiste bevoegdheden verleent. Als de app bijvoorbeeld alleen uit een gegevensbron moet kunnen lezen, gebruikt u een rol die alleen gemachtigd is om te lezen. Het zou ongepast zijn om een rol toe te wijzen die ook schrijfbewerkingen naar die service toestaat, omdat dit overmatige machtigingen zou zijn voor een leesbewerking. Op dezelfde manier wilt u ervoor zorgen dat de roltoewijzing alleen is afgestemd op de resources die moeten worden gelezen.

U moet een roltoewijzing maken die tijdens runtime toegang biedt tot uw Event Hub. Het bereik van de roltoewijzing kan zijn voor een Event Hubs-naamruimte of de Event Hub zelf. Beheerrollen zoals Eigenaar zijn niet voldoende. In de volgende tabel ziet u ingebouwde rollen die worden aanbevolen bij het gebruik van de Event Hubs-extensie in normale werking. Uw toepassing vereist mogelijk extra machtigingen op basis van de code die u schrijft.

Bindingstype Voorbeeld van ingebouwde rollen
Trigger Azure Event Hubs-gegevensontvanger, Azure Event Hubs-gegevenseigenaar
Uitvoerbinding Azure Event Hubs-gegevenszender

host.json-instellingen

Het host.json-bestand bevat instellingen die het gedrag van Event Hubs-triggers regelen. Zie de sectie host.json instellingen voor meer informatie over beschikbare instellingen.

Volgende stappen