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

Artikel
05/13/2021
11 minuter för att läsa

Den här artikeln förklarar hur du arbetar med Azure Event Hubs -utlösare för Azure Functions. Azure Functions stöder utlösare och utgående bindningar för Event Hubs.

Information om konfiguration och konfigurations information finns i översikten.

Använd funktionsutlösaren för att svara på en händelse som skickas till en händelseström i en händelsehubb. Du måste ha läsbehörighet till den underliggande händelsehubben för att konfigurera utlösaren. När funktionen utlöses, skriver du meddelandet som skickas till funktionen som en sträng.

Skalning

Varje instans av en händelseutlöst funktion backas upp av en enda EventProcessorHost-instans. Utlösaren (drivs av en Event Hubs) säkerställer att endast en EventProcessorHost-instans kan få ett lån på en viss partition.

Tänk dig till exempel en händelsehubb på följande sätt:

10 partitioner
1 000 händelser fördelas jämnt över alla partitioner, med 100 meddelanden i varje partition

När funktionen först aktiveras finns det bara en instans av funktionen. Vi anropar den första funktionsinstansen Function_0 . Funktionen Function_0 har en enda instans av EventProcessorHost som har ett lån på alla tio partitioner. Den här instansen läser händelser från partitionerna 0–9. Från och med nu händer något av följande:

Nya funktionsinstanser behövs inte: kan bearbeta alla 1 000 händelser innan skalningslogiken för Functions Function_0 börjar gälla. I det här fallet bearbetas alla 1 000 meddelanden av Function_0 .
Ytterligare en funktionsinstans läggs till: Om skalningslogiken i Functions bestämmer att har fler meddelanden än den kan bearbeta skapas en ny Function_0 Function_1 funktionsappinstans ( ). Den här nya funktionen har också en associerad instans av EventProcessorHost. När den underliggande Event Hubs upptäcker att en ny värdinstans försöker läsa meddelanden belastningsutjämnas partitionerna mellan värdinstanserna. Till exempel kan partitioner 0–4 tilldelas och Function_0 partitionerna 5–9 till Function_1 .
Fler funktionsinstanser läggs till: Om logiken för funktionsskalning avgör att både och har fler meddelanden än de kan bearbeta skapas nya Function_0 Function_1 Functions_N funktionsappinstanser. Appar skapas till den punkt där N är större än antalet händelsehubbpartitioner. I vårt exempel Event Hubs belastningsutjämna partitionerna, i det här fallet mellan Function_0 instanserna ... Functions_9 .

När skalning sker är N instanser ett tal som är större än antalet händelsehubbpartitioner. Det här mönstret används för att säkerställa att EventProcessorHost-instanser är tillgängliga för att hämta lås på partitioner när de blir tillgängliga från andra instanser. Du debiteras bara för de resurser som används när funktionsinstansen körs. Med andra ord debiteras du inte för den här överetablering.

När all funktionskörning har slutförts (med eller utan fel) läggs kontrollpunkter till i det associerade lagringskontot. När kontroll pekaren lyckas hämtas aldrig alla 1 000 meddelanden igen.

I följande exempel visas en C#-funktion som loggar meddelandetexten i händelsehubbens utlösare.

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

För att få åtkomst till händelsemetadata i funktionskoden binder du till ett EventData-objekt (kräver en using-instruktion för Microsoft.Azure.EventHubs ). Du kan också komma åt samma egenskaper med hjälp av bindningsuttryck i metodsignaturen. I följande exempel visas båda sätten att hämta samma data:

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

Om du vill ta emot händelser i en batch, string skapa EventData eller en matris.

Anteckning

När du tar emot i en batch kan du inte binda till metodparametrar som i exemplet ovan med och DateTime enqueuedTimeUtc måste ta emot dessa från varje EventData objekt

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

I följande exempel visas en händelsehubbutlösarbindning i en function.json-fil och en C#-skriptfunktion som använder bindningen. Funktionen loggar meddelandetexten i händelsehubbens utlösare.

I följande exempel visas Event Hubs data i filen function.json.

Version 2.x och senare

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

Version 1.x

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

Här är C#-skriptkoden:

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

Om du vill ta emot händelser i en batch, string skapa EventData eller en matris:

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

I följande exempel visas en händelsehubbutlösarbindning i en function.json-fil och en JavaScript-funktion som använder bindningen. Funktionen läser händelsemetadata och loggar meddelandet.

I följande exempel visas Event Hubs data i filen function.json.

Version 2.x och senare

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

Version 1.x

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

Här är JavaScript-koden:

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

Om du vill ta emot händelser i en batch cardinality anger du till i filen many function.json, som du ser i följande exempel.

Version 2.x och senare

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

Version 1.x

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

Här är JavaScript-koden:

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

I följande exempel visas en händelsehubbutlösarbindning i en function.json-fil och en Python-funktion som använder bindningen. Funktionen läser händelsemetadata och loggar meddelandet.

I följande exempel visas Event Hubs data i filen function.json.

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

Här är Python-koden:

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

I följande exempel visas en händelsehubbutlösarbindning som loggar meddelandetexten i händelsehubbens utlösare.

@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örningsbiblioteketanvänder du EventHubTrigger anteckningen för parametrar vars värde skulle komma från Event Hub. Parametrar med dessa anteckningar gör att funktionen körs när en händelse anländer. Den här anteckningen kan användas med interna Java-typer, POPO:er eller nullbara värden med hjälp av Optional<T> .

Attribut och anteckningar

I C#-klassbibliotekanvänder du attributet EventHubTriggerAttribute.

