Azure Event Hubs-utdatabindning för Azure Functions

  • Artikel

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 anslutningssträng å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 Anslut ions.

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å cosmos_db_trigger:

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 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. Mer information finns i Anslut ions.

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 anslutningssträng å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 Anslut ions.

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 anslutningssträng å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 Anslut ions.

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är T är en POJO eller någon inbyggd Java-typ. Med den här konfigurationen bevarar överföringen av ett värde till setValue metoden värdet som ett Event Hubs-meddelande.

Slutför PowerShell-exempel väntar.

Få åtkomst till utdatameddelandet genom att returnera värdet direkt eller med hjälp av context.extraOutputs.set().

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:

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 Anslut ionsinformation 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

Undantag och returkoder

Bindning Referens
Event Hubs Driftguide

Nästa steg