Delen via

Azure Event Hubs-uitvoerbinding voor Azure Functions

  • Artikel

In dit artikel wordt uitgelegd hoe u werkt met Azure Event Hubs-bindingen voor Azure Functions. Azure Functions ondersteunt trigger- en uitvoerbindingen voor Event Hubs.

Zie het overzicht voor informatie over het instellen en configureren van details.

Gebruik de Event Hubs-uitvoerbinding om gebeurtenissen naar een gebeurtenisstroom te schrijven. U moet een verzendmachtiging voor een Event Hub hebben om er gebeurtenissen naar te kunnen schrijven.

Zorg ervoor dat de vereiste pakketverwijzingen aanwezig zijn voordat u een uitvoerbinding implementeert.

Belangrijk

In dit artikel worden tabbladen gebruikt ter ondersteuning van meerdere versies van het Node.js programmeermodel. Het v4-model is algemeen beschikbaar en is ontworpen voor een flexibelere en intuïtievere ervaring voor JavaScript- en TypeScript-ontwikkelaars. Raadpleeg de ontwikkelaarshandleiding voor Azure Functions Node.js voor meer informatie over hoe het v4-model werkt. Raadpleeg de migratiehandleiding voor meer informatie over de verschillen tussen v3 en v4.

Azure Functions ondersteunt twee programmeermodellen voor Python. De manier waarop u uw bindingen definieert, is afhankelijk van het gekozen programmeermodel.

Met het Python v2-programmeermodel kunt u bindingen definiëren met behulp van decorators rechtstreeks in uw Python-functiecode. Zie de Ontwikkelaarshandleiding voor Python voor meer informatie.

Dit artikel ondersteunt beide programmeermodellen.

Opmerking

In het volgende voorbeeld ziet u een C#-functie waarmee een berichttekenreeks naar een Event Hub wordt geschreven, met behulp van de retourwaarde van de methode als uitvoer:

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

In het volgende voorbeeld ziet u een door een timer geactiveerde TypeScript-functie waarmee één bericht naar een Event Hub wordt verzonden:

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

Als u meerdere berichten wilt uitvoeren, retourneert u een matrix in plaats van één object. Voorbeeld:

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

In het volgende voorbeeld ziet u een door een timer geactiveerde JavaScript-functie waarmee één bericht naar een Event Hub wordt verzonden:

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

Als u meerdere berichten wilt uitvoeren, retourneert u een matrix in plaats van één object. Voorbeeld:

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

Volledige PowerShell-voorbeelden zijn in behandeling.

In het volgende voorbeeld ziet u een event hub-triggerbinding en een Python-functie die gebruikmaakt van de binding. De functie schrijft een bericht naar een Event Hub. Het voorbeeld is afhankelijk van of u het python-programmeermodel v1 of v2 gebruikt.

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'

Hier volgt Python-code waarmee meerdere berichten worden verzonden:

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

In het volgende voorbeeld ziet u een Java-functie waarmee een bericht met de huidige tijd naar een Event Hub wordt geschreven.

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

Gebruik in de Java Functions Runtime-bibliotheek de @EventHubOutput aantekening voor parameters waarvan de waarde naar Event Hubs zou worden gepubliceerd. Deze parameter zou van het type OutputBinding<T> moeten zijn, waarbij T een POJO of een systeemeigen Java-type is.

Kenmerken

Zowel in-process als geïsoleerde werkproces C#-bibliotheken gebruiken kenmerk om de binding te configureren. C#-script maakt in plaats daarvan gebruik van een function.json configuratiebestand, zoals beschreven in de handleiding voor C#-scripts.

Gebruik [EventHubOutputAttribute] om een uitvoerbinding te definiëren voor een Event Hub, die de volgende eigenschappen ondersteunt.

Parameters Beschrijving
EventHubName De naam van de event hub. Wanneer de event hub-naam ook aanwezig is in de verbindingsreeks, overschrijft die waarde deze eigenschap tijdens runtime.
Verbinding De naam van een app-instelling of instellingsverzameling die aangeeft hoe verbinding moet worden gemaakt met Event Hubs. Zie Verbindingen voor meer informatie.

Decorators

Is alleen van toepassing op het Python v2-programmeermodel.

Voor Python v2-functies die zijn gedefinieerd met behulp van een decorator, worden deze eigenschappen ondersteund voor event_hub_output:

Eigenschappen Beschrijving
arg_name De naam van de variabele die in functiecode wordt gebruikt, vertegenwoordigt de gebeurtenis.
event_hub_name hij heet de Event Hub. Wanneer de event hub-naam ook aanwezig is in de verbindingsreeks, overschrijft die waarde deze eigenschap tijdens runtime.
connection De naam van een app-instelling of instellingsverzameling die aangeeft hoe verbinding moet worden gemaakt met Event Hubs. Zie Verbindingen voor meer informatie.

Zie de sectie Configuratie voor Python-functies die zijn gedefinieerd met behulp van function.json.

Aantekeningen