Attributets konstruktor tar namnet på händelsehubben, namnet på konsumentgruppen och namnet på en appinställning som innehåller anslutningssträngen. Mer information om de här inställningarna finns i avsnittet om utlösarkonfiguration. Här är ett EventHubTriggerAttribute attributexempel:

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

Ett fullständigt exempel finns i Trigger - C# example.

Konfiguration

I följande tabell beskrivs de bindningskonfigurationsegenskaper som du anger i function.json-filen och EventHubTrigger -attributet.

function.json-egenskap	Attributegenskap	Description
Typ	saknas	Måste anges till `eventHubTrigger` . Den här egenskapen anges automatiskt när du skapar utlösaren i Azure Portal.
Riktning	saknas	Måste anges till `in` . Den här egenskapen anges automatiskt när du skapar utlösaren i Azure Portal.
Namn	saknas	Namnet på variabeln som representerar händelseobjektet i funktionskoden.
Sökvägen	EventHubName	Endast Functions 1.x. Namnet på händelsehubben. När händelsehubbens namn också finns i anslutningssträngen åsidosätter det värdet den här egenskapen vid körning.
eventHubName	EventHubName	Functions 2.x och senare. Namnet på händelsehubben. När händelsehubbens namn också finns i anslutningssträngen åsidosätter det värdet den här egenskapen vid körning. Kan refereras via appinställningar `%eventHubName%`
consumerGroup	ConsumerGroup	En valfri egenskap som anger konsumentgruppen som används för att prenumerera på händelser i hubben. Om detta utelämnas `$Default` används konsumentgruppen.
Kardinalitet	saknas	Används för alla icke-C#-språk. Ange till `many` för att aktivera batchbearbetning. Om det utelämnas eller `one` anges till skickas ett enskilt meddelande till funktionen. I C# tilldelas den här egenskapen automatiskt när utlösaren har en matris för typen.
Anslutning	Anslutning	Namnet på en appinställning eller inställningssamling som anger hur du ansluter till Event Hubs. Se Anslutningar.

När du utvecklar lokalt går appinställningarna till ilocal.settings.js på filen.

Anslutningar

Egenskapen connection är en referens till miljökonfigurationen som anger hur appen ska ansluta till Event Hubs. Den kan ange:

Namnet på en programinställning som innehåller en anslutningssträng
Namnet på ett delat prefix för flera programinställningar, tillsammans definierar en identitetsbaserad anslutning.

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.

Anslutningssträng

Hämta den här anslutningssträngen genom att klicka på knappen Anslutningsinformation för namnområdet, inte själva händelsehubben. Anslutningssträngen måste vara för Event Hubs namnrymd, inte själva händelsehubben.

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

Den här anslutningssträngen 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.xeller senare av tillägget kan du, i stället för att använda en anslutningssträng med en hemlighet, be appen att använda en Azure Active Directory identitet. Om du vill göra detta definierar du inställningar under ett gemensamt prefix som mappar till connection egenskapen i utlösar- och bindningskonfigurationen.

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

Egenskap	Mall för miljövariabler	Description	Exempelvärde
Fullständigt kvalificerat namnområde	`<CONNECTION_NAME_PREFIX>__fullyQualifiedNamespace`	Det fullständigt kvalificerade Event Hubs namnområdet.	<event_hubs_namespace>.servicebus.windows.net

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

När identitetsbaserade anslutningar Azure Functions i tjänsten använder de en hanterad identitet. Den system tilldelade identiteten används som standard, även om en användar tilldelad identitet kan anges med credential egenskaperna clientID och . När den körs i andra kontexter, till exempel lokal utveckling, används din utvecklaridentitet i stället, även om detta 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. Du måste tilldela en roll i Azure RBACmed hjälp av 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 ska du följa principen om minsta behörighet och endast bevilja identiteten de behörigheter som krävs. 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. Rolltilldelningens omfattning måste vara för en Event Hubs namnrymd, inte 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 i normal drift. Programmet kan kräva ytterligare behörigheter baserat på den kod som du skriver.

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

Användning

Standardvärde

Du kan använda följande parametertyper för den utlösande händelsehubben:

string
byte[]
POCO
EventData- Standardegenskaperna för EventData anges i för namnområdet Microsoft.Azure.EventHubs.

Ytterligare typer

Appar som använder version 5.0.0 eller senare av Event Hub-tillägget använder typen EventData i Azure.Messaging.EventHubs i stället för i namnområdet Microsoft.Azure.EventHubs. Den här versionen släpper stödet för Body den äldre typen till förmån för följande typer:

EventBody

Standardvärde

Du kan använda följande parametertyper för den utlösande händelsehubben:

string
byte[]
POCO
EventData- Standardegenskaperna för EventData anges i för namnområdet Microsoft.Azure.EventHubs.

Ytterligare typer

EventBody

Händelsemetadata

Utlösaren Event Hubs 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.

Egenskap	Typ	Description
`PartitionContext`	PartitionContext	`PartitionContext`-instansen.
`EnqueuedTimeUtc`	`DateTime`	Den tid iqueued 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 dataströmmen. Identifieraren är unik inom en partition Event Hubs dataströ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.

host.jspå Inställningar

host.jsfilen innehåller inställningar som styr beteendet för Event Hub-utlösaren. Mer information om tillgängliga inställningar finns i avsnittet host.jsi inställningar .

Nästa steg

Skriv händelser till en händelse ström (utgående bindning)

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

Betygsätta din upplevelse

Skalning

Attribut och anteckningar

Konfiguration

Anslutningar

Anslutningssträng

Identitetsbaserade anslutningar

Bevilja behörighet till identiteten

Användning

Standardvärde

Ytterligare typer

Händelsemetadata

host.jspå Inställningar

Nästa steg