Azure Event Grid-utdatabindning för Azure Functions

  • Artikel

Använd Event Grid-utdatabindningen för att skriva händelser till ett anpassat ämne. Du måste ha en giltig åtkomstnyckel för det anpassade ämnet. Event Grid-utdatabindningen stöder inte sas-token (signatur för delad åtkomst).

Information om konfiguration och konfigurationsinformation finns i Så här fungerar du med Event Grid-utlösare och bindningar i Azure Functions.

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.

Viktigt!

Event Grid-utdatabindningen är endast tillgänglig för Functions 2.x och senare.

Exempel

Vilken typ av utdataparameter som används med en Event Grid-utdatabindning beror på functions-körningsversionen, bindningstilläggsversionen och modaliteten för C#-funktionen. C#-funktionen kan skapas med något av följande C#-lägen:

I följande exempel visas hur den anpassade typen används i både utlösaren och en Event Grid-utdatabindning:

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

I följande exempel visas en Java-funktion som skriver ett meddelande till ett anpassat Event Grid-ämne. Funktionen använder bindningens setValue metod för att mata ut en sträng.

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

Du kan också använda en POJO-klass för att skicka Event Grid-meddelanden.

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

I följande exempel visas en timerutlöst TypeScript-funktion som matar ut en enskild händelse:

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

Om du vill mata ut flera händelser returnerar du en matris i stället för ett enda objekt. Till exempel:

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

I följande exempel visas en timerutlöst JavaScript-funktion som matar ut en enskild händelse:

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

Om du vill mata ut flera händelser returnerar du en matris i stället för ett enda objekt. Till exempel:

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

I följande exempel visas hur du konfigurerar en funktion för att mata ut ett Event Grid-händelsemeddelande. Avsnittet där type är inställt på konfigurerar eventGrid de värden som behövs för att upprätta en Event Grid-utdatabindning.

{
  "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"
    }
  ]
}

I din funktion använder du Push-OutputBinding för att skicka en händelse till ett anpassat ämne via Event Grid-utdatabindningen.

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

I följande exempel visas en utlösarbindning och en Python-funktion som använder bindningen. Den skickar sedan i en händelse till det anpassade ämnet, enligt vad som anges av topicEndpointUri. Exemplet beror på om du använder python-programmeringsmodellen v1 eller v2.

Här är funktionen i filen 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"))

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.

Attributets konstruktor tar namnet på en programinställning som innehåller namnet på det anpassade ämnet och namnet på en programinställning som innehåller ämnesnyckeln.

I följande tabell förklaras parametrarna EventGridOutputAttributeför .

Parameter Description
TopicEndpointUri Namnet på en appinställning som innehåller URI:n för det anpassade ämnet, till exempel MyTopicEndpointUri.
TopicKeySetting Namnet på en appinställning som innehåller en åtkomstnyckel för det anpassade ämnet.
Anslutning* Värdet för det gemensamma prefixet för inställningen som innehåller ämnets slutpunkts-URI. Mer information om namngivningsformatet för den här programinställningen finns i Identitetsbaserad autentisering.

Kommentarer

För Java-klasser använder du attributet EventGridAttribute .

Attributets konstruktor tar namnet på en appinställning som innehåller namnet på det anpassade ämnet och namnet på en appinställning som innehåller ämnesnyckeln. Mer information om de här inställningarna finns i Utdata – konfiguration. Här är ett EventGridOutput attributexempel:

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) {
            ...
    }
}

Konfiguration

I följande tabell förklaras de egenskaper som du kan ange för objektet options som skickas output.eventGrid() till metoden.

Property beskrivning
topicEndpointUri Namnet på en appinställning som innehåller URI:n för det anpassade ämnet, till exempel MyTopicEndpointUri.
topicKeySetting Namnet på en appinställning som innehåller en åtkomstnyckel för det anpassade ämnet.
Anslutning* Värdet för det gemensamma prefixet för inställningen som innehåller ämnets slutpunkts-URI. När du ställer in connection egenskapen topicEndpointUri ska egenskaperna och topicKeySetting inte anges. Mer information om namngivningsformatet för den här programinställningen finns i Identitetsbaserad autentisering.

Konfiguration