Gebruik in de Runtime-bibliotheek van Java Functions de aantekening eventHubOutput voor parameters waarvan de waarde naar Event Hubs zou worden gepubliceerd. De volgende instellingen worden ondersteund voor de aantekening:

Configuratie

Is alleen van toepassing op het Python v1-programmeermodel.

In de volgende tabel worden de eigenschappen uitgelegd die u kunt instellen voor het options object dat aan de output.eventHub() methode is doorgegeven.

Eigenschappen Beschrijving
eventHubName De naam van de event hub. Wanneer de event hub-naam ook aanwezig is in de verbindingsreeks, overschrijft die waarde deze eigenschap tijdens runtime.
verbinding De naam van een app-instelling of instellingsverzameling die aangeeft hoe verbinding moet worden gemaakt met Event Hubs. Zie Verbindingen voor meer informatie.

In de volgende tabel worden de bindingsconfiguratie-eigenschappen uitgelegd die u hebt ingesteld in het function.json-bestand , wat verschilt per runtime-versie.

function.json-eigenschap Beschrijving
type Moet worden ingesteld op eventHub.
direction Moet worden ingesteld op out. Deze parameter wordt automatisch ingesteld wanneer u de binding maakt in de Azure-portal.
name De naam van de variabele die in functiecode wordt gebruikt, vertegenwoordigt de gebeurtenis.
eventHubName Functions 2.x en hoger. De naam van de event hub. Wanneer de event hub-naam ook aanwezig is in de verbindingsreeks, overschrijft die waarde deze eigenschap tijdens runtime.
verbinding De naam van een app-instelling of instellingsverzameling die aangeeft hoe verbinding moet worden gemaakt met Event Hubs. Zie Verbindingen voor meer informatie.

Wanneer u lokaal ontwikkelt, voegt u uw toepassingsinstellingen toe aan het local.settings.json-bestand in de Values verzameling.

Gebruik

Het parametertype dat wordt ondersteund door de Event Hubs-uitvoerbinding, is afhankelijk van de runtimeversie van Functions, de versie van het extensiepakket en de gebruikte C#-modaliteit.

Wanneer u wilt dat de functie één gebeurtenis schrijft, kan de Event Hubs-uitvoerbinding worden gekoppeld aan de volgende typen:

Type Description
string De gebeurtenis als een tekenreeks. Gebruik deze tekst wanneer de gebeurtenis eenvoudige tekst is.
byte[] De bytes van de gebeurtenis.
JSON serialiseerbare typen Een object dat de gebeurtenis vertegenwoordigt. Functions probeert een eenvoudig oud CLR-objecttype (POCO) te serialiseren in JSON-gegevens.

Wanneer u wilt dat de functie meerdere gebeurtenissen schrijft, kan de Event Hubs-uitvoerbinding worden gekoppeld aan de volgende typen:

Type Description
T[] waarbij T een van de gebeurtenistypen voor één gebeurtenis is Een matrix met meerdere gebeurtenissen. Elke vermelding vertegenwoordigt één gebeurtenis.

Voor andere uitvoerscenario's maakt en gebruikt u rechtstreeks een EventHubProducerClient met andere typen van Azure.Messaging.EventHubs . Zie Azure-clients registreren voor een voorbeeld van het gebruik van afhankelijkheidsinjectie om een clienttype te maken op basis van de Azure SDK.

Er zijn twee opties voor het uitvoeren van een Event Hubs-bericht vanuit een functie met behulp van de annotatie eventHubOutput :

  • Retourwaarde: Door de aantekening toe te passen op de functie zelf, wordt de retourwaarde van de functie behouden als een Event Hubs-bericht.

  • Imperatief: Als u de berichtwaarde expliciet wilt instellen, past u de aantekening toe op een specifieke parameter van het type OutputBinding<T>, waarbij T een POJO of een systeemeigen Java-type is. Met deze configuratie wordt de waarde doorgegeven aan de setValue methode als een Event Hubs-bericht.

Volledige PowerShell-voorbeelden zijn in behandeling.

Open het uitvoerbericht door de waarde rechtstreeks of met behulp van context.extraOutputs.set().

Er zijn twee opties voor het uitvoeren van een Event Hubs-bericht vanuit een functie:

  • Retourwaarde: Stel de name eigenschap in function.json in op $return. Met deze configuratie blijft de retourwaarde van de functie behouden als een Event Hubs-bericht.

  • Imperatief: Geef een waarde door aan de ingestelde methode van de parameter die is gedeclareerd als een Out-type . De doorgegeven set waarde wordt behouden als een Event Hubs-bericht.

Connecties

De connection eigenschap is een verwijzing naar de omgevingsconfiguratie die aangeeft hoe de app verbinding moet maken met Event Hubs. Het kan het volgende opgeven:

Als de geconfigureerde waarde zowel een exacte overeenkomst is voor één instelling als een voorvoegselovereenkomst voor andere instellingen, wordt de exacte overeenkomst gebruikt.

