Azure Event Hubs trigger voor Azure Functions

Artikel
05/13/2021
13 minuten om te lezen

In dit artikel wordt uitgelegd hoe u kunt werken met de Azure Event hubs -trigger voor Azure functions. Azure Functions ondersteunt trigger-en uitvoer bindingen voor Event hubs.

Zie het overzichtvoor meer informatie over de installatie-en configuratie 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.

Schalen

Elk exemplaar van een door een gebeurtenis geactiveerde functie wordt ondersteund door één EventProcessorHost-exemplaar. De trigger (verzorgd door Event Hubs) zorgt ervoor dat slechts één EventProcessorHost-exemplaar een lease kan krijgen op een bepaalde partitie.

Denk bijvoorbeeld aan de volgende Event Hub:

10 partities
1.000 gebeurtenissen, gelijkmatig verdeeld over alle partities, met 100 berichten in elke partitie

Wanneer uw functie voor het eerst wordt ingeschakeld, is er slechts één exemplaar van de functie. We noemen het eerste functie-exemplaar Function_0. De Function_0-functie heeft één exemplaar van EventProcessorHost dat een lease heeft op alle tien partities. Dit exemplaar leest gebeurtenissen van partities 0-9. Vanaf dit punt gebeurt een van de volgende dingen:

Er zijn geen nieuwe functie-exemplaren nodig: Function_0 kan alle 1.000 gebeurtenissen verwerken voordat de schaallogica van Functions in werking treedt. In dit geval worden alle 1.000 berichten verwerkt door Function_0.
Er wordt een extra functie-exemplaar toegevoegd: Als de schaallogica van Functions vaststelt dat Function_0 meer berichten heeft dan deze kan verwerken, wordt er een nieuw functie-app-exemplaar (Function_1) gemaakt. Deze nieuwe functie heeft ook een gekoppeld exemplaar van EventProcessorHost. Als de onderliggende Event Hubs detecteren dat een nieuw host-exemplaar berichten probeert te lezen, worden de partities over de host-exemplaren verdeeld. Partities 0-4 kunnen bijvoorbeeld worden toegewezen aan Function_0, en partities 5-9 aan Function_1.
Er worden nog N functie-exemplaren toegevoegd: Als de schaallogica van Functions vaststelt dat zowel Function_0 als Function_1 meer berichten hebben dan ze kunnen verwerken, worden er nieuwe Functions_N functie-app-exemplaren gemaakt. Er worden apps gemaakt tot het punt waarop N groter is dan het aantal event hub-partities. In ons voorbeeld verdeelt Event Hubs de partities opnieuw, in dit geval over de exemplaren Function_0...Functions_9.

Wanneer er wordt geschaald, is N exemplaren een getal dat groter is dan het aantal event hub-partities. Dit patroon wordt gebruikt om ervoor te zorgen dat er EventProcessorHost-exemplaren beschikbaar zijn voor het verkrijgen van vergrendelingen op partities wanneer deze beschikbaar worden vanuit andere exemplaren. Er worden alleen kosten in rekening gebracht voor de resources die worden gebruikt wanneer het functie-exemplaar wordt uitgevoerd. Met andere woorden, er worden geen kosten in rekening gebracht voor deze overinrichting.

Wanneer de uitvoering van alle functies is voltooid (met of zonder fouten), worden controlepunten toegevoegd aan het gekoppelde opslagaccount. Wanneer het toevoegen van controlepunten slaagt, worden alle 1.000 berichten nooit meer opgehaald.

In het volgende voorbeeld ziet u een C#-functie die de berichttekst van de event hub-trigger registreert.

[FunctionName("EventHubTriggerCSharp")]
public static void Run([EventHubTrigger("samples-workitems", Connection = "EventHubConnectionAppSetting")] string myEventHubMessage, ILogger log)
{
    log.LogInformation($"C# function triggered to process a message: {myEventHubMessage}");
}

