Trigger Griglia di eventi di Azure per Funzioni di Azure

Usare il trigger di funzione per rispondere a un evento inviato da un'origine griglia di eventi. Per ricevere gli eventi, è necessario disporre di una sottoscrizione di eventi all'origine. Per informazioni su come creare una sottoscrizione di eventi, vedere Creare una sottoscrizione. Per informazioni sull'installazione e la configurazione dell'associazione, vedere la panoramica.

Nota

I trigger di Griglia di eventi non sono supportati in modo nativo in un servizio di bilanciamento del carico interno ambiente del servizio app (AMBIENTE del servizio app). Il trigger usa una richiesta HTTP che non riesce a raggiungere l'app per le funzioni senza un gateway nella rete virtuale.

Importante

Questo articolo usa schede per supportare le versioni diverse del modello di programmazione Node.js. Il modello v4 è disponibile a livello generale ed è progettato per offrire un'esperienza più flessibile e intuitiva per gli sviluppatori JavaScript e TypeScript. Per altre informazioni sul funzionamento del modello v4, vedere la guida per gli sviluppatori di Node.js per Funzioni di Azure. Altre informazioni sulle differenze tra i modelli v3 e v4 sono disponibili nella guida alla migrazione.

Funzioni di Azure supporta due modelli di programmazione per Python. Il modo in cui si definiscono le associazioni dipende dal modello di programmazione scelto.

v2

Il modello di programmazione Python v2 consente di definire associazioni usando elementi Decorator direttamente nel codice della funzione Python. Per altre informazioni, vedere la Guida per sviluppatori Python.

v1

Il modello di programmazione Python v1 richiede di definire associazioni in un file di function.json separato nella cartella della funzione. Per altre informazioni, vedere la Guida per sviluppatori Python.

Questo articolo supporta entrambi i modelli di programmazione.

Esempio

Per un esempio di trigger HTTP, vedere Ricevere eventi in un endpoint HTTP.

Il tipo del parametro di input usato con un trigger di Griglia di eventi dipende da questi tre fattori:

• Versione del runtime di Funzioni
• Versione dell'estensione di associazione
• Modalità della funzione C#.

È possibile creare una funzione C# usando una delle modalità C# seguenti:

• Modello di lavoro isolato: funzione C# compilata eseguita in un processo di lavoro isolato dal runtime. Il processo di lavoro isolato è necessario per supportare le funzioni C# in esecuzione in LTS e versioni non LTS .NET e .NET Framework. Le estensioni per le funzioni del processo di lavoro isolato usano Microsoft.Azure.Functions.Worker.Extensions.* spazi dei nomi.
• Modello in-process: funzione C# compilata eseguita nello stesso processo del runtime di Funzioni. In una variante di questo modello, le funzioni possono essere eseguite usando script C#, che è supportato principalmente per la modifica del portale C#. Le estensioni per le funzioni in-process usano Microsoft.Azure.WebJobs.Extensions.* spazi dei nomi.

Importante

Il supporto terminerà per il modello in-process il 10 novembre 2026. È consigliabile eseguire la migrazione delle app al modello di lavoro isolato per il supporto completo.

Modello di lavoro isolato

Quando si esegue la funzione C# in un processo di lavoro isolato, è necessario definire un tipo personalizzato per le proprietà dell'evento. Nell'esempio seguente viene definita una MyEventType classe .

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

L'esempio seguente mostra come viene usato il tipo personalizzato sia nel trigger che in un'associazione di output di Griglia di eventi:

    [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
{

Modello di processo

L'esempio seguente mostra una funzione Functions versione 4.x che usa un parametro di CloudEvent associazione:

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

L'esempio seguente mostra una funzione Functions versione 4.x che usa un parametro di EventGridEvent associazione:

using Microsoft.Azure.WebJobs;
using Azure.Messaging.EventGrid;
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());
        }
    }
}

L'esempio seguente mostra una funzione che usa un parametro di JObject associazione:

using Microsoft.Azure.WebJobs;
using Microsoft.Azure.WebJobs.Extensions.EventGrid;
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));
        }
    }
}

Questa sezione contiene gli esempi seguenti:

• Trigger griglia di eventi, parametro String
• Trigger griglia di eventi, parametro POJO

