Azure Event Grid-uitvoerbinding voor Azure Functions

  • Artikel

Gebruik de Event Grid-uitvoerbinding om gebeurtenissen naar een aangepast onderwerp te schrijven. U moet een geldige toegangssleutel hebben voor het aangepaste onderwerp. De Event Grid-uitvoerbinding biedt geen ondersteuning voor SAS-tokens (Shared Access Signature).

Zie Hoe u werkt met Event Grid-triggers en -bindingen in Azure Functions voor meer informatie over de installatie- en configuratiedetails.

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.

Belangrijk

De Event Grid-uitvoerbinding is alleen beschikbaar voor Functions 2.x en hoger.

Opmerking

Het type uitvoerparameter dat wordt gebruikt met een Event Grid-uitvoerbinding, is afhankelijk van de runtimeversie van Functions, de versie van de bindingsextensie en de modaliteit van de C#-functie. De C#-functie kan worden gemaakt met een van de volgende C#-modi:

In het volgende voorbeeld ziet u hoe het aangepaste type wordt gebruikt in zowel de trigger als een Event Grid-uitvoerbinding:

using System;
using System.Collections.Generic;
using Microsoft.Azure.Functions.Worker;
using Microsoft.Extensions.Logging;

namespace SampleApp
{
    public static class EventGridFunction
    {
        [Function(nameof(EventGridFunction))]
        [EventGridOutput(TopicEndpointUri = "MyEventGridTopicUriSetting", TopicKeySetting = "MyEventGridTopicKeySetting")]
        public static MyEventType Run([EventGridTrigger] MyEventType input, FunctionContext context)
        {
            var logger = context.GetLogger(nameof(EventGridFunction));

            logger.LogInformation(input.Data.ToString());

            var outputEvent = new MyEventType()
            {
                Id = "unique-id",
                Subject = "abc-subject",
                Data = new Dictionary<string, object>
                {
                    { "myKey", "myValue" }
                }
            };

            return outputEvent;
        }
    }

    public class MyEventType
    {
        public string Id { get; set; }

        public string Topic { get; set; }

        public string Subject { get; set; }

        public string EventType { get; set; }

        public DateTime EventTime { get; set; }

        public IDictionary<string, object> Data { get; set; }
    }
}

In het volgende voorbeeld ziet u een Java-functie waarmee een bericht naar een aangepast Event Grid-onderwerp wordt geschreven. De functie gebruikt de methode van setValue de binding om een tekenreeks uit te voeren.

public class Function {
    @FunctionName("EventGridTriggerTest")
    public void run(@EventGridTrigger(name = "event") String content,
            @EventGridOutput(name = "outputEvent", topicEndpointUri = "MyEventGridTopicUriSetting", topicKeySetting = "MyEventGridTopicKeySetting") OutputBinding<String> outputEvent,
            final ExecutionContext context) {
        context.getLogger().info("Java EventGrid trigger processed a request." + content);
        final String eventGridOutputDocument = "{\"id\": \"1807\", \"eventType\": \"recordInserted\", \"subject\": \"myapp/cars/java\", \"eventTime\":\"2017-08-10T21:03:07+00:00\", \"data\": {\"make\": \"Ducati\",\"model\": \"Monster\"}, \"dataVersion\": \"1.0\"}";
        outputEvent.setValue(eventGridOutputDocument);
    }
}

U kunt ook een POJO-klasse gebruiken om Event Grid-berichten te verzenden.

public class Function {
    @FunctionName("EventGridTriggerTest")
    public void run(@EventGridTrigger(name = "event") String content,
            @EventGridOutput(name = "outputEvent", topicEndpointUri = "MyEventGridTopicUriSetting", topicKeySetting = "MyEventGridTopicKeySetting") OutputBinding<EventGridEvent> outputEvent,
            final ExecutionContext context) {
        context.getLogger().info("Java EventGrid trigger processed a request." + content);

        final EventGridEvent eventGridOutputDocument = new EventGridEvent();
        eventGridOutputDocument.setId("1807");
        eventGridOutputDocument.setEventType("recordInserted");
        eventGridOutputDocument.setEventTime("2017-08-10T21:03:07+00:00");
        eventGridOutputDocument.setDataVersion("1.0");
        eventGridOutputDocument.setSubject("myapp/cars/java");
        eventGridOutputDocument.setData("{\"make\": \"Ducati\",\"model\":\"monster\"");

        outputEvent.setValue(eventGridOutputDocument);
    }
}

class EventGridEvent {
    private String id;
    private String eventType;
    private String subject;
    private String eventTime;
    private String dataVersion;
    private String data;