Als u toegang wilt krijgen tot gebeurtenismetagegevens in functiecode, bindt u aan een EventData-object (hiervoor is een using-instructie vereist voor Microsoft.Azure.EventHubs). U kunt ook toegang krijgen tot dezelfde eigenschappen met behulp van bindingsexpressies in de methodehandtekening. In het volgende voorbeeld ziet u beide manieren om dezelfde gegevens op te halen:

[FunctionName("EventHubTriggerCSharp")]
public static void Run(
    [EventHubTrigger("samples-workitems", Connection = "EventHubConnectionAppSetting")] EventData myEventHubMessage,
    DateTime enqueuedTimeUtc,
    Int64 sequenceNumber,
    string offset,
    ILogger log)
{
    log.LogInformation($"Event: {Encoding.UTF8.GetString(myEventHubMessage.Body)}");
    // Metadata accessed by binding to EventData
    log.LogInformation($"EnqueuedTimeUtc={myEventHubMessage.SystemProperties.EnqueuedTimeUtc}");
    log.LogInformation($"SequenceNumber={myEventHubMessage.SystemProperties.SequenceNumber}");
    log.LogInformation($"Offset={myEventHubMessage.SystemProperties.Offset}");
    // Metadata accessed by using binding expressions in method parameters
    log.LogInformation($"EnqueuedTimeUtc={enqueuedTimeUtc}");
    log.LogInformation($"SequenceNumber={sequenceNumber}");
    log.LogInformation($"Offset={offset}");
}

Als u gebeurtenissen in een batch wilt ontvangen, maakt u string of EventData een matrix.

Notitie

Wanneer u een batch ontvangt, kunt u niet binden aan methodeparameters zoals in het bovenstaande voorbeeld met DateTime enqueuedTimeUtc en moet u deze ontvangen van elk EventData-object

[FunctionName("EventHubTriggerCSharp")]
public static void Run([EventHubTrigger("samples-workitems", Connection = "EventHubConnectionAppSetting")] EventData[] eventHubMessages, ILogger log)
{
    foreach (var message in eventHubMessages)
    {
        log.LogInformation($"C# function triggered to process a message: {Encoding.UTF8.GetString(message.Body)}");
        log.LogInformation($"EnqueuedTimeUtc={message.SystemProperties.EnqueuedTimeUtc}");
    }
}

In het volgende voorbeeld ziet u een event hub-trigger-binding in een function.json-bestand en een C# Script-functie die gebruikmaakt van de binding. De functie registreert de berichttekst van de event hub-trigger.

In de volgende voorbeelden ziet u Event Hubs die gegevens binden in het bestand function.json.

Versie 2.x en hoger

{
  "type": "eventHubTrigger",
  "name": "myEventHubMessage",
  "direction": "in",
  "eventHubName": "MyEventHub",
  "connection": "myEventHubReadConnectionAppSetting"
}

Versie 1.x

{
  "type": "eventHubTrigger",
  "name": "myEventHubMessage",
  "direction": "in",
  "path": "MyEventHub",
  "connection": "myEventHubReadConnectionAppSetting"
}

Dit is de C# Script-code:

using System;

public static void Run(string myEventHubMessage, TraceWriter log)
{
    log.Info($"C# function triggered to process a message: {myEventHubMessage}");
}

#r "Microsoft.Azure.EventHubs"

using System.Text;
using System;
using Microsoft.ServiceBus.Messaging;
using Microsoft.Azure.EventHubs;

public static void Run(EventData myEventHubMessage,
    DateTime enqueuedTimeUtc,
    Int64 sequenceNumber,
    string offset,
    TraceWriter log)
{
    log.Info($"Event: {Encoding.UTF8.GetString(myEventHubMessage.Body)}");
    log.Info($"EnqueuedTimeUtc={myEventHubMessage.SystemProperties.EnqueuedTimeUtc}");
    log.Info($"SequenceNumber={myEventHubMessage.SystemProperties.SequenceNumber}");
    log.Info($"Offset={myEventHubMessage.SystemProperties.Offset}");

    // Metadata accessed by using binding expressions
    log.Info($"EnqueuedTimeUtc={enqueuedTimeUtc}");
    log.Info($"SequenceNumber={sequenceNumber}");
    log.Info($"Offset={offset}");
}

