Associazioni di output di Griglia di eventi di Azure per Funzioni di Azure

  • Articolo

È possibile usare l'associazione di output di Griglia di eventi per scrivere eventi in un argomento personalizzato. È necessario avere una chiave di accesso per l'argomento personalizzato valida. L'associazione di output di Griglia di eventi non supporta i token di firma di accesso condiviso.

Per informazioni sull'installazione e sulla configurazione, vedere How to work with Event Grid triggers and bindings in Funzioni di Azure (Come usare trigger e associazioni di Griglia di eventi in Funzioni di Azure).

Importante

Questo articolo usa schede per supportare più versioni 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 sviluppatori di Funzioni di Azure Node.js. Per altre informazioni sulle differenze tra v3 e v4, vedere la 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.

Importante

L'associazione di output di Griglia di eventi è disponibile solo per Funzioni di Azure 2.x e successive.

Esempio

Il tipo del parametro di output usato con un'associazione di output di Griglia di eventi dipende dalla versione del runtime di Funzioni, dalla versione dell'estensione di associazione e dalla modalità della funzione C#. La funzione C# può essere creata usando una delle modalità C# seguenti:

  • Libreria di classi in-process: funzione C# compilata eseguita nello stesso processo del runtime di Funzioni.
  • Libreria di classi del processo di lavoro isolato: funzione C# compilata eseguita in un processo di lavoro isolato dal runtime.

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

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

L'esempio seguente illustra una funzione Java che scrive un messaggio in un argomento personalizzato di Griglia di eventi. La funzione usa il metodo dell'associazione setValue per restituire una stringa.

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

È anche possibile usare una classe POJO per inviare messaggi di Griglia di eventi.

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

L'esempio seguente mostra una funzione TypeScript attivata dal timer che restituisce un singolo evento:

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

Per restituire più eventi, restituire una matrice anziché un singolo oggetto. Ad esempio:

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

L'esempio seguente mostra una funzione JavaScript attivata dal timer che restituisce un singolo evento:

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

Per restituire più eventi, restituire una matrice anziché un singolo oggetto. Ad esempio:

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

Nell'esempio seguente viene illustrato come configurare una funzione per l'output di un messaggio di evento di Griglia di eventi. La sezione in cui type è impostata per eventGrid configurare i valori necessari per stabilire un'associazione di output di Griglia di eventi.

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

Nella funzione usare Push-OutputBinding per inviare un evento a un argomento personalizzato tramite l'associazione di output di Griglia di eventi.

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

L'esempio seguente mostra un'associazione di trigger e una funzione Python che usa l'associazione. Invia quindi in un evento all'argomento personalizzato, come specificato da topicEndpointUri. L'esempio dipende dal fatto che si usi il modello di programmazione Python v1 o v2.

Ecco la funzione nel file 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"))

Attributi

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

Il costruttore dell'attributo accetta il nome di un'impostazione dell'applicazione che contiene il nome dell'argomento personalizzato e il nome di un'impostazione dell'applicazione che contiene la chiave dell'argomento.

Nella tabella seguente vengono illustrati i parametri per .EventGridOutputAttribute

Parametro Descrizione
TopicEndpointUri Nome di un'impostazione di app che contiene l'URI per l'argomento personalizzato, ad esempio MyTopicEndpointUri.
TopicKeySetting Nome di un'impostazione di app che contiene una chiave di accesso per l'argomento personalizzato.
connection* Valore del prefisso comune per l'impostazione che contiene l'URI dell'endpoint dell'argomento. Per altre informazioni sul formato di denominazione di questa impostazione dell'applicazione, vedere Autenticazione basata su identità.

Annotazioni

Per le classi Java, usare l'attributo EventGridAttribute .

Il costruttore dell'attributo accetta il nome di un'impostazione di app che contiene il nome dell'argomento personalizzato e il nome di un'impostazione di app che contiene la chiave dell'argomento. Per altre informazioni su queste impostazioni, vedere la sezione relativa alla configurazione dell'output. Di seguito è riportato un esempio di attributo 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) {
            ...
    }
}

Impostazione

Nella tabella seguente vengono illustrate le proprietà che è possibile impostare sull'oggetto options passato al output.eventGrid() metodo .