    public String getId() {
        return id;
    }

    public String getData() {
        return data;
    }

    public void setData(String data) {
        this.data = data;
    }

    public String getDataVersion() {
        return dataVersion;
    }

    public void setDataVersion(String dataVersion) {
        this.dataVersion = dataVersion;
    }

    public String getEventTime() {
        return eventTime;
    }

    public void setEventTime(String eventTime) {
        this.eventTime = eventTime;
    }

    public String getSubject() {
        return subject;
    }

    public void setSubject(String subject) {
        this.subject = subject;
    }

    public String getEventType() {
        return eventType;
    }

    public void setEventType(String eventType) {
        this.eventType = eventType;
    }

    public void setId(String id) {
        this.id = id;
    }  
}

In het volgende voorbeeld ziet u een door een timer geactiveerde TypeScript-functie die één gebeurtenis uitvoert:

import { app, EventGridPartialEvent, InvocationContext, output, Timer } from '@azure/functions';

export async function timerTrigger1(myTimer: Timer, context: InvocationContext): Promise<EventGridPartialEvent> {
    const timeStamp = new Date().toISOString();
    return {
        id: 'message-id',
        subject: 'subject-name',
        dataVersion: '1.0',
        eventType: 'event-type',
        data: {
            name: 'John Henry',
        },
        eventTime: timeStamp,
    };
}

app.timer('timerTrigger1', {
    schedule: '0 */5 * * * *',
    return: output.eventGrid({
        topicEndpointUri: 'MyEventGridTopicUriSetting',
        topicKeySetting: 'MyEventGridTopicKeySetting',
    }),
    handler: timerTrigger1,
});

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

const timeStamp = new Date().toISOString();
return [
    {
        id: 'message-id',
        subject: 'subject-name',
        dataVersion: '1.0',
        eventType: 'event-type',
        data: {
            name: 'John Henry',
        },
        eventTime: timeStamp,
    },
    {
        id: 'message-id-2',
        subject: 'subject-name',
        dataVersion: '1.0',
        eventType: 'event-type',
        data: {
            name: 'John Doe',
        },
        eventTime: timeStamp,
    },
];

In het volgende voorbeeld ziet u een door een timer geactiveerde JavaScript-functie die één gebeurtenis uitvoert:

const { app, output } = require('@azure/functions');

const eventGridOutput = output.eventGrid({
    topicEndpointUri: 'MyEventGridTopicUriSetting',
    topicKeySetting: 'MyEventGridTopicKeySetting',
});

app.timer('timerTrigger1', {
    schedule: '0 */5 * * * *',
    return: eventGridOutput,
    handler: (myTimer, context) => {
        const timeStamp = new Date().toISOString();
        return {
            id: 'message-id',
            subject: 'subject-name',
            dataVersion: '1.0',
            eventType: 'event-type',
            data: {
                name: 'John Henry',
            },
            eventTime: timeStamp,
        };
    },
});

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

const timeStamp = new Date().toISOString();
return [
    {
        id: 'message-id',
        subject: 'subject-name',
        dataVersion: '1.0',
        eventType: 'event-type',
        data: {
            name: 'John Henry',
        },
        eventTime: timeStamp,
    },
    {
        id: 'message-id-2',
        subject: 'subject-name',
        dataVersion: '1.0',
        eventType: 'event-type',
        data: {
            name: 'John Doe',
        },
        eventTime: timeStamp,
    },
];

In het volgende voorbeeld ziet u hoe u een functie configureert om een Event Grid-gebeurtenisbericht uit te voeren. De sectie waar type is ingesteld om de waarden te eventGrid configureren die nodig zijn om een Event Grid-uitvoerbinding tot stand te brengen.

{
  "bindings": [
    {
      "type": "eventGrid",
      "name": "outputEvent",
      "topicEndpointUri": "MyEventGridTopicUriSetting",
      "topicKeySetting": "MyEventGridTopicKeySetting",
      "direction": "out"
    },
    {
      "authLevel": "anonymous",
      "type": "httpTrigger",
      "direction": "in",
      "name": "Request",
      "methods": [
        "get",
        "post"
      ]
    },
    {
      "type": "http",
      "direction": "out",
      "name": "Response"
    }
  ]
}

Gebruik de Push-OutputBinding functie om een gebeurtenis naar een aangepast onderwerp te verzenden via de Event Grid-uitvoerbinding.

using namespace System.Net

# Input bindings are passed in via param block.
param($Request, $TriggerMetadata)

# Write to the Azure Functions log stream.
Write-Host "PowerShell HTTP trigger function processed a request."