Als u gebeurtenissen in een batch wilt ontvangen, maakt u string of EventData een matrix:

public static void Run(string[] eventHubMessages, TraceWriter log)
{
    foreach (var message in eventHubMessages)
    {
        log.Info($"C# function triggered to process a message: {message}");
    }
}

In het volgende voorbeeld ziet u een event hub-trigger-binding in een function.json-bestand en een JavaScript-functie die gebruikmaakt van de binding. De functie leest gebeurtenismetagegevens en registreert het bericht.

In de volgende voorbeelden ziet u Event Hubs die gegevens binden in het bestand function.json.

Versie 2.x en hoger

{
  "type": "eventHubTrigger",
  "name": "myEventHubMessage",
  "direction": "in",
  "eventHubName": "MyEventHub",
  "connection": "myEventHubReadConnectionAppSetting"
}

Versie 1.x

{
  "type": "eventHubTrigger",
  "name": "myEventHubMessage",
  "direction": "in",
  "path": "MyEventHub",
  "connection": "myEventHubReadConnectionAppSetting"
}

Dit is de JavaScript-code:

module.exports = function (context, myEventHubMessage) {
    context.log('Function triggered to process a message: ', myEventHubMessage);
    context.log('EnqueuedTimeUtc =', context.bindingData.enqueuedTimeUtc);
    context.log('SequenceNumber =', context.bindingData.sequenceNumber);
    context.log('Offset =', context.bindingData.offset);

    context.done();
};

Als u gebeurtenissen in een batch wilt ontvangen, stelt u cardinality in op many in het bestand function.json, zoals in de volgende voorbeelden.

Versie 2.x en hoger

{
  "type": "eventHubTrigger",
  "name": "eventHubMessages",
  "direction": "in",
  "eventHubName": "MyEventHub",
  "cardinality": "many",
  "connection": "myEventHubReadConnectionAppSetting"
}

Versie 1.x

{
  "type": "eventHubTrigger",
  "name": "eventHubMessages",
  "direction": "in",
  "path": "MyEventHub",
  "cardinality": "many",
  "connection": "myEventHubReadConnectionAppSetting"
}

Dit is de JavaScript-code:

module.exports = function (context, eventHubMessages) {
    context.log(`JavaScript eventhub trigger function called for message array ${eventHubMessages}`);

    eventHubMessages.forEach((message, index) => {
        context.log(`Processed message ${message}`);
        context.log(`EnqueuedTimeUtc = ${context.bindingData.enqueuedTimeUtcArray[index]}`);
        context.log(`SequenceNumber = ${context.bindingData.sequenceNumberArray[index]}`);
        context.log(`Offset = ${context.bindingData.offsetArray[index]}`);
    });

    context.done();
};

In het volgende voorbeeld ziet u een event hub-trigger-binding in een function.json-bestand en een Python-functie die gebruikmaakt van de binding. De functie leest gebeurtenismetagegevens en registreert het bericht.

In de volgende voorbeelden ziet u Event Hubs die gegevens binden in het bestand function.json.

{
  "type": "eventHubTrigger",
  "name": "event",
  "direction": "in",
  "eventHubName": "MyEventHub",
  "connection": "myEventHubReadConnectionAppSetting"
}

Dit is de Python-code:

import logging
import azure.functions as func


def main(event: func.EventHubEvent):
    logging.info(f'Function triggered to process a message: {event.get_body().decode()}')
    logging.info(f'  EnqueuedTimeUtc = {event.enqueued_time}')
    logging.info(f'  SequenceNumber = {event.sequence_number}')
    logging.info(f'  Offset = {event.offset}')

    # Metadata
    for key in event.metadata:
        logging.info(f'Metadata: {key} = {event.metadata[key]}')

In het volgende voorbeeld ziet u een Event Hub-trigger-binding die de berichttekst van de Event Hub-trigger registreert.

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

Gebruik in de Java-functies-runtimebibliotheek de EventHubTrigger-aantekening voor parameters waarvan de waarde afkomstig is van 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>.

