Azure Event Hubs-utlösare för Azure Functions
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 Anslutningar. |
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å event_hub_message_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 Anslutningar. |
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 one skickas ett enda meddelande till funktionen. |
samband | Namnet på en appinställning eller inställningssamling som anger hur du ansluter till Event Hubs. Se Anslutningar. |
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 Portal. |
riktning | Måste anges till in . Den här egenskapen anges automatiskt när du skapar utlösaren i Azure Portal. |
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 one skickas ett enda meddelande till funktionen. |
samband | Namnet på en appinställning eller inställningssamling som anger hur du ansluter till Event Hubs. Se Anslutningar. |
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.
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:
- Namnet på en programinställning som innehåller en anslutningssträng
- Namnet på ett delat prefix för flera programinställningar, som 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.
Connection string
Hämta den här anslutningssträng genom att klicka på knappen Anslutningsinformation 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 .