Azure Event Grid-Trigger für Azure Functions

Der Funktionstrigger kann verwendet werden, um auf ein Ereignis zu reagieren, das an eine Event Grid-Quelle gesendet wird. Sie müssen über ein Ereignisabonnement für die Quelle verfügen, um Ereignisse zu empfangen. Informationen zum Erstellen eines Ereignisabonnements finden Sie unter Erstellen eines Abonnements. Informationen zum Bindungssetup und zur Konfiguration finden Sie in der Übersicht.

Hinweis

Event Grid-Trigger werden in einer ILB-ASE (Internal Load Balancer App Service Environment, App Service-Umgebung für internen Lastenausgleich) nicht nativ unterstützt. Der Trigger verwendet eine HTTP-Anforderung, die die Funktions-App ohne Gateway zum virtuellen Netzwerk nicht erreichen kann.

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

Ein Beispiel für einen HTTP-Trigger finden Sie unter Empfangen von Ereignissen an einem HTTP-Endpunkt.

Der Typ des Eingabeparameters, der mit einem Event Grid-Trigger verwendet wird, hängt von drei Faktoren ab:

  • Version der Functions-Laufzeit
  • Version der Bindungserweiterung
  • Modalität der C#-Funktion

Eine C#-Funktion kann mit einem der folgenden C#-Modi erstellt werden:

  • Isoliertes Workermodell: Kompilierte C#-Funktion, die in einem Workerprozess ausgeführt wird, der von der Runtime isoliert ist. Ein isolierter Workerprozess ist erforderlich, um C#-Funktionen zu unterstützen, die in LTS- und Nicht-LTS-Versionen von .NET und .NET Framework ausgeführt werden. Erweiterungen für isolierte Workerprozessfunktionen verwenden Microsoft.Azure.Functions.Worker.Extensions.*-Namespaces.
  • In-Process-Modell: Kompilierte C#-Funktion, die im gleichen Prozess wie die Functions-Runtime ausgeführt wird. In einer Variante dieses Modells kann Functions mithilfe von C#-Skripts ausgeführt werden. Dies wird hauptsächlich für die Bearbeitung im C#-Portal unterstützt. Erweiterungen für In-Process-Funktionen verwenden Microsoft.Azure.WebJobs.Extensions.*-Namespaces.

Wenn Sie Ihre C#-Funktion in einem isolierten Workerprozess ausführen, müssen Sie einen benutzerdefinierten Typ für Ereigniseigenschaften definieren. Im folgenden Beispiel wird eine Klasse vom Typ MyEventType definiert:

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

Das folgende Beispiel zeigt, wie der benutzerdefinierte Typ sowohl im Trigger als auch in einer Event Grid-Ausgabebindung verwendet wird:

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

Dieser Abschnitt enthält folgende Beispiele:

Die folgenden Beispiele zeigen die Triggerbindung in Java, das die Bindung verwendet und ein Ereignis generiert. Dabei wird das Ereignis erst als String und dann als POJO empfangen:

Event Grid-Trigger, String-Parameter

  @FunctionName("eventGridMonitorString")
  public void logEvent(
    @EventGridTrigger(
      name = "event"
    )
    String content,
    final ExecutionContext context) {
      context.getLogger().info("Event content: " + content);
  }

Event Grid-Trigger, POJO-Parameter

In diesem Beispiel werden die folgenden POJO verwendet, die die Eigenschaften der obersten Ebene eines Event Grid-Ereignisses darstellen:

import java.util.Date;
import java.util.Map;

public class EventSchema {

  public String topic;
  public String subject;
  public String eventType;
  public Date eventTime;
  public String id;
  public String dataVersion;
  public String metadataVersion;
  public Map<String, Object> data;

}

Beim Eingang wird die JSON-Nutzlast des Ereignisses in das EventSchema-POJO deserialisiert, damit dieses von der Funktion verwendet werden kann. Durch diesen Prozess kann die Funktion auf die Ereigniseigenschaften auf objektorientierte Weise zugreifen.

  @FunctionName("eventGridMonitor")
  public void logEvent(
    @EventGridTrigger(
      name = "event"
    )
    EventSchema event,
    final ExecutionContext context) {
      context.getLogger().info("Event content: ");
      context.getLogger().info("Subject: " + event.subject);
      context.getLogger().info("Time: " + event.eventTime); // automatically converted to Date by the runtime
      context.getLogger().info("Id: " + event.id);
      context.getLogger().info("Data: " + event.data);
  }

