Výstupní vazba Azure Event Gridu pro Azure Functions

  • Článek

Výstupní vazbu Event Gridu použijte k zápisu událostí do vlastního tématu. Pro vlastní téma musíte mít platný přístupový klíč. Výstupní vazba Event Gridu nepodporuje tokeny sdíleného přístupového podpisu (SAS).

Informace o nastavení a konfiguraci najdete v tématu Jak pracovat s triggery a vazbami Event Gridu ve službě Azure Functions.

Důležité

Tento článek používá karty pro podporu více verzí programovacího modelu Node.js. Model v4 je obecně dostupný a je navržený tak, aby měl flexibilnější a intuitivnější prostředí pro vývojáře v JavaScriptu a TypeScriptu. Další podrobnosti o tom, jak model v4 funguje, najdete v příručce pro vývojáře služby Azure Functions Node.js. Další informace o rozdílech mezi v3 a v4 najdete v průvodci migrací.

Azure Functions podporuje dva programovací modely pro Python. Způsob, jakým definujete vazby, závisí na zvoleném programovacím modelu.

Programovací model Pythonu v2 umožňuje definovat vazby pomocí dekorátorů přímo v kódu funkce Pythonu. Další informace najdete v příručce pro vývojáře Pythonu.

Tento článek podporuje oba programovací modely.

Důležité

Výstupní vazba Event Gridu je dostupná jenom pro Functions 2.x a vyšší.

Příklad

Typ výstupního parametru použitého s výstupní vazbou Event Gridu závisí na verzi modulu runtime functions, verzi rozšíření vazby a způsobu fungování funkce C#. Funkci C# je možné vytvořit pomocí jednoho z následujících režimů jazyka C#:

  • Knihovna tříd v procesu: zkompilovaná funkce jazyka C#, která se spouští ve stejném procesu jako modul runtime služby Functions.
  • Knihovna tříd izolovaného pracovního procesu: zkompilovaná funkce jazyka C#, která běží v pracovním procesu izolovaném od modulu runtime.

Následující příklad ukazuje, jak se vlastní typ používá v triggeru i ve výstupní vazbě Event Gridu:

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

Následující příklad ukazuje funkci Java, která zapisuje zprávu do vlastního tématu Event Gridu. Funkce používá metodu vazby setValue k výstupu řetězce.

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

K odesílání zpráv Event Gridu můžete použít také třídu POJO.

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

Následující příklad ukazuje časovač aktivovanou funkci TypeScript, která vypíše jednu událost:

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

Pokud chcete vytvořit výstup více událostí, vraťte místo jednoho objektu pole. Příklad:

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

Následující příklad ukazuje časovač aktivovanou javascriptovou funkci , která vypíše jednu událost:

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

Pokud chcete vytvořit výstup více událostí, vraťte místo jednoho objektu pole. Příklad:

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

Následující příklad ukazuje, jak nakonfigurovat funkci pro výstup zprávy události Event Gridu. Oddíl, ve kterém type je nastavená eventGrid konfigurace hodnot potřebných k vytvoření výstupní vazby Event Gridu.

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

Ve funkci použijte Push-OutputBinding k odeslání události do vlastního tématu prostřednictvím výstupní vazby Event Gridu.

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

Následující příklad ukazuje vazbu triggeru a funkci Pythonu, která používá vazbu. Pak se odešle v události do vlastního tématu, jak je určeno topicEndpointUri. Tento příklad závisí na tom, jestli používáte programovací model v1 nebo v2 Pythonu.

Tady je funkce v souboru 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"))

Atributy

Knihovny C# v procesu i izolovaného pracovního procesu používají ke konfiguraci vazby atribut. Skript jazyka C# místo toho používá konfigurační soubor function.json, jak je popsáno v průvodci skriptováním jazyka C#.

Konstruktor atributu přebírá název nastavení aplikace, které obsahuje název vlastního tématu, a název nastavení aplikace obsahující klíč tématu.

Následující tabulka vysvětluje parametry .EventGridOutputAttribute

Parametr Popis
Identifikátor TopicEndpointUri Název nastavení aplikace, které obsahuje identifikátor URI pro vlastní téma, například MyTopicEndpointUri.
TopicKeySetting Název nastavení aplikace, které obsahuje přístupový klíč pro vlastní téma.
Připojení* Hodnota společné předpony pro nastavení, které obsahuje identifikátor URI koncového bodu tématu. Další informace o formátu pojmenování tohoto nastavení aplikace naleznete v tématu Ověřování na základě identity.