Proprietà Descrizione
topicEndpointUri Nome di un'impostazione di app che contiene l'URI per l'argomento personalizzato, ad esempio MyTopicEndpointUri.
topicKeySetting Nome di un'impostazione di app che contiene una chiave di accesso per l'argomento personalizzato.
connection* Valore del prefisso comune per l'impostazione che contiene l'URI dell'endpoint dell'argomento. Quando si imposta la connection proprietà , le topicEndpointUri proprietà e topicKeySetting non devono essere impostate. Per altre informazioni sul formato di denominazione di questa impostazione dell'applicazione, vedere Autenticazione basata su identità.

Impostazione

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

Proprietà di function.json Descrizione
type Deve essere impostato su eventGrid.
direction Deve essere impostato su out. Questo parametro viene impostato automaticamente quando si crea l'associazione nel portale di Azure.
name Nome della variabile usato nel codice della funzione che rappresenta l'evento.
topicEndpointUri Nome di un'impostazione di app che contiene l'URI per l'argomento personalizzato, ad esempio MyTopicEndpointUri.
topicKeySetting Nome di un'impostazione di app che contiene una chiave di accesso per l'argomento personalizzato.
connection* Valore del prefisso comune per l'impostazione che contiene l'URI dell'endpoint dell'argomento. Per altre informazioni sul formato di denominazione di questa impostazione dell'applicazione, vedere Autenticazione basata su identità.

*Il supporto per le connessioni basate su identità richiede la versione 3.3.x o successiva dell'estensione.

Quando si sviluppa in locale, aggiungere le impostazioni dell'applicazione nel file local.settings.json nella Values raccolta.

Importante

Assicurarsi di impostare il valore di TopicEndpointUri sul nome di un'impostazione dell'app che contiene l'URI dell'argomento personalizzato. Non specificare l'URI dell'argomento personalizzato direttamente in questa proprietà. Lo stesso vale quando si usa Connection.

Per esempi completi, vedere la sezione Esempio.

Utilizzo

Il tipo di parametro supportato dall'associazione di output 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 scriva un singolo evento, l'associazione di output di Griglia di eventi può essere associata ai tipi seguenti:

Tipo Descrizione
string Evento come stringa.
byte[] Byte del messaggio dell'evento.
Tipi serializzabili JSON Oggetto che rappresenta un evento JSON. Funzioni tenta di serializzare un tipo di oggetto CLR (POCO) normale in dati JSON.

Quando si vuole che la funzione scriva più eventi, l'associazione di output di Griglia di eventi può essere associata ai tipi seguenti:

Tipo Descrizione
T[] dove T è uno dei singoli tipi di evento Matrice contenente più eventi. Ogni voce rappresenta un evento.

Per altri scenari di output, creare e usare i tipi direttamente da Azure.Messaging.EventGrid .

Inviare singoli messaggi chiamando un parametro di metodo, ad out EventGridOutput paramNameesempio , e scrivere più messaggi con ICollector<EventGridOutput>.

Accedere al messaggio di output restituendo direttamente il valore o usando context.extraOutputs.set().

Accedere all'evento di output usando il Push-OutputBinding cmdlet per inviare un evento all'associazione di output di Griglia di eventi.

Sono disponibili due opzioni per l'output di un messaggio di Griglia di eventi da una funzione:

  • Valore restituito: impostare la name proprietà in function.json su $return. Con questa configurazione, il valore restituito della funzione viene salvato in modo permanente come messaggio di Griglia di eventi.
  • Imperativo: passare un valore al metodo set del parametro dichiarato come tipo Out . Il valore passato a set viene salvato in modo permanente come messaggio di Griglia di eventi.

Connessioni

Esistono due modi per eseguire l'autenticazione in un argomento di Griglia di eventi quando si usa l'associazione di output di Griglia di eventi:

Authentication method Descrizione
Uso di una chiave dell'argomento Impostare le TopicEndpointUri proprietà e TopicKeySetting , come descritto in Usare una chiave dell'argomento.
Uso di un'identità Impostare la Connection proprietà sul nome di un prefisso condiviso per più impostazioni dell'applicazione, definendo insieme l'autenticazione basata sull'identità. Questo metodo è supportato quando si usa la versione 3.3.x o successiva dell'estensione.

Usare una chiave dell'argomento