Verwenden Sie die EventGridTrigger-Anmerkung in der Laufzeitbibliothek für Java-Funktionen für Parameter, deren Wert von Event Grid empfangen wird. Parameter mit diesen Anmerkungen führen dazu, dass die Funktion ausgeführt wird, wenn ein Ereignis empfangen wird. Diese Anmerkung kann mit nativen Java-Typen, POJOs oder Werten mit Optional<T>, die NULL-Werte annehmen können, verwendet werden.

Das folgende Beispiel zeigt eine TypeScript-Funktion für den Event Grid-Trigger.

import { app, EventGridEvent, InvocationContext } from '@azure/functions';

export async function eventGridTrigger1(event: EventGridEvent, context: InvocationContext): Promise<void> {
    context.log('Event grid function processed event:', event);
}

app.eventGrid('eventGridTrigger1', {
    handler: eventGridTrigger1,
});

Das folgende Beispiel zeigt eine JavaScript-Funktion für den Event Grid-Trigger.

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

app.eventGrid('eventGridTrigger1', {
    handler: (event, context) => {
        context.log('Event grid function processed event:', event);
    },
});

Im folgenden Beispiel wird gezeigt, wie eine Event Grid-Triggerbindung in der Datei function.json konfiguriert wird.

{
  "bindings": [
    {
      "type": "eventGridTrigger",
      "name": "eventGridEvent",
      "direction": "in"
    }
  ]
}

Das Event Grid-Ereignis wird der Funktion über den Parameter eventGridEvent bereitgestellt, wie im folgenden PowerShell-Beispiel gezeigt.

param($eventGridEvent, $TriggerMetadata)

# Make sure to pass hashtables to Out-String so they're logged correctly
$eventGridEvent | Out-String | Write-Host

Das folgende Beispiel zeigt eine Event Grid-Triggerbindung sowie eine Python-Funktion, die die Bindung verwendet. Das Beispiel hängt davon ab, ob Sie das Python-Programmiermodell v1 oder v2 verwenden.

import logging
import json
import azure.functions as func

app = func.FunctionApp()

@app.function_name(name="eventGridTrigger")
@app.event_grid_trigger(arg_name="event")
def eventGridTest(event: func.EventGridEvent):
    result = json.dumps({
        'id': event.id,
        'data': event.get_json(),
        'topic': event.topic,
        'subject': event.subject,
        'event_type': event.event_type,
    })

    logging.info('Python EventGrid trigger processed an event: %s', result)

Attribute

Sowohl von C#-Bibliotheken des Typs In-Process als auch des Typs Isolierter Workerprozess wird das Attribut EventGridTrigger verwendet. Das C#-Skript verwendet stattdessen eine Konfigurationsdatei function.json, wie im C#-Skript-Handbuch beschrieben.

Dies ist ein EventGridTrigger-Attribut in einer Methodensignatur:

[Function(nameof(EventGridFunction))]
[EventGridOutput(TopicEndpointUri = "MyEventGridTopicUriSetting", TopicKeySetting = "MyEventGridTopicKeySetting")]
public static MyEventType Run([EventGridTrigger] MyEventType input, FunctionContext context)
{

Anmerkungen

Mit der EventGridTrigger-Anmerkung können Sie eine Event Grid-Bindung deklarativ konfigurieren, indem Sie Konfigurationswerte bereitstellen. Weitere Details finden Sie in den Abschnitten Beispiel und Konfiguration.

Konfiguration

Das an die app.eventGrid()-Methode übergebene options-Objekt unterstützt derzeit keine Eigenschaften für das Modell v4.

Konfiguration

Die folgende Tabelle gibt Aufschluss über die Bindungskonfigurationseigenschaften, die Sie in der Datei function.json festlegen. Im Attribut EventGridTrigger müssen keine Konstruktorparameter oder -eigenschaften festgelegt werden.

Eigenschaft von „function.json“ BESCHREIBUNG
type Erforderlich – muss auf eventGridTrigger festgelegt sein.
direction Erforderlich – muss auf in festgelegt sein.
name Erforderlich – der Variablenname, der im Funktionscode für den Parameter verwendet wird, der die Ereignisdaten empfängt.

Vollständige Beispiele finden Sie im Abschnitt „Beispiele“.

Verwendung

Der Event Grid-Trigger verwendet eine Webhook-HTTP-Anforderung, die mit den gleichen host.json-Einstellungen wie der HTTP-Trigger konfiguriert werden kann.

Der vom Event Grid-Trigger unterstützte Parametertyp hängt von der Runtimeversion von Functions, von der Version des Erweiterungspakets sowie von der verwendeten C#-Modalität ab.

Wenn die Funktion ein einzelnes Ereignis verarbeiten soll, kann der Event Grid-Trigger an die folgenden Typen gebunden werden:

type BESCHREIBUNG
Serialisierbare JSON-Typen Functions versucht, die JSON-Daten des Ereignisses in einen POCO-Typ (Plain-Old CLR Object) zu deserialisieren.
string Das Ereignis als Zeichenfolge.
BinaryData1 Die Bytes der Ereignisnachricht.
CloudEvent1 Das Ereignisobjekt. Verwenden Sie dieses Objekt, wenn Event Grid für die Übermittlung mithilfe des CloudEvents-Schemas konfiguriert ist.
EventGridEvent1 Das Ereignisobjekt. Verwenden Sie dieses Objekt, wenn Event Grid für die Übermittlung mithilfe des Event Grid-Schemas konfiguriert ist.

Wenn die Funktion einen Ereignisbatch verarbeiten soll, kann der Event Grid-Trigger an die folgenden Typen gebunden werden:

type BESCHREIBUNG
CloudEvent[]1,
EventGridEvent[]1,
string[],
BinaryData[]1
Ein Array von Ereignissen aus dem Batch. Jeder Eintrag stellt ein Ereignis dar.

1 Um diese Typen zu verwenden, müssen Sie auf Microsoft.Azure.Functions.Worker.Extensions.EventGrid 3.3.0 oder höher und die gemeinsamen Abhängigkeiten für SDK-Typbindungen verweisen.

Die Event Grid-Ereignisinstanz ist über den Parameter verfügbar, der dem als EventSchema typisierten EventGridTrigger-Attribut zugeordnet ist.

Die Event Grid-Instanz ist über den Parameter verfügbar, der in der name-Eigenschaft der function.json-Datei konfiguriert ist.

Die Event Grid-Instanz ist über den Parameter verfügbar, der in der als func.EventGridEvent typisierten name-Eigenschaft der function.json-Datei konfiguriert ist.

Ereignisschema

Daten für ein Event Grid-Ereignis werden als JSON-Objekt im Text einer HTTP-Anforderung empfangen. Das JSON-Objekt ähnelt dem folgenden Beispiel:

[{
  "topic": "/subscriptions/{subscriptionid}/resourceGroups/eg0122/providers/Microsoft.Storage/storageAccounts/egblobstore",
  "subject": "/blobServices/default/containers/{containername}/blobs/blobname.jpg",
  "eventType": "Microsoft.Storage.BlobCreated",
  "eventTime": "2018-01-23T17:02:19.6069787Z",
  "id": "{guid}",
  "data": {
    "api": "PutBlockList",
    "clientRequestId": "{guid}",
    "requestId": "{guid}",
    "eTag": "0x8D562831044DDD0",
    "contentType": "application/octet-stream",
    "contentLength": 2248,
    "blobType": "BlockBlob",
    "url": "https://egblobstore.blob.core.windows.net/{containername}/blobname.jpg",
    "sequencer": "000000000000272D000000000003D60F",
    "storageDiagnostics": {
      "batchId": "{guid}"
    }
  },
  "dataVersion": "",
  "metadataVersion": "1"
}]

Das Beispiel stellt ein Array mit einem Element dar. Event Grid sendet immer ein Array und kann mehrere Ereignisse im Array senden. Die Runtime ruft die Funktion einmal für jedes Arrayelement auf.

Die Eigenschaften der obersten Ebene in den JSON-Ereignisdaten sind für alle Ereignistypen identisch, die Inhalte der Eigenschaft data sind dagegen für jeden Ereignistyp spezifisch. Das Beispiel oben bezieht sich auf ein Blob Storage-Ereignis.

Erläuterungen zu den allgemeinen und ereignisspezifischen Eigenschaften finden Sie unter Ereigniseigenschaften in der Event Grid-Dokumentation.

Nächste Schritte