I följande tabell förklaras de bindningskonfigurationsegenskaper som du anger i filen function.json .

function.json egenskap beskrivning
typ Måste anges till eventGrid.
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.
topicEndpointUri Namnet på en appinställning som innehåller URI:n för det anpassade ämnet, till exempel MyTopicEndpointUri.
topicKeySetting Namnet på en appinställning som innehåller en åtkomstnyckel för det anpassade ämnet.
Anslutning* Värdet för det gemensamma prefixet för inställningen som innehåller ämnets slutpunkts-URI. Mer information om namngivningsformatet för den här programinställningen finns i Identitetsbaserad autentisering.

*Stöd för identitetsbaserade anslutningar kräver version 3.3.x eller senare av tillägget.

När du utvecklar lokalt lägger du till dina programinställningar i den local.settings.json filen i Values samlingen.

Viktigt!

Kontrollera att du anger värdet TopicEndpointUri för till namnet på en appinställning som innehåller URI:n för det anpassade ämnet. Ange inte URI för det anpassade ämnet direkt i den här egenskapen. Samma sak gäller när du använder Connection.

Se avsnittet Exempel för fullständiga exempel.

Användning

Vilken parametertyp som stöds av Event Grid-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 Grid-utdatabindningen binda till följande typer:

Typ Beskrivning
string Händelsen som en sträng.
byte[] Byte för händelsemeddelandet.
JSON-serialiserbara typer Ett objekt som representerar en JSON-händelse. 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 Grid-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 Azure.Messaging.EventGrid direkt.

Skicka enskilda meddelanden genom att anropa en metodparameter som out EventGridOutput paramName, och skriva flera meddelanden med ICollector<EventGridOutput>.

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

Få åtkomst till utdatahändelsen med hjälp av cmdleten Push-OutputBinding för att skicka en händelse till Event Grid-utdatabindningen.

Det finns två alternativ för att mata ut ett Event Grid-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 Grid-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 Grid-meddelande.

anslutningar

Det finns två sätt att autentisera till ett Event Grid-ämne när du använder Event Grid-utdatabindningen:

Autentiseringsmetod beskrivning
Använda en ämnesnyckel Ange egenskaperna och TopicKeySetting enligt beskrivningen TopicEndpointUri i Använd en ämnesnyckel.
Använda en identitet Connection Ange egenskapen till namnet på ett delat prefix för flera programinställningar och definiera identitetsbaserad autentisering tillsammans. Den här metoden stöds när du använder version 3.3.x eller senare av tillägget.

Använda en ämnesnyckel

Använd följande steg för att konfigurera en ämnesnyckel:

  1. Följ stegen i Hämta åtkomstnycklar för att hämta ämnesnyckeln för ditt Event Grid-ämne.

  2. I programinställningarna skapar du en inställning som definierar ämnesnyckelvärdet. Använd namnet på den här inställningen för bindningens TopicKeySetting egenskap.

  3. I programinställningarna skapar du en inställning som definierar ämnesslutpunkten. Använd namnet på den här inställningen för bindningens TopicEndpointUri egenskap.

Identitetsbaserad autentisering

När du använder version 3.3.x eller senare av tillägget kan du ansluta till ett Event Grid-ämne med hjälp av en Microsoft Entra-identitet för att undvika att behöva hämta och arbeta med ämnesnycklar.

Du måste skapa en programinställning som returnerar ämnets slutpunkts-URI. Namnet på inställningen ska kombinera ett unikt gemensamt prefix (till exempel myawesometopic) med värdet __topicEndpointUri. Sedan måste du använda det vanliga prefixet (i det här fallet myawesometopic) när du definierar Connection egenskapen i bindningen.

I det här läget kräver tillägget följande egenskaper:

Property Miljövariabelmall beskrivning Exempelvärde
Ämnesslutpunkts-URI <CONNECTION_NAME_PREFIX>__topicEndpointUri Ämnesslutpunkten. https://<topic-name>.centralus-1.eventgrid.azure.net/api/events

Fler egenskaper kan användas 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 identitetsbaserade anslutningar 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>:topicEndpointUri

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 event grid-ämnet vid körning. 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
Utdatabindning EventGrid-deltagare, EventGrid-datasändare

Nästa steg