# Interact with query parameters or the body of the request.
$message = $Request.Query.Message

Push-OutputBinding -Name outputEvent -Value  @{
    id = "1"
    eventType = "testEvent"
    subject = "testapp/testPublish"
    eventTime = "2020-08-27T21:03:07+00:00"
    data = @{
        Message = $message
    }
    dataVersion = "1.0"
}

Push-OutputBinding -Name Response -Value ([HttpResponseContext]@{
    StatusCode = 200
    Body = "OK"
})

In het volgende voorbeeld ziet u een triggerbinding en een Python-functie die gebruikmaakt van de binding. Vervolgens wordt een gebeurtenis verzonden naar het aangepaste onderwerp, zoals opgegeven door de topicEndpointUri. Het voorbeeld is afhankelijk van of u het python-programmeermodel v1 of v2 gebruikt.

Dit is de functie in het bestand function_app.py:

import logging
import azure.functions as func
import datetime

app = func.FunctionApp()

@app.function_name(name="eventgrid_output")
@app.event_grid_trigger(arg_name="eventGridEvent")
@app.event_grid_output(
    arg_name="outputEvent",
    topic_endpoint_uri="MyEventGridTopicUriSetting",
    topic_key_setting="MyEventGridTopicKeySetting")
def eventgrid_output(eventGridEvent: func.EventGridEvent, 
         outputEvent: func.Out[func.EventGridOutputEvent]) -> None:

    logging.log("eventGridEvent: ", eventGridEvent)

    outputEvent.set(
        func.EventGridOutputEvent(
            id="test-id",
            data={"tag1": "value1", "tag2": "value2"},
            subject="test-subject",
            event_type="test-event-1",
            event_time=datetime.datetime.utcnow(),
            data_version="1.0"))

Kenmerken

Zowel in-processals 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.

De constructor van het kenmerk gebruikt de naam van een toepassingsinstelling die de naam van het aangepaste onderwerp bevat en de naam van een toepassingsinstelling die de onderwerpsleutel bevat.

In de volgende tabel worden de parameters voor de EventGridOutputAttribute.

Parameter Description
TopicEndpointUri De naam van een app-instelling die de URI voor het aangepaste onderwerp bevat, zoals MyTopicEndpointUri.
TopicKeySetting De naam van een app-instelling die een toegangssleutel voor het aangepaste onderwerp bevat.
verbinding* De waarde van het algemene voorvoegsel voor de instelling die de eindpunt-URI van het onderwerp bevat. Zie Verificatie op basis van identiteiten voor meer informatie over de naamgevingsindeling van deze toepassingsinstelling.

Aantekeningen

Gebruik voor Java-klassen het kenmerk EventGridAttribute .

De constructor van het kenmerk neemt de naam van een app-instelling die de naam van het aangepaste onderwerp bevat en de naam van een app-instelling die de onderwerpsleutel bevat. Zie Uitvoer: configuratie voor meer informatie over deze instellingen. Hier volgt een voorbeeld van een EventGridOutput-kenmerk:

public class Function {
    @FunctionName("EventGridTriggerTest")
    public void run(@EventGridTrigger(name = "event") String content,
            @EventGridOutput(name = "outputEvent", topicEndpointUri = "MyEventGridTopicUriSetting", topicKeySetting = "MyEventGridTopicKeySetting") OutputBinding<String> outputEvent, final ExecutionContext context) {
            ...
    }
}

Configuratie

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

Eigenschappen Beschrijving
topicEndpointUri De naam van een app-instelling die de URI voor het aangepaste onderwerp bevat, zoals MyTopicEndpointUri.
topicKeySetting De naam van een app-instelling die een toegangssleutel voor het aangepaste onderwerp bevat.
verbinding* De waarde van het algemene voorvoegsel voor de instelling die de eindpunt-URI van het onderwerp bevat. Bij het instellen van de connection eigenschap mogen de topicEndpointUri en topicKeySetting eigenschappen niet worden ingesteld. Zie Verificatie op basis van identiteiten voor meer informatie over de naamgevingsindeling van deze toepassingsinstelling.

Configuratie

In de volgende tabel worden de bindingsconfiguratie-eigenschappen uitgelegd die u in het function.json-bestand hebt ingesteld.

function.json-eigenschap Beschrijving
type Moet worden ingesteld op eventGrid.
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.
topicEndpointUri De naam van een app-instelling die de URI voor het aangepaste onderwerp bevat, zoals MyTopicEndpointUri.
topicKeySetting De naam van een app-instelling die een toegangssleutel voor het aangepaste onderwerp bevat.
verbinding* De waarde van het algemene voorvoegsel voor de instelling die de eindpunt-URI van het onderwerp bevat. Zie Verificatie op basis van identiteiten voor meer informatie over de naamgevingsindeling van deze toepassingsinstelling.