Per configurare una chiave dell'argomento, seguire questa procedura:

  1. Seguire la procedura descritta in Ottenere le chiavi di accesso per ottenere la chiave dell'argomento per l'argomento Griglia di eventi.

  2. Nelle impostazioni dell'applicazione creare un'impostazione che definisce il valore della chiave dell'argomento. Usare il nome di questa impostazione per la TopicKeySetting proprietà dell'associazione.

  3. Nelle impostazioni dell'applicazione creare un'impostazione che definisce l'endpoint dell'argomento. Usare il nome di questa impostazione per la TopicEndpointUri proprietà dell'associazione.

Autenticazione basata sull'identità

Quando si usa la versione 3.3.x o successiva dell'estensione, è possibile connettersi a un argomento di Griglia di eventi usando un'identità di Microsoft Entra per evitare di dover ottenere e usare le chiavi degli argomenti.

È necessario creare un'impostazione dell'applicazione che restituisce l'URI dell'endpoint dell'argomento. Il nome dell'impostazione deve combinare un prefisso comune univoco ,ad esempio , myawesometopiccon il valore __topicEndpointUri . È quindi necessario usare tale prefisso comune (in questo caso , myawesometopic) quando si definisce la Connection proprietà nell'associazione.

In questa modalità, l'estensione richiede le proprietà seguenti:

Proprietà Modello di variabile di ambiente Descrizione Valore di esempio
URI dell'endpoint dell'argomento <CONNECTION_NAME_PREFIX>__topicEndpointUri Endpoint dell'argomento. https://<topic-name>.centralus-1.eventgrid.azure.net/api/events

È possibile usare altre proprietà per personalizzare la connessione. Vedere Proprietà comuni per le connessioni basate su identità.

Nota

Quando si usa app Azure Configurazione o Key Vault per specificare le impostazioni per le connessioni gestite basate sull'identità, i nomi delle impostazioni devono usare un separatore di chiavi valido, : ad esempio o / al posto di __ per assicurarsi che i nomi vengano risolti correttamente.

Ad esempio: <CONNECTION_NAME_PREFIX>:topicEndpointUri.

Quando sono ospitate nel servizio Azure Functions, le connessioni basate su identità usano una identità gestita. Per impostazione predefinita, viene usata l’identità assegnata a livello di sistema, ma è comunque possibile specificare un’identità assegnata dall’utente a cui siano associate le proprietà credential e clientID. Si noti che la configurazione di un'identità assegnata dall'utente con un ID risorsa non è supportata. Quando viene eseguita in altri contesti, ad esempio lo sviluppo locale, viene usata l'identità dello sviluppatore, anche se può essere personalizzata. Vedere Sviluppo locale con connessioni basate su identità.

Concedere l'autorizzazione all'identità

Qualsiasi identità usata deve avere le autorizzazioni necessarie per eseguire le azioni previste. Per la maggior parte dei servizi di Azure, questo significa che è necessario assegnare un ruolo nel controllo degli accessi in base al ruolo di Azure, usando ruoli predefiniti o personalizzati che forniscono tali autorizzazioni.

Importante

È possibile che alcune autorizzazioni esposte dal servizio di destinazione non siano necessarie per tutti i contesti. Laddove possibile, rispettare il principio dei privilegi minimi e concedere all’identità solo i privilegi necessari. Ad esempio, se l'app deve essere in grado di leggere solo da un'origine dati, usare un ruolo che disponga solo dell'autorizzazione per la lettura. Sarebbe inappropriato assegnare un ruolo che consenta anche la scrittura in tale servizio, in quanto sarebbe eccessiva l'autorizzazione per un'operazione di lettura. Analogamente, è consigliabile assicurarsi che l'assegnazione di ruolo sia con ambito solo sulle risorse che devono essere lette.

È necessario creare un'assegnazione di ruolo che fornisce l'accesso all'argomento di Griglia di eventi in fase di esecuzione. I ruoli di gestione come proprietario non sono sufficienti. La tabella seguente illustra i ruoli predefiniti consigliati quando si usa l'estensione di Hub eventi nel normale funzionamento. L'applicazione potrebbe richiedere autorizzazioni aggiuntive in base al codice scritto.

Tipo di associazione Ruoli predefiniti di esempio
Associazione di output Collaboratore EventGrid, mittente dati EventGrid

Passaggi successivi