Condividi tramite


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.

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.

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.

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

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

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

Questa sezione contiene gli esempi seguenti:

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>.

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

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

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.

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)

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#.

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

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

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

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

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.

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.

1 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.

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