Azure Event Grid utlösare för Azure Functions

Använd funktionsutlösaren för att svara på en händelse som skickats till ett Event Grid ämne.

Information om installation och konfiguration finns i översikten.

Anteckning

Event Grid-utlösare stöds inte internt i en intern lastbalanserare App Service-miljön. Utlösaren använder en HTTP-begäran som inte kan nå funktionsappen utan en gateway till det virtuella nätverket.

Exempel

Ett exempel på HTTP-utlösare finns i Ta emot händelser till en HTTP-slutpunkt.

Version 3.x

I följande exempel visas en Functions 3.x C#-funktion som binder till en CloudEvent :

using Azure.Messaging;
using Microsoft.Azure.WebJobs;
using Microsoft.Azure.WebJobs.Extensions.EventGrid;
using Microsoft.Extensions.Logging;

namespace Company.Function
{
    public static class CloudEventTriggerFunction
    {
        [FunctionName("CloudEventTriggerFunction")]
        public static void Run(
            ILogger logger,
            [EventGridTrigger] CloudEvent e)
        {
            logger.LogInformation("Event received {type} {subject}", e.Type, e.Subject);
        }
    }
}

I följande exempel visas en Functions 3.x C#-funktion som binder till en EventGridEvent :

using Microsoft.Azure.WebJobs;
using Microsoft.Azure.WebJobs.Extensions.EventGrid;
using Azure.Messaging.EventGrid;
using Microsoft.Extensions.Logging;

namespace Company.Function
{
    public static class EventGridEventTriggerFunction
    {
        [FunctionName("EventGridEventTriggerFunction")]
        public static void Run(
            ILogger logger,
            [EventGridTrigger] EventGridEvent e)
        {
            logger.LogInformation("Event received {type} {subject}", e.EventType, e.Subject);
        }
    }
}

C# (2.x och senare)

I följande exempel visas en C#-funktion som binder till EventGridEvent :

using System;
using Microsoft.Azure.WebJobs;
using Microsoft.Azure.WebJobs.Host;
using Microsoft.Azure.EventGrid.Models;
using Microsoft.Azure.WebJobs.Extensions.EventGrid;
using Microsoft.Extensions.Logging;

namespace Company.Function
{
    public static class EventGridTriggerDemo
    {
        [FunctionName("EventGridTriggerDemo")]
        public static void Run([EventGridTrigger]EventGridEvent eventGridEvent, ILogger log)
        {
            log.LogInformation(eventGridEvent.Data.ToString());
        }
    }
}

Mer information finns i Paket, Attribut, Konfigurationoch Användning.

Version 1.x

I följande exempel visas en Functions 1.x C#-funktion som binder till JObject :

using Microsoft.Azure.WebJobs;
using Microsoft.Azure.WebJobs.Extensions.EventGrid;
using Microsoft.Azure.WebJobs.Host;
using Newtonsoft.Json;
using Newtonsoft.Json.Linq;
using Microsoft.Extensions.Logging;

namespace Company.Function
{
    public static class EventGridTriggerCSharp
    {
        [FunctionName("EventGridTriggerCSharp")]
        public static void Run([EventGridTrigger]JObject eventGridEvent, ILogger log)
        {
            log.LogInformation(eventGridEvent.ToString(Formatting.Indented));
        }
    }
}

Attribut och anteckningar

I C#-klassbibliotekanvänder du attributet EventGridTrigger.

Här är ett attribut EventGridTrigger i en metodsignatur:

[FunctionName("EventGridTest")]
public static void EventGridTest([EventGridTrigger] JObject eventGridEvent, ILogger log)
{
    ...
}

Ett komplett exempel finns i C#-exempel.

Konfiguration

I följande tabell beskrivs de bindningskonfigurationsegenskaper som du anger ifunction.jspå filen. Det finns inga konstruktorparametrar eller egenskaper att ange i EventGridTrigger attributet.

function.jspå egenskapen Beskrivning
Typ Obligatoriskt – måste anges till eventGridTrigger .
riktning Obligatoriskt – måste anges till in .
Namn Obligatoriskt – variabelnamnet som används i funktionskoden för den parameter som tar emot händelsedata.

Användning

I Azure Functions 1.x kan du använda följande parametertyper för den Event Grid utlösaren:

  • JObject
  • string

I Azure Functions 2.x och senare har du också möjlighet att använda följande parametertyp för Event Grid utlösaren:

  • Microsoft.Azure.EventGrid.Models.EventGridEvent– Definierar egenskaper för de fält som är gemensamma för alla händelsetyper.

Anteckning