*Ondersteuning voor op identiteit gebaseerde verbindingen vereist versie 3.3.x of hoger van de extensie.

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

Belangrijk

Zorg ervoor dat u de waarde instelt op TopicEndpointUri de naam van een app-instelling die de URI van het aangepaste onderwerp bevat. Geef de URI van het aangepaste onderwerp niet rechtstreeks in deze eigenschap op. Hetzelfde geldt voor het gebruik van Connection.

Zie de sectie Voorbeeld voor volledige voorbeelden.

Gebruik

Het parametertype dat wordt ondersteund door de Event Grid-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 Grid-uitvoerbinding worden gekoppeld aan de volgende typen:

Type Description
string De gebeurtenis als een tekenreeks.
byte[] De bytes van het gebeurtenisbericht.
JSON serialiseerbare typen Een object dat een JSON-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 Grid-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 typen van Azure.Messaging.EventGrid .

Afzonderlijke berichten verzenden door een methodeparameter aan te roepen, zoals out EventGridOutput paramName, en meerdere berichten te schrijven met ICollector<EventGridOutput>.

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

Open de uitvoer gebeurtenis met behulp van de Push-OutputBinding cmdlet om een gebeurtenis te verzenden naar de Event Grid-uitvoerbinding.

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

  • Retourwaarde: Stel de name eigenschap in function.json in op $return. Met deze configuratie wordt de retourwaarde van de functie behouden als een Event Grid-bericht.
  • Imperatief: Geef een waarde door aan de ingestelde methode van de parameter die is gedeclareerd als een Out-type . De waarde waaraan wordt doorgegeven set , wordt behouden als een Event Grid-bericht.

Connecties

Er zijn twee manieren om te verifiëren bij een Event Grid-onderwerp wanneer u de Event Grid-uitvoerbinding gebruikt:

Verificatiemethode Beschrijving
Een onderwerpsleutel gebruiken Stel de TopicEndpointUri en TopicKeySetting eigenschappen in, zoals beschreven in Een onderwerpsleutel gebruiken.
Een identiteit gebruiken Stel de Connection eigenschap in op de naam van een gedeeld voorvoegsel voor meerdere toepassingsinstellingen, samen het definiëren van verificatie op basis van identiteiten. Deze methode wordt ondersteund wanneer u versie 3.3.x of hoger van de extensie gebruikt.

Een onderwerpsleutel gebruiken

Gebruik de volgende stappen om een onderwerpsleutel te configureren:

  1. Volg de stappen in Toegangssleutels ophalen om de onderwerpsleutel voor uw Event Grid-onderwerp te verkrijgen.

  2. Maak in de toepassingsinstellingen een instelling waarmee de waarde van de onderwerpsleutel wordt gedefinieerd. Gebruik de naam van deze instelling voor de TopicKeySetting eigenschap van de binding.

  3. Maak in de toepassingsinstellingen een instelling waarmee het onderwerpeindpunt wordt gedefinieerd. Gebruik de naam van deze instelling voor de TopicEndpointUri eigenschap van de binding.

Verificatie op basis van identiteit

Wanneer u versie 3.3.x of hoger van de extensie gebruikt, kunt u verbinding maken met een Event Grid-onderwerp met behulp van een Microsoft Entra-identiteit om te voorkomen dat u onderwerpsleutels moet verkrijgen en gebruiken.

U moet een toepassingsinstelling maken die de eindpunt-URI van het onderwerp retourneert. De naam van de instelling moet een uniek gemeenschappelijk voorvoegsel (bijvoorbeeld myawesometopic) combineren met de waarde __topicEndpointUri. Vervolgens moet u dat algemene voorvoegsel (in dit geval myawesometopic) gebruiken wanneer u de Connection eigenschap in de binding definieert.

In deze modus vereist de extensie de volgende eigenschappen:

Eigenschappen Sjabloon voor omgevingsvariabele Beschrijving Voorbeeldwaarde
Eindpunt-URI onderwerp <CONNECTION_NAME_PREFIX>__topicEndpointUri Het eindpunt van het onderwerp. https://<topic-name>.centralus-1.eventgrid.azure.net/api/events

Er kunnen meer eigenschappen worden gebruikt 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 verbindingen op basis van beheerde identiteiten 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>:topicEndpointUri.

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 Grid-onderwerp. 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
Uitvoerbinding EventGrid-inzender, EventGrid-gegevenszender

Volgende stappen