Poznámky

Pro třídy Java použijte atribut EventGridAttribute .

Konstruktor atributu přebírá název nastavení aplikace, které obsahuje název vlastního tématu, a název nastavení aplikace, které obsahuje klíč tématu. Další informace o těchto nastaveních najdete v tématu Výstup – konfigurace. Tady je příklad atributu EventGridOutput :

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

Konfigurace

Následující tabulka vysvětluje vlastnosti, které můžete nastavit u objektu předaného options metodě output.eventGrid() .

Vlastnost Popis
topicEndpointUri Název nastavení aplikace, které obsahuje identifikátor URI pro vlastní téma, například MyTopicEndpointUri.
topicKeySetting Název nastavení aplikace, které obsahuje přístupový klíč pro vlastní téma.
Připojení* Hodnota společné předpony pro nastavení, které obsahuje identifikátor URI koncového bodu tématu. Při nastavování connection vlastnosti by neměly být nastaveny topicEndpointUri vlastnosti a topicKeySetting vlastnosti. Další informace o formátu pojmenování tohoto nastavení aplikace naleznete v tématu Ověřování na základě identity.

Konfigurace

Následující tabulka vysvětluje vlastnosti konfigurace vazby, které jste nastavili v souboru function.json .

vlastnost function.json Popis
type Musí být nastavena na eventGridhodnotu .
direction Musí být nastavena na outhodnotu . Tento parametr se nastaví automaticky při vytváření vazby na webu Azure Portal.
Jméno Název proměnné použitý v kódu funkce, který představuje událost.
topicEndpointUri Název nastavení aplikace, které obsahuje identifikátor URI pro vlastní téma, například MyTopicEndpointUri.
topicKeySetting Název nastavení aplikace, které obsahuje přístupový klíč pro vlastní téma.
Připojení* Hodnota společné předpony pro nastavení, které obsahuje identifikátor URI koncového bodu tématu. Další informace o formátu pojmenování tohoto nastavení aplikace naleznete v tématu Ověřování na základě identity.

*Podpora připojení založených na identitě vyžaduje verzi 3.3.x nebo vyšší rozšíření.

Při místním vývoji přidejte nastavení aplikace do souboru local.settings.json v kolekci Values .

Důležité

Ujistěte se, že jste nastavili hodnotu TopicEndpointUri na název nastavení aplikace, které obsahuje identifikátor URI vlastního tématu. Nezadávejte identifikátor URI vlastního tématu přímo v této vlastnosti. Totéž platí při použití Connection.

Kompletní příklady najdete v části Příklad.

Využití

Typ parametru podporovaný výstupní vazbou Event Gridu závisí na verzi modulu runtime služby Functions, verzi balíčku rozšíření a použitém režimu jazyka C#.

Pokud chcete, aby funkce zapisuje jednu událost, výstupní vazba Event Gridu může svázat s následujícími typy:

Typ Popis
string Událost jako řetězec.
byte[] Bajty zprávy události.
Serializovatelné typy JSON Objekt představující událost JSON Funkce se pokusí serializovat prostý starý typ objektu CLR (POCO) do dat JSON.

Pokud chcete, aby funkce zapisuje více událostí, výstupní vazba Event Gridu může svázat s následujícími typy:

Typ Popis
T[] where T is one of the single event types Pole obsahující více událostí. Každá položka představuje jednu událost.

V případě jiných výstupních scénářů můžete přímo vytvářet a používat typy z Azure.Messaging.EventGrid .

Odesílat jednotlivé zprávy voláním parametru metody, jako out EventGridOutput paramNameje , a psát více zpráv s ICollector<EventGridOutput>.

Přístup k výstupní zprávě vrácením hodnoty přímo nebo pomocí context.extraOutputs.set().

Přístup k výstupní události pomocí Push-OutputBinding rutiny k odeslání události do výstupní vazby Event Gridu.

Existují dvě možnosti výstupu zprávy Event Gridu z funkce:

  • Návratová hodnota: Nastavte name vlastnost v function.json na $returnhodnotu . Při této konfiguraci se návratová hodnota funkce zachová jako zpráva Event Gridu.
  • Imperativní: Předejte hodnotu metodě sady parametru deklarovaného jako typ Out . Předaná set hodnota je trvalá jako zpráva Event Gridu.

Propojení

Při použití výstupní vazby Event Gridu existují dva způsoby ověřování tématu Event Gridu:

Metoda ověřování Popis
Použití klíče tématu Nastavte vlastnosti TopicEndpointUri a TopicKeySetting vlastnosti, jak je popsáno v části Použití klíče tématu.
Použití identity Connection Nastavte vlastnost na název sdílené předpony pro více nastavení aplikace společně definující ověřování na základě identity. Tato metoda se podporuje při použití verze 3.3.x nebo vyšší rozšíření.

Použití klíče tématu

Pomocí následujících kroků nakonfigurujte klíč tématu:

  1. Postupujte podle kroků v části Získání přístupových klíčů a získejte klíč tématu služby Event Grid.

  2. V nastavení aplikace vytvořte nastavení, které definuje hodnotu klíče tématu. Pro vlastnost vazby použijte název tohoto nastavení TopicKeySetting .

  3. V nastavení aplikace vytvořte nastavení, které definuje koncový bod tématu. Pro vlastnost vazby použijte název tohoto nastavení TopicEndpointUri .

Ověřování na základě identity

Pokud používáte rozšíření verze 3.3.x nebo vyšší, můžete se k tématu Event Gridu připojit pomocí identity Microsoft Entra, abyste nemuseli získávat klíče témat a pracovat s nich.

Musíte vytvořit nastavení aplikace, které vrátí identifikátor URI koncového bodu tématu. Název nastavení by měl sloučit jedinečnou společnou předponu (například myawesometopic) s hodnotou __topicEndpointUri. Pak musíte použít tuto společnou předponu (v tomto případě myawesometopic) při definování Connection vlastnosti v vazbě.

V tomto režimu rozšíření vyžaduje následující vlastnosti:

Vlastnost Šablona proměnné prostředí Popis Příklad hodnoty
Identifikátor URI koncového bodu tématu <CONNECTION_NAME_PREFIX>__topicEndpointUri Koncový bod tématu. https://<topic-name>.centralus-1.eventgrid.azure.net/api/events

K přizpůsobení připojení je možné použít další vlastnosti. Viz Běžné vlastnosti pro připojení založená na identitě.

Poznámka:

Při použití konfigurace Aplikace Azure nebo služby Key Vault k poskytnutí nastavení pro připojení založená na spravované identitě by názvy nastavení měly používat platný oddělovač klíčů, například : místo / názvu__, aby se názvy správně přeložily.

Například <CONNECTION_NAME_PREFIX>:topicEndpointUri.

Při hostovaní ve službě Azure Functions používají připojení založená na identitách spravovanou identitu. Identita přiřazená systémem se používá ve výchozím nastavení, i když je možné zadat identitu přiřazenou uživatelem s vlastnostmi a clientID vlastnostmicredential. Všimněte si, že konfigurace identity přiřazené uživatelem s ID prostředku se nepodporuje . Při spuštění v jiných kontextech, jako je místní vývoj, se místo toho použije vaše identita vývojáře, i když je možné ji přizpůsobit. Viz Místní vývoj s připojeními založenými na identitách.

Udělení oprávnění identitě

Jakákoli identita, kterou používáte, musí mít oprávnění k provedení zamýšlených akcí. U většiny služeb Azure to znamená, že potřebujete přiřadit roli v Azure RBAC pomocí předdefinovaných nebo vlastních rolí, které tato oprávnění poskytují.

Důležité

Cílová služba může zpřístupnit některá oprávnění, která nejsou nutná pro všechny kontexty. Pokud je to možné, dodržujte zásadu nejnižšího oprávnění a udělte identitě pouze požadovaná oprávnění. Pokud například aplikace potřebuje jen číst ze zdroje dat, použijte roli, která má oprávnění jen ke čtení. Přiřazení role, která také umožňuje zápis do této služby, by bylo nevhodné, protože by to bylo nadměrné oprávnění pro operaci čtení. Podobně byste chtěli zajistit, aby přiřazení role bylo vymezeno pouze nad prostředky, které je potřeba číst.

Musíte vytvořit přiřazení role, které poskytuje přístup k tématu Event Gridu za běhu. Role správy, jako je vlastník , nestačí. Následující tabulka ukazuje předdefinované role, které se doporučují při použití rozšíření Event Hubs v normálním provozu. Vaše aplikace může vyžadovat další oprávnění na základě kódu, který napíšete.

Typ vazby Příklad předdefinovaných rolí
Výstupní vazba Přispěvatel EventGrid, odesílatel dat EventGrid

Další kroky