Kenmerken en aantekeningen

Gebruik in C#-klassebibliotheken het kenmerk EventHubTriggerAttribute.

De constructor van het kenmerk neemt de naam van de event hub, de naam van de consumentengroep en de naam van een app-instelling die de verbindingsreeks bevat. Zie de triggerconfiguratiesectie voor meer informatie over deze instellingen. Hier volgt een voorbeeld van een EventHubTriggerAttribute-kenmerk:

[FunctionName("EventHubTriggerCSharp")]
public static void Run([EventHubTrigger("samples-workitems", Connection = "EventHubConnectionAppSetting")] string myEventHubMessage, ILogger log)
{
    ...
}

Zie Trigger: C#-voorbeeldvoor een volledig voorbeeld.

Configuratie

De volgende tabel bevat informatie over de bindingsconfiguratie-eigenschappen die u instelt in het bestand function.json en het kenmerk EventHubTrigger.

function.json-eigenschap	Kenmerkeigenschap	Beschrijving
type	N.v.t.	Moet worden ingesteld op `eventHubTrigger`. Deze eigenschap wordt automatisch ingesteld wanneer u de trigger maakt in de Azure-portal.
direction	N.v.t.	Moet worden ingesteld op `in`. Deze eigenschap wordt automatisch ingesteld wanneer u de trigger maakt in de Azure-portal.
name	N.v.t.	De naam van de variabele die het gebeurtenisitem in functiecode vertegenwoordigt.
path	EventHubName	Alleen Functions 1.x. De naam van de event hub. Wanneer de event hub-naam ook aanwezig is in de verbindingsreeks, overschrijft die waarde deze eigenschap tijdens runtime.
eventHubName	EventHubName	Functions 2.x en hoger. De naam van de event hub. Wanneer de event hub-naam ook aanwezig is in de verbindingsreeks, overschrijft die waarde deze eigenschap tijdens runtime. Hiernaar kan worden verwezen via app-instellingen `%eventHubName%`
consumerGroup	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	N.v.t.	Wordt gebruikt voor alle niet- C#-talen. 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. In C# wordt deze eigenschap automatisch toegewezen wanneer de trigger een matrix voor het type heeft.
connection	Verbinding	De naam van een app-instelling of instellingsverzameling die aangeeft hoe verbinding moet worden Event Hubs. Zie Verbindingen.

Wanneer u lokaal ontwikkelt, gaan app-instellingen in het bestand local.settings.json.

Verbindingen

De connection eigenschap is een verwijzing naar de omgevingsconfiguratie die aangeeft hoe de app verbinding moet maken met Event Hubs. Er kan het volgende worden opgegeven:

De naam van een toepassingsinstelling met een connection string
De naam van een gedeeld voorvoegsel voor meerdere toepassingsinstellingen, samen met het definiëren van een verbinding op basis van identiteit.

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

Verbindingsreeks

U kunt deze connection string door te klikken op de knop Verbindingsgegevens voor de naamruimte, niet op de Event Hub zelf. De connection string moet voor een Event Hubs zijn, niet voor de Event Hub zelf.

Bij gebruik voor triggers moet de connection string ten minste leesmachtigingen hebben om de functie te activeren. Bij gebruik voor uitvoerbindingen moet de connection string 'verzenden'-machtigingen hebben om berichten naar de gebeurtenisstroom te verzenden.

Deze connection string moeten 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 ofhoger van de extensie gebruikt in plaats van een connection string met een geheim, kunt u de app een Azure Active Directory laten gebruiken. Hiervoor definieert u instellingen onder een gemeenschappelijk voorvoegsel dat wordt toe te staan aan de eigenschap in de connection trigger en bindingsconfiguratie.

In deze modus vereist de extensie de volgende eigenschappen:

Eigenschap	Sjabloon voor omgevingsvariabelen	Description	Voorbeeldwaarde
Fully Qualified Namespace	`<CONNECTION_NAME_PREFIX>__fullyQualifiedNamespace`	De volledig gekwalificeerde Event Hubs naamruimte.	<event_hubs_namespace>.servicebus.windows.net

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

