Freigeben über

Azure Event Hubs-Ausgabebindung für Azure Functions

  • Artikel

Dieser Artikel erläutert das Arbeiten mit Azure Event Hubs-Bindungen für Azure Functions. Azure Functions unterstützt Trigger- und Ausgabebindungen für Event Hubs.

Informationen zu Setup- und Konfigurationsdetails finden Sie in der Übersicht.

Mit der Event Hubs-Ausgabebindung werden Ereignisse in einen Ereignisdatenstrom geschrieben. Um Ereignisse in einen Event Hub schreiben zu können, müssen Sie über eine Sendeberechtigung verfügen.

Stellen Sie sicher, dass die erforderlichen Paketverweise vorhanden sind, bevor Sie versuchen, eine Ausgabebindung zu implementieren.

Wichtig

In diesem Artikel werden Registerkarten verwendet, um mehrere Versionen des Node.js-Programmiermodells zu unterstützen. Das v4-Modell ist allgemein verfügbar und bietet JavaScript- und TypeScript-Entwicklern eine flexiblere und intuitivere Erfahrung. Weitere Informationen zur Funktionsweise des v4-Modells finden Sie im Azure Functions Node.js-Entwicklerhandbuch. Weitere Informationen zu den Unterschieden zwischen v3 und v4 finden Sie im Migrationshandbuch.

Azure Functions unterstützt zwei Programmiermodelle für Python. Wie Sie Ihre Bindung definieren, hängt vom gewählten Python-Programmiermodell ab.

Mit dem Python v2-Programmiermodell können Sie Bindungen mithilfe von Decorators direkt im Python-Funktionscode definieren. Weitere Informationen finden Sie im Python Developer-Leitfaden.

In diesem Artikel werden beide Programmiermodelle unterstützt.

Beispiel

Das folgende Beispiel zeigt eine C#-Funktion, die eine Nachrichtenzeichenfolge in einen Event Hub schreibt, wobei der Rückgabewert der Methode als Ausgabe verwendet wird:

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

Das folgende Beispiel zeigt eine durch einen Timer ausgelöste TypeScript-Funktion, die eine einzelne Nachricht an einen Event Hub sendet:

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

Um mehrere Nachrichten auszugeben, geben Sie anstelle eines einzelnen Objekts ein Array zurück. Beispiel:

const timeStamp = new Date().toISOString();
const message = `Message created at: ${timeStamp}`;
return [`1: ${message}`, `2: ${message}`];

