Azure Event Hubs-utdatabindning för Azure Functions
Den här artikeln beskriver hur du arbetar med Azure Event Hubs-bindningar 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 Event Hubs-utdatabindningen för att skriva händelser till en händelseström. Du måste ha behörighet att skicka till en händelsehubb för att kunna skicka händelser till den.
Kontrollera att nödvändiga paketreferenser finns på plats innan du försöker implementera en utdatabindning.
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 skriver en meddelandesträng till en händelsehubb med metodens returvärde som utdata:
[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 timerutlöst TypeScript-funktion som skickar ett enda meddelande till en händelsehubb:
import { app, InvocationContext, output, Timer } from '@azure/functions';
export async function timerTrigger1(myTimer: Timer, context: InvocationContext): Promise<string> {
const timeStamp = new Date().toISOString();
return `Message created at: ${timeStamp}`;
}
app.timer('timerTrigger1', {
schedule: '0 */5 * * * *',
return: output.eventHub({
eventHubName: 'myeventhub',
connection: 'MyEventHubSendAppSetting',
}),
handler: timerTrigger1,
});
Om du vill mata ut flera meddelanden returnerar du en matris i stället för ett enda objekt. Till exempel:
const timeStamp = new Date().toISOString();
const message = `Message created at: ${timeStamp}`;
return [`1: ${message}`, `2: ${message}`];
I följande exempel visas en timerutlöst JavaScript-funktion som skickar ett enda meddelande till en händelsehubb:
const { app, output } = require('@azure/functions');
const eventHubOutput = output.eventHub({
eventHubName: 'myeventhub',
connection: 'MyEventHubSendAppSetting',
});
app.timer('timerTrigger1', {
schedule: '0 */5 * * * *',
return: eventHubOutput,
handler: (myTimer, context) => {
const timeStamp = new Date().toISOString();
return `Message created at: ${timeStamp}`;
},
});
Om du vill mata ut flera meddelanden returnerar du en matris i stället för ett enda objekt. Till exempel:
const timeStamp = new Date().toISOString();
const message = `Message created at: ${timeStamp}`;
return [`1: ${message}`, `2: ${message}`];
Slutför PowerShell-exempel väntar.
I följande exempel visas en utlösarbindning för händelsehubben och en Python-funktion som använder bindningen. Funktionen skriver ett meddelande till en händelsehubb. 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="eventhub_output")
@app.route(route="eventhub_output")
@app.event_hub_output(arg_name="event",
event_hub_name="<EVENT_HUB_NAME>",
connection="<CONNECTION_SETTING>")
def eventhub_output(req: func.HttpRequest, event: func.Out[str]):
body = req.get_body()
if body is not None:
event.set(body.decode('utf-8'))
else:
logging.info('req body is none')
return 'ok'
Här är Python-kod som skickar flera meddelanden:
import logging
import azure.functions as func
from typing import List
app = func.FunctionApp()
@app.function_name(name="eventhub_output")
@app.route(route="eventhub_output")
@app.event_hub_output(arg_name="event",
event_hub_name="<EVENT_HUB_NAME>",
connection="<CONNECTION_SETTING>")
def eventhub_output(req: func.HttpRequest, event: func.Out[List[str]]) -> func.HttpResponse:
my_messages=["message1", "message2","message3"]
event.set(my_messages)
return func.HttpResponse(f"Messages sent")
I följande exempel visas en Java-funktion som skriver ett meddelande som innehåller den aktuella tiden till en händelsehubb.
@FunctionName("sendTime")
@EventHubOutput(name = "event", eventHubName = "samples-workitems", connection = "AzureEventHubConnection")
public String sendTime(
@TimerTrigger(name = "sendTimeTrigger", schedule = "0 */5 * * * *") String timerInfo) {
return LocalDateTime.now().toString();
}
I Java Functions-körningsbiblioteket använder du anteckningen @EventHubOutput
för parametrar vars värde skulle publiceras till Event Hubs. Parametern ska vara av typen OutputBinding<T>
, där T
är en POJO eller någon inbyggd Java-typ.
Attribut
C#-bibliotek i både processprocess och isolerad arbetsprocess använder attribut för att konfigurera bindningen. C#-skriptet använder i stället en function.json konfigurationsfil enligt beskrivningen i C#-skriptguiden.
Använd [EventHubOutputAttribute] för att definiera en utdatabindning till en händelsehubb som stöder följande egenskaper.
Parametrar | beskrivning |
---|---|
EventHubName | Namnet på händelsehubben. När händelsehubbens namn också finns i niska veze åsidosätter det värdet den här egenskapen vid körning. |
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 stöds dessa egenskaper för event_hub_output
:
Property | beskrivning |
---|---|
arg_name |
Variabelnamnet som används i funktionskoden som representerar händelsen. |
event_hub_name |
namnet på händelsehubben. När händelsehubbens namn också finns i niska veze å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. Mer information finns i 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 EventHubOutput-kommentaren för parametrar vars värde skulle publiceras till Event Hubs. Följande inställningar stöds i kommentaren:
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 output.eventHub()
till metoden.
Property | beskrivning |
---|---|
eventHubName | Namnet på händelsehubben. När händelsehubbens namn också finns i niska veze åsidosätter det värdet den här egenskapen vid körning. |
samband | Namnet på en appinställning eller inställningssamling som anger hur du ansluter till Event Hubs. Mer information finns i Anslutningar. |
I följande tabell förklaras de bindningskonfigurationsegenskaper som du anger i function.json-filen, som skiljer sig beroende på körningsversion.
function.json egenskap | beskrivning |
---|---|
typ | Måste anges till eventHub . |
riktning | Måste anges till out . Den här parametern anges automatiskt när du skapar bindningen i Azure-portalen. |
Namn | Variabelnamnet som används i funktionskoden som representerar händelsen. |
eventHubName | Funktioner 2.x och senare. Namnet på händelsehubben. När händelsehubbens namn också finns i niska veze åsidosätter det värdet den här egenskapen vid körning. |
samband | Namnet på en appinställning eller inställningssamling som anger hur du ansluter till Event Hubs. Mer information finns i Anslutningar. |
När du utvecklar lokalt lägger du till dina programinställningar i den local.settings.json filen i Values
samlingen.
Användning
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 skriva en enskild händelse kan Event Hubs-utdatabindningen 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 | Ett objekt som representerar händelsen. Functions försöker serialisera en vanlig CLR-objekttyp (POCO) till JSON-data. |
När du vill att funktionen ska skriva flera händelser kan Event Hubs-utdatabindningen binda till följande typer:
Typ | Beskrivning |
---|---|
T[] där T är en av de enskilda händelsetyperna |
En matris som innehåller flera händelser. Varje post representerar en händelse. |
För andra utdatascenarier skapar och använder du typer från Microsoft.Azure.EventHubs direkt.
Det finns två alternativ för att mata ut ett Event Hubs-meddelande från en funktion med hjälp av EventHubOutput-kommentaren:
Returvärde: Genom att använda anteckningen på själva funktionen sparas funktionens returvärde som ett Event Hubs-meddelande.
Imperativ: Om du uttryckligen vill ange meddelandevärdet använder du anteckningen på en specifik parameter av typen
OutputBinding<T>
, därT
är en POJO eller någon inbyggd Java-typ. Med den här konfigurationen bevarar överföringen av ett värde tillsetValue
metoden värdet som ett Event Hubs-meddelande.
Slutför PowerShell-exempel väntar.
Det finns två alternativ för att mata ut ett Event Hubs-meddelande från en funktion:
Returvärde: Ange
name
egenskapen i function.json till$return
. Med den här konfigurationen sparas funktionens returvärde som ett Event Hubs-meddelande.Imperativ: Skicka ett värde till den angivna metoden för parametern som deklarerats som en Out-typ . Värdet som skickas till
set
sparas som ett Event Hubs-meddelande.
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 niska veze
- 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 niska veze genom att klicka på knappen Anslutningsinformation för namnområdet, inte själva händelsehubben. Niska veze 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 niska veze ha minst läsbehörighet för att aktivera funktionen. När den används för utdatabindningar måste niska veze ha "skicka" behörighet att skicka meddelanden till händelseströmmen.
Den här niska veze 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 niska veze 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 |
Undantag och returkoder
Bindning | Referens |
---|---|
Event Hubs | Driftguide |