Om du försöker binda till Microsoft.Azure.WebJobs.Extensions.EventGrid.EventGridEvent visar kompilatorn ett "inaktuellt" meddelande och rekommenderar att du använder Microsoft.Azure.EventGrid.Models.EventGridEvent i stället. Om du vill använda den nyare typen refererar du till Microsoft.Azure.EventGrid NuGet-paketet och kvalificerar typnamnet fullständigt genom EventGridEvent att lägga till prefixet Microsoft.Azure.EventGrid.Models .

Ytterligare typer

Appar som använder version 3.0.0 eller senare av Event Grid-tillägget använder typen från EventGridEvent namnområdet Azure.Messaging.EventGrid. Dessutom kan du binda till typen CloudEvent från namnområdet Azure.Messaging.

Händelseschema

Data för en Event Grid-händelse tas emot som ett JSON-objekt i brödtexten i en HTTP-begäran. JSON ser ut ungefär som i följande exempel:

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

Exemplet som visas är en matris med ett element. Event Grid alltid en matris och kan skicka fler än en händelse i matrisen. Körningen anropar din funktion en gång för varje matriselement.

Egenskaperna på den översta nivån i händelse-JSON-data är desamma för alla händelsetyper, medan innehållet i data egenskapen är specifikt för varje händelsetyp. Exemplet som visas är för en Blob Storage-händelse.

Förklaringar av vanliga och händelsespecifika egenskaper finns i Händelseegenskaper i Event Grid dokumentationen.

Typen EventGridEvent definierar bara egenskaperna på den översta nivån. Data Egenskapen är en JObject .

Skapa en prenumeration

Börja ta emot Event Grid HTTP-begäranden genom att Event Grid en prenumeration som anger den slutpunkts-URL som anropar funktionen.

Azure Portal

För funktioner som du utvecklar i Azure Portal med Event Grid-utlösaren väljer du Integration och sedan Event Grid Utlösare och sedan Skapa Event Grid prenumeration.

Anslut en ny händelseprenumeration som ska utlösas i portalen.

När du väljer den här länken öppnar portalen sidan Skapa händelseprenumeration med den aktuella utlösarslutpunkten redan definierad.

Skapa händelseprenumeration med funktionsslutpunkten redan definierad

Mer information om hur du skapar prenumerationer med hjälp av Azure Portal finns i Skapa anpassad händelse – Azure Portal i Event Grid dokumentationen.

Azure CLI

Om du vill skapa en prenumeration med hjälp av Azure CLIanvänder du kommandot az eventgrid event-subscription create.

Kommandot kräver slutpunkts-URL:en som anropar funktionen. I följande exempel visas det versionsspecifika URL-mönstret:

Körningsversion 2.x (och senare)

https://{functionappname}.azurewebsites.net/runtime/webhooks/eventgrid?functionName={functionname}&code={systemkey}

Version 1.x runtime

https://{functionappname}.azurewebsites.net/admin/extensions/EventGridExtensionConfig?functionName={functionname}&code={systemkey}

Systemnyckeln är en auktoriseringsnyckel som måste inkluderas i slutpunkts-URL:en för en Event Grid utlösare. I följande avsnitt beskrivs hur du hämtar systemnyckeln.

Här är ett exempel som prenumererar på ett bloblagringskonto (med en platshållare för systemnyckeln):

Körningsversion 2.x (och senare)

az eventgrid resource event-subscription create -g myResourceGroup \
    --provider-namespace Microsoft.Storage --resource-type storageAccounts \
    --resource-name myblobstorage12345 --name myFuncSub \
    --included-event-types Microsoft.Storage.BlobCreated \
    --subject-begins-with /blobServices/default/containers/images/blobs/ \
    --endpoint https://mystoragetriggeredfunction.azurewebsites.net/runtime/webhooks/eventgrid?functionName=imageresizefunc&code=<key>

Version 1.x runtime

az eventgrid resource event-subscription create -g myResourceGroup \
    --provider-namespace Microsoft.Storage --resource-type storageAccounts \
    --resource-name myblobstorage12345 --name myFuncSub \
    --included-event-types Microsoft.Storage.BlobCreated \
    --subject-begins-with /blobServices/default/containers/images/blobs/ \
    --endpoint https://mystoragetriggeredfunction.azurewebsites.net/admin/extensions/EventGridExtensionConfig?functionName=imageresizefunc&code=<key>

Mer information om hur du skapar en prenumeration finns i snabbstarten för bloblagring eller andra Event Grid snabbstarter.

Hämta systemnyckeln

Du kan hämta systemnyckeln med hjälp av följande API (HTTP GET):

Körningsversion 2.x (och senare)

http://{functionappname}.azurewebsites.net/admin/host/systemkeys/eventgrid_extension?code={masterkey}

Version 1.x runtime

http://{functionappname}.azurewebsites.net/admin/host/systemkeys/eventgridextensionconfig_extension?code={masterkey}