Das folgende Beispiel zeigt eine durch einen Timer ausgelöste JavaScript-Funktion, die eine einzelne Nachricht an einen Event Hub sendet:

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}`;
    },
});

Um mehrere Nachrichten auszugeben, geben Sie anstelle eines einzelnen Objekts ein Array zurück. Beispiel:

const timeStamp = new Date().toISOString();
const message = `Message created at: ${timeStamp}`;
return [`1: ${message}`, `2: ${message}`];

Vollständige PowerShell-Beispiele stehen aus.

Das folgende Beispiel zeigt eine Event Hubs-Triggerbindung sowie eine Python-Funktion, die die Bindung verwendet. Die Funktion schreibt eine Nachricht in einen Event Hub. Das Beispiel hängt davon ab, ob Sie das Python-Programmiermodell v1 oder v2 verwenden.

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'

Der folgende Python-Code sendet mehrere Nachrichten:

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

Das folgende Beispiel zeigt eine Java-Funktion, die eine Nachricht mit der aktuellen Uhrzeit in einen Event Hub schreibt.

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

Verwenden Sie die @EventHubOutput-Anmerkung in der Laufzeitbibliothek für Java-Funktionen für Parameter, deren Wert in Event Hubs veröffentlicht wird. Der Parametertyp sollte OutputBinding<T> lauten, wobei T für ein POJO oder einen beliebigen nativen Java-Typ steht.

Attributes

Von C#-Bibliotheken vom Typ prozessintern und isolierter Workerprozess wird ein Attribut verwendet, um die Bindung zu definieren. Das C#-Skript verwendet stattdessen eine Konfigurationsdatei function.json, wie im C#-Skript-Handbuch beschrieben.

Verwenden Sie [EventHubOutputAttribute], um eine Ausgabebindung an einen Event Hub zu definieren. Dabei werden die folgenden Eigenschaften unterstützt:

Parameter BESCHREIBUNG
EventHubName Der Name des Event Hubs. Wenn der Event Hub-Name auch in der Verbindungszeichenfolge enthalten ist, setzt dieser Wert diese Eigenschaft zur Laufzeit außer Kraft.
Connection Der Name einer App-Einstellung oder -Einstellungssammlung, die angibt, wie eine Verbindung mit Event Hubs hergestellt wird. Weitere Informationen finden Sie unter Verbindungen.

Decorator-Elemente

Gilt nur für das Python v2-Programmiermodell.

Für Python v2-Funktionen, die mithilfe eines Dekorators definiert sind, werden diese Eigenschaften für event_hub_output:

Eigenschaft BESCHREIBUNG
arg_name Der Variablenname, der in Funktionscode verwendet wird, der das Ereignis darstellt.
event_hub_name der Name des Event Hubs. Wenn der Event Hub-Name auch in der Verbindungszeichenfolge enthalten ist, setzt dieser Wert diese Eigenschaft zur Laufzeit außer Kraft.
connection Der Name einer App-Einstellung oder -Einstellungssammlung, die angibt, wie eine Verbindung mit Event Hubs hergestellt wird. Weitere Informationen finden Sie unter Verbindungen.

Informationen zu Python-Funktionen, die mithilfe von function.json definiert wurden, finden Sie im Abschnitt Konfiguration.

Anmerkungen

Verwenden Sie die EventHubOutput-Anmerkung in der Laufzeitbibliothek für Java-Funktionen für Parameter, deren Wert in Event Hubs veröffentlicht wird. Für die Anmerkung werden die folgenden Einstellungen unterstützt:

Konfiguration

Gilt nur für das Python v1-Programmiermodell.

In der folgenden Tabelle werden die Eigenschaften erläutert, die Sie für das options-Objekt festlegen können, das an die output.eventHub()-Methode übergeben wurde.

Eigenschaft Beschreibung
eventHubName Der Name des Event Hubs. Wenn der Event Hub-Name auch in der Verbindungszeichenfolge enthalten ist, setzt dieser Wert diese Eigenschaft zur Laufzeit außer Kraft.
connection Der Name einer App-Einstellung oder -Einstellungssammlung, die angibt, wie eine Verbindung mit Event Hubs hergestellt wird. Weitere Informationen finden Sie unter Verbindungen.

Die folgende Tabelle gibt Aufschluss über die Bindungskonfigurationseigenschaften, die Sie in der Datei function.json festlegen (unterscheidet sich je nach Runtimeversion):

Eigenschaft von „function.json“ BESCHREIBUNG
type Muss auf eventHub festgelegt sein.
direction Muss auf out festgelegt sein. Dieser Parameter wird automatisch festgelegt, wenn Sie die Bindung im Azure Portal erstellen.
name Der Variablenname, der in Funktionscode verwendet wird, der das Ereignis darstellt.
eventHubName Functions 2.x und höher Der Name des Event Hubs. Wenn der Event Hub-Name auch in der Verbindungszeichenfolge enthalten ist, setzt dieser Wert diese Eigenschaft zur Laufzeit außer Kraft.
connection Der Name einer App-Einstellung oder -Einstellungssammlung, die angibt, wie eine Verbindung mit Event Hubs hergestellt wird. Weitere Informationen finden Sie unter Verbindungen.

Wenn Sie die Entwicklung lokal ausführen, fügen Sie Ihre Anwendungseinstellungen in der Datei local.settings.json in der Values-Sammlung hinzu.

Verwendung

Der von der Event Hubs-Ausgabebindung unterstützte Parametertyp hängt von der Version der Functions-Runtime, von der Version des Erweiterungspakets sowie von der verwendeten C#-Modalität ab.

Wenn die Funktion ein einzelnes Ereignis schreiben soll, kann die Event Hubs-Ausgabebindung an die folgenden Typen gebunden werden:

type BESCHREIBUNG
string Das Ereignis als Zeichenfolge. Verwenden Sie diesen Parameter, wenn es sich bei dem Ereignis um einfachen Text handelt.
byte[] Die Bytes der Ereignisnachricht.
Serialisierbare JSON-Typen Ein Objekt, das das Ereignis darstellt. Functions versucht, einen POCO-Typ (Plain-Old CLR Object) in JSON-Daten zu serialisieren.

Wenn die Funktion mehrere Ereignisse schreiben soll, kann die Event Hubs-Ausgabebindung an die folgenden Typen gebunden werden:

type BESCHREIBUNG
T[], wobei T einer der einzelnen Ereignistypen ist Ein Array, das mehrere Ereignisse enthält. Jeder Eintrag stellt ein Ereignis dar.

Für andere Ausgabeszenarien erstellen und verwenden Sie Typen direkt aus Microsoft.Azure.EventHubs.

Es gibt zwei Optionen für das Ausgeben einer Event Hubs-Nachricht aus einer Funktion mithilfe der EventHubOutput-Anmerkung:

  • Rückgabewert: Wenn Sie die Anmerkung auf die Funktion selbst anwenden, wird der Rückgabewert der Funktion als Event Hubs-Nachricht beibehalten.

  • Imperativ: Um den Nachrichtenwert explizit festzulegen, wenden Sie die Anmerkung auf einen bestimmten Parameter des Typs OutputBinding<T> an, wobei T ein POJO oder ein beliebiger nativer Java-Typ ist. Bei dieser Konfiguration wird bei Übergabe eines Werts an die setValue-Methode der Wert als Event Hubs-Nachricht beibehalten.

Vollständige PowerShell-Beispiele stehen aus.

Auf die Ausgabemeldung greifen Sie zu, indem Sie den Wert direkt zurückgeben oder context.extraOutputs.set() verwenden.

Es gibt zwei Optionen für das Ausgeben einer Event Hubs-Nachricht aus einer Funktion:

  • Rückgabewert: Legen Sie die Eigenschaft name in function.json auf $return fest. Mit dieser Konfiguration wird der Rückgabewert der Funktion als Event Hubs-Nachricht beibehalten.

  • Imperativ: Übergeben Sie einen Wert an die set-Methode des Parameters, der als Out-Typ deklariert ist. Der an set übergebene Wert wird als Event Hubs-Nachricht beibehalten.

Verbindungen

Die connection-Eigenschaft ist ein Verweis auf eine Umgebungskonfiguration, die angibt, wie sich die App mit Event Hubs verbinden soll. Folgendes kann angegeben werden:

Wenn der konfigurierte Wert sowohl eine genaue Übereinstimmung für eine einzelne Einstellung als auch eine Präfix-Übereinstimmung für andere Einstellungen ist, wird die genaue Übereinstimmung verwendet.

Verbindungszeichenfolge

Sie erhalten diese Verbindungszeichenfolge, indem Sie für den Namespace (nicht für den eigentlichen Event Hub) auf die Schaltfläche Verbindungsinformationen klicken. Die Verbindungszeichenfolge muss für einen Event Hubs-Namespace und nicht für den Event Hub selbst sein.

Bei Verwendung für Trigger muss die Verbindungszeichenfolge mindestens über Leseberechtigungen verfügen, um die Funktion zu aktivieren. Bei Verwendung für Ausgabebindungen muss die Verbindungszeichenfolge über Sendeberechtigungen verfügen, um Nachrichten an den Ereignisdatenstrom zu senden.

Diese Verbindungszeichenfolge sollte in einer Anwendungseinstellung mit einem Namen gespeichert werden, der dem in der Eigenschaft connection der Bindungskonfiguration angegebenen Wert entspricht.

Identitätsbasierte Verbindungen

Wenn Sie Version 5.x oder eine höhere Version der Erweiterung verwenden, kann die App anstelle einer Verbindungszeichenfolge mit einem Geheimnis eine Microsoft Entra-Identität verwenden. Dazu definieren Sie Einstellungen unter einem gemeinsamen Präfix, das der Eigenschaft connection in der Trigger- und Bindungskonfiguration entspricht.

In diesem Modus benötigt die Erweiterung die folgenden Eigenschaften:

Eigenschaft Vorlage für Umgebungsvariable BESCHREIBUNG Beispielwert
Vollqualifizierter Namespace <CONNECTION_NAME_PREFIX>__fullyQualifiedNamespace Der vollqualifizierte Event Hubs-Namespace. myeventhubns.servicebus.windows.net

Zusätzliche Eigenschaften können festgelegt werden, um die Verbindung anzupassen. Weitere Informationen finden Sie unter Allgemeine Eigenschaften für identitätsbasierte Verbindungen.

Hinweis

Wenn Sie Azure App Configuration oder Key Vault verwenden, um Einstellungen für Verbindungen mit verwalteter Identität bereitzustellen, sollten die Namen der Einstellungen ein gültiges Schlüsseltrennzeichen wie : oder / anstelle von __ verwenden, um sicherzustellen, dass die Namen richtig aufgelöst werden.

Beispiel: <CONNECTION_NAME_PREFIX>:fullyQualifiedNamespace.

Identitätsbasierte Verbindungen verwenden eine verwaltete Identität, wenn sie im Azure Functions-Dienst gehostet werden. Standardmäßig wird eine vom System zugewiesene Identität verwendet, auch wenn mit den Eigenschaften credential und clientID eine vom Benutzer zugewiesene Identität angegeben werden kann. Beachten Sie, dass das Konfigurieren einer benutzerseitig zugewiesenen Identität mit einer Ressourcen-ID nicht unterstützt wird. Bei Ausführung in anderen Kontexten (z. B. bei der lokalen Entwicklung) wird stattdessen Ihre Entwickleridentität verwendet, Dieses Verhalten kann angepasst werden. Weitere Informationen finden Sie unter Lokale Entwicklung mit identitätsbasierten Verbindungen.

Erteilen der Berechtigung für die Identität

Unabhängig davon, welche Identität verwendet wird, muss diese über Berechtigungen zum Ausführen der vorgesehenen Aktionen verfügen. Daher müssen Sie für die meisten Azure-Dienste eine Rolle in Azure RBAC zuweisen, indem Sie entweder integrierte oder benutzerdefinierte Rollen verwenden, die diese Berechtigungen bieten.

Wichtig

Vom Zieldienst werden möglicherweise einige nicht für alle Kontexte erforderliche Berechtigungen verfügbar gemacht. Befolgen Sie nach Möglichkeit das Prinzip der geringsten Berechtigung, und gewähren Sie der Identität nur die erforderlichen Berechtigungen. Wenn die App beispielsweise nur Daten aus einer Datenquelle lesen muss, verwenden Sie eine Rolle, die nur über Leseberechtigungen verfügt. Es wäre nicht angemessen, eine Rolle zu zuweisen, die auch das Schreiben in diesen Dienst zulässt, da dies eine übermäßige Berechtigung für einen Lesevorgang wäre. Ebenso sollten Sie sicherstellen, dass die Rollenzuweisung auf die Ressourcen begrenzt ist, die gelesen werden müssen.

Sie müssen eine Rollenzuweisung erstellen, die zur Laufzeit Zugriff auf Ihren Event Hub ermöglicht. Der Bereich der Rollenzuweisung kann für einen Event Hubs-Namespace oder den Event Hub selbst gelten. Verwaltungsrollen wie Besitzer sind nicht ausreichend. Die folgende Tabelle zeigt integrierte Rollen, die für die Event Hubs-Erweiterung im Normalbetrieb empfohlen werden. Ihre Anwendung erfordert möglicherweise zusätzliche Berechtigungen basierend auf dem von Ihnen geschriebenen Code.

Bindungstyp Integrierte Beispielrollen
Trigger Azure Event Hubs-Datenempfänger, Azure Event Hubs-Datenbesitzer
Ausgabebindung Azure Event Hubs-Datensender

Ausnahmen und Rückgabecodes

Bindung Verweis
Event Hubs Betriebsleitfaden

Nächste Schritte