Gli esempi seguenti illustrano l'associazione di trigger in Java che usano l'associazione e generano un evento, ricevendo prima l'evento come String e il secondo come POJO.

Trigger Griglia di eventi, parametro String

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

Trigger Griglia di eventi, parametro POJO

Questo esempio usa il POJO seguente, che rappresenta le proprietà di livello superiore di un evento Griglia di eventi:

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;

}

All'arrivo, il payload JSON dell'evento viene deserializzato nel POJO EventSchema per l'uso nella funzione. Questo processo consente alla funzione di accedere alle proprietà dell'evento in una modalità orientata agli oggetti.

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

Nella libreria di runtime delle funzioni Java usare l'annotazione EventGridTrigger sui parametri il cui valore proviene da Griglia di eventi. I parametri con queste annotazioni attivano l'esecuzione della funzione quando viene ricevuto un evento. Questa annotazione è utilizzabile con i tipi Java nativi, con oggetti POJO o con valori nullable tramite Optional<T>.

Modello v4

L'esempio seguente mostra una funzione TypeScript trigger di Griglia di eventi.

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

Modello v3

Gli esempi typeScript non sono documentati per il modello v3.

Modello v4

L'esempio seguente mostra una funzione JavaScript trigger di Griglia di eventi.

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

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

Modello v3

L'esempio seguente illustra un'associazione di trigger in un file function.json e una funzione JavaScript che usa l'associazione.

Ecco i dati di associazione nel file function.json:

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

Ecco il codice JavaScript:

module.exports = async function (context, eventGridEvent) {
    context.log("JavaScript Event Grid function processed a request.");
    context.log("Subject: " + eventGridEvent.subject);
    context.log("Time: " + eventGridEvent.eventTime);
    context.log("Data: " + JSON.stringify(eventGridEvent.data));
};

Nell'esempio seguente viene illustrato come configurare un'associazione di trigger di Griglia di eventi nel file function.json.

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

L'evento griglia di eventi viene reso disponibile alla funzione tramite un parametro denominato eventGridEvent, come illustrato nell'esempio di PowerShell seguente.

param($eventGridEvent, $TriggerMetadata)

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

L'esempio seguente mostra un'associazione di trigger di Griglia di eventi e una funzione Python che usa l'associazione. L'esempio dipende dal fatto che si usi il modello di programmazione Python v1 o v2.

v2

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)

v1

Ecco i dati di associazione nel file function.json:

{
  "bindings": [
    {
      "type": "eventGridTrigger",
      "name": "event",
      "direction": "in"
    }
  ],
  "disabled": false,
  "scriptFile": "__init__.py"
}

Ecco il codice Python:

import json
import logging

import azure.functions as func

def main(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)

Attributi

Sia le librerie C# in-process che il processo di lavoro isolato usano l'attributo EventGridTrigger . Lo script C# usa invece un file di configurazione function.json come descritto nella guida per gli script C#.

Modello di lavoro isolato

Di seguito è mostrato un attributo EventGridTrigger in una firma del metodo:

public static MyEventType Run([EventGridTrigger] MyEventType input, FunctionContext context)
{
    var logger = context.GetLogger(nameof(EventGridFunction));
    logger.LogInformation(input.Data?.ToString());

Modello di processo

Di seguito è mostrato un attributo EventGridTrigger in una firma del metodo:

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

Annotazioni

L'annotazione EventGridTrigger consente di configurare in modo dichiarativo un'associazione di Griglia di eventi fornendo valori di configurazione. Per altri dettagli, vedere le sezioni di esempio e configurazione.

Impostazione

Modello v4

L'oggetto options passato al app.eventGrid() metodo attualmente non supporta alcuna proprietà per il modello v4.

Modello v3

Nella tabella seguente sono illustrate le proprietà di configurazione dell'associazione impostate nel file function.json.

Proprietà	Descrizione
type	Obbligatoria. Deve essere impostata su eventGridTrigger.
direction	Obbligatoria. Deve essere impostata su in.
name	Obbligatoria: nome della variabile usato nel codice della funzione per il parametro che riceve i dati dell'evento.

Impostazione

Nella tabella seguente sono illustrate le proprietà di configurazione dell'associazione impostate nel file function.json. Non sono presenti parametri o proprietà di costruttori da impostare nell'attributo EventGridTrigger.

Proprietà di function.json	Descrizione
type	Obbligatoria. Deve essere impostata su eventGridTrigger.
direction	Obbligatoria. Deve essere impostata su in.
name	Obbligatoria: nome della variabile usato nel codice della funzione per il parametro che riceve i dati dell'evento.

Per esempi completi, vedere la sezione di esempio.

Utilizzo

Il trigger di Griglia di eventi usa una richiesta HTTP webhook, che può essere configurata usando le stesse impostazioni di host.json del trigger HTTP.

Il tipo di parametro supportato dal trigger di Griglia di eventi dipende dalla versione del runtime di Funzioni, dalla versione del pacchetto di estensione e dalla modalità C# usata.

Estensione v3.x

Le funzioni della libreria di classi C# in-process supportano i tipi seguenti:

• Azure.Messaging.CloudEvent
• Azure.Messaging.EventGrid
• Newtonsoft.Json.Linq.JObject
• System.String

Estensione v2.x

Le funzioni della libreria di classi C# in-process supportano i tipi seguenti:

• Microsoft.Azure.EventGrid.Models.EventGridEvent
• Newtonsoft.Json.Linq.JObject
• System.String

Funzioni 1.x

Le funzioni della libreria di classi C# in-process supportano i tipi seguenti:

• Newtonsoft.Json.Linq.JObject
• System.String

Estensione v3.x

Quando si vuole che la funzione elabori un singolo evento, il trigger di Griglia di eventi può essere associato ai tipi seguenti:

Tipo	Descrizione
Tipi serializzabili JSON	Funzioni tenta di deserializzare i dati JSON dell'evento in un tipo POCO (Plain-Old CLR Object).
string	Evento come stringa.
BinaryData1	Byte del messaggio dell'evento.
CloudEvent1	Oggetto evento. Usare quando Griglia di eventi è configurata per il recapito usando lo schema CloudEvents.
EventGridEvent1	Oggetto evento. Usare quando Griglia di eventi è configurata per il recapito usando lo schema di Griglia di eventi.

Quando si vuole che la funzione elabori un batch di eventi, il trigger di Griglia di eventi può essere associato ai tipi seguenti:

Tipo	Descrizione
CloudEvent[]1, EventGridEvent[]1, string[], BinaryData[]1	Matrice di eventi del batch. Ogni voce rappresenta un evento.

¹ Per usare questi tipi, è necessario fare riferimento a Microsoft.Azure.Functions.Worker.Extensions.EventGrid 3.3.0 o versione successiva e alle dipendenze comuni per le associazioni di tipi SDK.

Estensione v2.x

Richiede di definire un tipo personalizzato o di usare una stringa. Vedere la sezione Esempio per esempi sull'uso di un tipo di parametro personalizzato.

Funzioni 1.x

Le funzioni versione 1.x non supportano il processo di lavoro isolato.

L'istanza dell'evento di Griglia di eventi è disponibile tramite il parametro associato all'attributo EventGridTrigger, tipizzato come EventSchema.

L'istanza di Griglia di eventi è disponibile tramite il parametro configurato nella proprietà function.json del file name.

L'istanza di Griglia di eventi è disponibile tramite il parametro configurato nella proprietà function.json del file name, tipizzata come func.EventGridEvent.

Schema di eventi

I dati di un evento di Griglia di eventi vengono trasmessi come oggetto JSON nel corpo di una richiesta HTTP. L'oggetto JSON sarà simile all'esempio seguente:

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

L'esempio illustrato rappresenta una matrice di un elemento. Griglia di eventi invia sempre una matrice e può inviare più eventi nella matrice. Il runtime richiama la funzione una volta per ogni elemento della matrice.

Le proprietà di livello superiore nei dati JSON dell'evento sono uguali per tutti i tipi di evento, mentre il contenuto della proprietà data è specifico per ogni tipo di evento. L'esempio illustrato si riferisce a un evento di archiviazione BLOB.

Per altre informazioni sulle proprietà comuni e specifiche degli eventi, vedere Proprietà degli eventi nella documentazione relativa a Griglia di eventi.

Passaggi successivi

• In caso di domande, inviare un problema al team qui
• Inviare un evento di Griglia di eventi