Wanneer deze worden gehost in Azure Functions-service, gebruiken identiteitsgebaseerde verbindingen 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 eigenschappen clientID en . Wanneer deze wordt uitgevoerd in andere contexten, zoals lokale ontwikkeling, wordt in plaats daarvan uw identiteit van de ontwikkelaar gebruikt, hoewel dit kan worden aangepast. Zie Local development with identity-based connections(Lokale ontwikkeling met op identiteit gebaseerde verbindingen).

Machtiging verlenen aan de identiteit

Elke identiteit die wordt gebruikt, moet machtigingen hebben om de beoogde acties uit te voeren. U moet een rol toewijzen in Azure RBACmet behulp van ingebouwde of aangepaste rollen die deze machtigingen bieden.

Belangrijk

Sommige machtigingen kunnen worden blootgesteld door de doelservice die niet nodig zijn voor alle contexten. Waar mogelijk moet u zich houden aan het principe van de minste bevoegdheden en de identiteit alleen bevoegdheden verlenen. Als de app bijvoorbeeld alleen gegevens uit een gegevensbron hoeft te kunnen lezen, gebruikt u een rol die alleen machtigingen heeft om te lezen. Het zou ongepast zijn om een rol toe te wijzen waarmee ook naar die service kan worden geschreven, omdat dit overmatige machtigingen zou zijn voor een leesbewerking. Op dezelfde manier wilt u er zeker van zijn dat de roltoewijzing alleen wordt beperkt tot 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 moet voor een Event Hubs zijn, niet de Event Hub zelf. Beheerrollen zoals Eigenaar zijn niet voldoende. In de volgende tabel ziet u ingebouwde rollen die worden aanbevolen wanneer u de extensie Event Hubs normaal gebruikt. Uw toepassing heeft mogelijk aanvullende machtigingen nodig op basis van de code die u schrijft.

Bindingstype	Voorbeeld van ingebouwde rollen
Trigger	[Azure Event Hubs gegevensontvanger], Azure Event Hubs eigenaar van gegevens
Uitvoerbinding	Azure Event Hubs Afzender van gegevens

Gebruik

Standaard

U kunt de volgende parametertypen gebruiken voor het activeren van Event Hub:

string
byte[]
POCO
EventData - De standaardeigenschappen van EventData worden opgegeven in de voor de Microsoft.Azure.EventHubs-naamruimte.

Aanvullende typen

Apps met versie 5.0.0 of hoger van de Event Hub-extensie gebruiken het EventData type in Azure.Messaging.EventHubs in plaats van het type in microsoft.Azure.EventHubs-naamruimte. Met deze versie wordt de ondersteuning voor het verouderde Body type in de plaats van de volgende typen wegvalt:

EventBody

Standaard

U kunt de volgende parametertypen gebruiken voor het activeren van Event Hub:

string
byte[]
POCO
EventData - De standaardeigenschappen van EventData worden opgegeven in de voor de Microsoft.Azure.EventHubs-naamruimte.

Aanvullende typen

EventBody

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	Beschrijving
`PartitionContext`	PartitionContext	Het `PartitionContext`-exemplaar.
`EnqueuedTimeUtc`	`DateTime`	De wachtrijtijd in UTC.
`Offset`	`string`	De offset 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.

host.jsop instellingen

De host.jsin het bestand bevat instellingen die het trigger gedrag van de Event hub regelen. Zie de sectie host.jsop instellingen voor meer informatie over de beschik bare instellingen.

Volgende stappen

Gebeurtenissen schrijven naar een gebeurtenis stroom (uitvoer binding)

Azure Event Hubs trigger voor Azure Functions

Beoordeel uw ervaring

Schalen

Kenmerken en aantekeningen

Configuratie

Verbindingen

Verbindingsreeks

Op identiteit gebaseerde verbindingen

Machtiging verlenen aan de identiteit

Gebruik

Standaard

Aanvullende typen

Gebeurtenismetagegevens

host.jsop instellingen

Volgende stappen