Connection string

Verkrijg deze verbindingsreeks door op de knop Verbindingsgegevens voor de naamruimte te klikken, niet op de Event Hub zelf. De verbindingsreeks moet voor een Event Hubs-naamruimte zijn, niet voor de Event Hub zelf.

Wanneer de verbindingsreeks wordt gebruikt voor triggers, moet de verbindingsreeks ten minste leesmachtigingen hebben om de functie te activeren. Wanneer de verbindingsreeks wordt gebruikt voor uitvoerbindingen, moet de verbindingsreeks machtigingen voor het verzenden van berichten naar de gebeurtenisstroom hebben.

Deze verbindingsreeks moet worden opgeslagen in een toepassingsinstelling met een naam die overeenkomt met de waarde die is opgegeven door de connection eigenschap van de bindingsconfiguratie.

Op identiteit gebaseerde verbindingen

Als u versie 5.x of hoger van de extensie gebruikt, in plaats van een verbindingsreeks met een geheim te gebruiken, kunt u de app een Microsoft Entra-identiteit laten gebruiken. Hiervoor definieert u instellingen onder een gemeenschappelijk voorvoegsel dat wordt toegewezen aan de connection eigenschap in de trigger- en bindingsconfiguratie.

In deze modus vereist de extensie de volgende eigenschappen:

Eigenschappen Sjabloon voor omgevingsvariabele Beschrijving Voorbeeldwaarde
Volledig gekwalificeerde naamruimte <CONNECTION_NAME_PREFIX>__fullyQualifiedNamespace De volledig gekwalificeerde Event Hubs-naamruimte. myeventhubns.servicebus.windows.net

Er kunnen extra eigenschappen worden ingesteld om de verbinding aan te passen. Zie Algemene eigenschappen voor op identiteit gebaseerde verbindingen.

Notitie

Wanneer u Azure-app Configuratie of Key Vault gebruikt om instellingen voor beheerde identiteitverbindingen te bieden, moeten instellingsnamen een geldig sleutelscheidingsteken gebruiken, zoals : of / in plaats van de __ sleutelkluis om ervoor te zorgen dat namen correct worden omgezet.

Bijvoorbeeld: <CONNECTION_NAME_PREFIX>:fullyQualifiedNamespace.

Wanneer deze worden gehost in de Azure Functions-service, maken identiteitsverbindingen gebruik van een beheerde identiteit. De door het systeem toegewezen identiteit wordt standaard gebruikt, hoewel een door de gebruiker toegewezen identiteit kan worden opgegeven met de credential en clientID eigenschappen. Houd er rekening mee dat het configureren van een door de gebruiker toegewezen identiteit met een resource-id niet wordt ondersteund. Wanneer uw ontwikkelaarsidentiteit wordt uitgevoerd in andere contexten, zoals lokale ontwikkeling, wordt in plaats daarvan uw ontwikkelaarsidentiteit gebruikt, hoewel dit kan worden aangepast. Zie Lokale ontwikkeling met op identiteit gebaseerde verbindingen.

Toestemming verlenen aan de identiteit

Elke identiteit die wordt gebruikt, moet machtigingen hebben om de beoogde acties uit te voeren. Voor de meeste Azure-services betekent dit dat u een rol in Azure RBAC moet toewijzen met behulp van ingebouwde of aangepaste rollen die deze machtigingen bieden.

Belangrijk

Sommige machtigingen worden mogelijk weergegeven door de doelservice die niet nodig is voor alle contexten. Waar mogelijk moet u zich houden aan het principe van minimale bevoegdheid, waarbij de identiteit alleen vereiste bevoegdheden verleent. Als de app bijvoorbeeld alleen uit een gegevensbron moet kunnen lezen, gebruikt u een rol die alleen gemachtigd is om te lezen. Het zou ongepast zijn om een rol toe te wijzen die ook schrijfbewerkingen naar die service toestaat, omdat dit overmatige machtigingen zou zijn voor een leesbewerking. Op dezelfde manier wilt u ervoor zorgen dat de roltoewijzing alleen is afgestemd op de resources die moeten worden gelezen.

U moet een roltoewijzing maken die tijdens runtime toegang biedt tot uw Event Hub. Het bereik van de roltoewijzing kan zijn voor een Event Hubs-naamruimte of de Event Hub zelf. Beheerrollen zoals Eigenaar zijn niet voldoende. In de volgende tabel ziet u ingebouwde rollen die worden aanbevolen bij het gebruik van de Event Hubs-extensie in normale werking. Uw toepassing vereist mogelijk extra machtigingen op basis van de code die u schrijft.

Bindingstype Voorbeeld van ingebouwde rollen
Trigger Azure Event Hubs-gegevensontvanger, Azure Event Hubs-gegevenseigenaar
Uitvoerbinding Azure Event Hubs-gegevenszender

Uitzonderingen en retourcodes

Binding Verwijzing
Event Hubs Operations Guide (Bedieningshandleiding)

Volgende stappen