Det här är ett administratörs-API, så det kräver din huvudnyckel för funktionsappen. Blanda inte ihop systemnyckeln (för att aktivera en Event Grid utlösarfunktion) med huvudnyckeln (för att utföra administrativa uppgifter i funktionsappen). När du prenumererar på Event Grid bör du använda systemnyckeln.

Här är ett exempel på svaret som tillhandahåller systemnyckeln:

{
  "name": "eventgridextensionconfig_extension",
  "value": "{the system key for the function}",
  "links": [
    {
      "rel": "self",
      "href": "{the URL for the function, without the system key}"
    }
  ]
}

Du kan hämta huvudnyckeln för funktionsappen på fliken Funktionsappinställningar i portalen.

Viktigt

Huvudnyckeln ger administratörsåtkomst till din funktionsapp. Dela inte den här nyckeln med tredje part eller distribuera den i interna klientprogram.

Mer information finns i Auktoriseringsnycklar i referensartikeln om HTTP-utlösare.

Du kan också skicka en HTTP PUT för att ange nyckelvärdet själv.

Lokal testning med visningswebbapp

Om du vill Event Grid en utlösare lokalt måste du få Event Grid HTTP-begäranden som levereras från deras ursprung i molnet till din lokala dator. Ett sätt att göra det är att samla in begäranden online och manuellt skicka dem på den lokala datorn:

  1. Skapa en visningswebbapp som samlar in händelsemeddelanden.
  2. Skapa en Event Grid prenumeration som skickar händelser till visningsappen.
  3. Generera en begäran och kopiera begärandetexten från visningsappen.
  4. Publicera begäran manuellt till localhost-URL:en för din Event Grid utlösarfunktion.

När du är klar med testningen kan du använda samma prenumeration för produktion genom att uppdatera slutpunkten. Använd Azure CLI-kommandot az eventgrid event-subscription update.

Skapa en visningswebbapp

Du kan förenkla insamlingen av händelsemeddelanden genom att distribuera en färdig webbapp som visar händelsemeddelandena. Den distribuerade lösningen innehåller en App Service-plan,en webbapp för App Service och källkod från GitHub.

Välj Deploy to Azure (Distribuera till Azure) för att distribuera lösningen till din prenumeration. Ange parametervärdena i Azure Portal.

Button to Deploy to Azure.

Det kan ta några minuter att slutföra distributionen. Efter distributionen har slutförts kan du visa webbappen för att kontrollera att den körs. I en webbläsare navigerar du till: https://<your-site-name>.azurewebsites.net

Du ser webbplatsen men det har inte publicerats händelser till den än.

Visa ny webbplats

Skapa en Event Grid-prenumeration

Skapa en Event Grid prenumeration av den typ som du vill testa och ge den URL:en från webbappen som slutpunkt för händelseavisering. Slutpunkten för ditt webbprogram måste innehålla suffixet /api/updates/. Därför är den fullständiga URL:en https://<your-site-name>.azurewebsites.net/api/updates

Information om hur du skapar prenumerationer med hjälp av Azure Portal finns i Skapa anpassad händelse – Azure Portal i Event Grid dokumentationen.

Generera en begäran

Utlöst en händelse som genererar HTTP-trafik till webbappens slutpunkt. Om du till exempel har skapat en bloblagringsprenumeration kan du ladda upp eller ta bort en blob. När en begäran visas i webbappen kopierar du begärandetexten.

Begäran om prenumerationsverifiering tas emot först. ignorera alla valideringsbegäranden och kopiera händelsebegäran.

Kopiera begärandetexten från webbappen

Publicera begäran manuellt

Kör din Event Grid lokalt. Rubrikerna Content-Type aeg-event-type och måste anges manuellt, medan alla andra värden kan lämnas som standard.

Använd ett verktyg som Postman eller curl för att skapa en HTTP POST-begäran:

  • Ange en Content-Type: application/json rubrik.
  • Ange ett aeg-event-type: Notification sidhuvud.
  • Klistra in RequestBin-data i begärandetexten.
  • Publicera till URL:en för din Event Grid utlösarfunktion.
    • För 2.x och senare använder du följande mönster:

      http://localhost:7071/runtime/webhooks/eventgrid?functionName={FUNCTION_NAME}
      
    • För 1.x använder du:

      http://localhost:7071/admin/extensions/EventGridExtensionConfig?functionName={FUNCTION_NAME}
      

Parametern functionName måste vara det namn som anges i FunctionName attributet.

Följande skärmbilder visar huvudena och begärandetexten i Postman:

Rubriker i Postman

Begärandetext i Postman

Funktionen Event Grid körs och visar loggar som liknar följande exempel:

Exempelloggar Event Grid utlösarfunktion

Nästa steg