Hub eventi di Azure binding di output per Funzioni di Azure

Questo articolo illustra come usare le associazioni di Hub eventi di Azure in Funzioni di Azure. Funzioni di Azure supporta il trigger e le associazioni di output per Hub eventi.

Per informazioni sui dettagli di impostazione e configurazione, vedere la panoramica.

È possibile usare l'associazione di output di Hub eventi per scrivere eventi in un flusso di eventi. Per scrivere eventi in un hub eventi, è necessario disporre dell'autorizzazione di invio.

Assicurarsi che i riferimenti ai pacchetti richiesti siano disponibili prima di provare a implementare un'associazione di output.

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

Modello di lavoro isolato

L'esempio seguente illustra una funzione C# che scrive una stringa di messaggio in un hub eventi, usando il valore restituito del metodo come output:

[Function(nameof(EventHubFunction))]
[FixedDelayRetry(5, "00:00:10")]
[EventHubOutput("dest", Connection = "EventHubConnection")]
public string EventHubFunction(
    [EventHubTrigger("src", Connection = "EventHubConnection")] string[] input,
    FunctionContext context)
{
    _logger.LogInformation("First Event Hubs triggered message: {msg}", input[0]);

    var message = $"Output message created at {DateTime.Now}";
    return message;
}

Modello di processo

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.

L'esempio seguente illustra una funzione C# che scrive un messaggio in un Hub eventi usando il valore restituito del metodo come output:

[FunctionName("EventHubOutput")]
[return: EventHub("outputEventHubMessage", Connection = "EventHubConnectionAppSetting")]
public static string Run([TimerTrigger("0 */5 * * * *")] TimerInfo myTimer, ILogger log)
{
    log.LogInformation($"C# Timer trigger function executed at: {DateTime.Now}");
    return $"{DateTime.Now}";
}

L'esempio seguente mostra come usare l'interfaccia IAsyncCollector per inviare un batch di messaggi. Questo scenario è comune quando si elaborano messaggi provenienti da un hub eventi e si invia il risultato a un altro hub eventi.

[FunctionName("EH2EH")]
public static async Task Run(
    [EventHubTrigger("source", Connection = "EventHubConnectionAppSetting")] EventData[] events,
    [EventHub("dest", Connection = "EventHubConnectionAppSetting")]IAsyncCollector<EventData> outputEvents,
    ILogger log)
{
    foreach (EventData eventData in events)
    {
        // Do some processing:
        string newEventBody = DoSomething(eventData);

        // Queue the message to be sent in the background by adding it to the collector.
        // If only the event is passed, an Event Hubs partition to be assigned via
        // round-robin for each batch.
        await outputEvents.AddAsync(new EventData(newEventBody));

        // If your scenario requires that certain events are grouped together in an
        // Event Hubs partition, you can specify a partition key.  Events added with 
        // the same key will always be assigned to the same partition.        
        await outputEvents.AddAsync(new EventData(newEventBody), "sample-key");
    }
}

Modello v4

L'esempio seguente mostra una funzione TypeScript attivata dal timer che invia un singolo messaggio a un hub eventi:

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

export async function timerTrigger1(myTimer: Timer, context: InvocationContext): Promise<string> {
    const timeStamp = new Date().toISOString();
    return `Message created at: ${timeStamp}`;
}

app.timer('timerTrigger1', {
    schedule: '0 */5 * * * *',
    return: output.eventHub({
        eventHubName: 'myeventhub',
        connection: 'MyEventHubSendAppSetting',
    }),
    handler: timerTrigger1,
});

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

const timeStamp = new Date().toISOString();
const message = `Message created at: ${timeStamp}`;
return [`1: ${message}`, `2: ${message}`];

Modello v3

Gli esempi typeScript non sono documentati per il modello v3.

Modello v4

L'esempio seguente mostra una funzione JavaScript attivata dal timer che invia un singolo messaggio a un hub eventi:

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

const eventHubOutput = output.eventHub({
    eventHubName: 'myeventhub',
    connection: 'MyEventHubSendAppSetting',
});

app.timer('timerTrigger1', {
    schedule: '0 */5 * * * *',
    return: eventHubOutput,
    handler: (myTimer, context) => {
        const timeStamp = new Date().toISOString();
        return `Message created at: ${timeStamp}`;
    },
});

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

const timeStamp = new Date().toISOString();
const message = `Message created at: ${timeStamp}`;
return [`1: ${message}`, `2: ${message}`];

Modello v3

L'esempio seguente mostra un'associazione di trigger dell'hub eventi in un file function.json e una funzione che usa l'associazione. La funzione scrive un messaggio di output in un hub eventi.

L'esempio seguente mostra un'associazione di dati di Hub eventi nel file function.json , che è diverso per la versione 1.x del runtime di Funzioni rispetto alle versioni successive.

{
    "type": "eventHub",
    "name": "outputEventHubMessage",
    "eventHubName": "myeventhub",
    "connection": "MyEventHubSendAppSetting",
    "direction": "out"
}

Ecco il codice JavaScript che invia un messaggio:

module.exports = function (context, myTimer) {
    var timeStamp = new Date().toISOString();
    context.log('Message created at: ', timeStamp);   
    context.bindings.outputEventHubMessage = "Message created at: " + timeStamp;
    context.done();
};

Ecco il codice JavaScript che invia più messaggi:

module.exports = function(context) {
    var timeStamp = new Date().toISOString();
    var message = 'Message created at: ' + timeStamp;

    context.bindings.outputEventHubMessage = [];

    context.bindings.outputEventHubMessage.push("1 " + message);
    context.bindings.outputEventHubMessage.push("2 " + message);
    context.done();
};

Gli esempi completi di PowerShell sono in sospeso.

L'esempio seguente mostra un'associazione di trigger dell'hub eventi e una funzione Python che usa l'associazione. La funzione scrive un messaggio in un Hub eventi. L'esempio dipende dal fatto che si usi il modello di programmazione Python v1 o v2.

v2

import logging
import azure.functions as func

app = func.FunctionApp()

@app.function_name(name="eventhub_output")
@app.route(route="eventhub_output")
@app.event_hub_output(arg_name="event",
                      event_hub_name="<EVENT_HUB_NAME>",
                      connection="<CONNECTION_SETTING>")
def eventhub_output(req: func.HttpRequest, event: func.Out[str]):
    body = req.get_body()
    if body is not None:
        event.set(body.decode('utf-8'))
    else:    
        logging.info('req body is none')
    return 'ok'

Ecco il codice Python che invia più messaggi:

import logging
import azure.functions as func
from typing import List

app = func.FunctionApp()

@app.function_name(name="eventhub_output")
@app.route(route="eventhub_output")
@app.event_hub_output(arg_name="event",
                      event_hub_name="<EVENT_HUB_NAME>",
                      connection="<CONNECTION_SETTING>")

def eventhub_output(req: func.HttpRequest, event: func.Out[List[str]]) -> func.HttpResponse:
    my_messages=["message1", "message2","message3"]
    event.set(my_messages)
    return func.HttpResponse(f"Messages sent")

v1

Gli esempi seguenti illustrano il data binding di Hub eventi nel file function.json.

{
    "type": "eventHub",
    "name": "$return",
    "eventHubName": "myeventhub",
    "connection": "MyEventHubSendAppSetting",
    "direction": "out"
}

Ecco il codice Python che invia un messaggio:

import datetime
import logging
import azure.functions as func


def main(timer: func.TimerRequest) -> str:
    timestamp = datetime.datetime.utcnow()
    logging.info('Message created at: %s', timestamp)
    return 'Message created at: {}'.format(timestamp)

Ecco il codice Python che invia più messaggi:

import logging
from typing import List
import azure.functions as func


def main(req: func.HttpRequest, messages:func.Out[List[str]]) -> func.HttpResponse:
    logging.info('Python HTTP trigger function processed a request.')
    messages.set([{"message1"}, {"message2"}])
    return func.HttpResponse(f"Messages sent")

L'esempio seguente illustra una funzione Java che scrive un messaggio contenente l'ora corrente in un hub eventi.

@FunctionName("sendTime")
@EventHubOutput(name = "event", eventHubName = "samples-workitems", connection = "AzureEventHubConnection")
public String sendTime(
   @TimerTrigger(name = "sendTimeTrigger", schedule = "0 */5 * * * *") String timerInfo)  {
     return LocalDateTime.now().toString();
 }

Nella libreria di runtime delle funzioni Java usare l'annotazione @EventHubOutput sui parametri il cui valore verrebbe pubblicato in Hub eventi. Il parametro deve essere di tipo OutputBinding<T>, dove T corrisponde a un POJO o a qualsiasi tipo Java nativo.

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

Modello di lavoro isolato

Usare [EventHubOutputAttribute] per definire un'associazione di output a un hub eventi, che supporta le proprietà seguenti.

Parametri	Descrizione
EventHubName	Nome di Hub eventi. Quando il nome dell'hub eventi è presente anche nella stringa di connessione, tale valore sostituisce questa proprietà in fase di runtime.
Connessione	Nome di un'impostazione o di una raccolta di impostazioni dell'app che specifica come connettersi a Hub eventi. Per altre informazioni, vedere Connessioni.

Modello di processo

Usare EventHubAttribute per definire un'associazione di output a un hub eventi, che supporta le proprietà seguenti.

Parametri	Descrizione
EventHubName	Nome di Hub eventi. Quando il nome dell'hub eventi è presente anche nella stringa di connessione, tale valore sostituisce questa proprietà in fase di runtime.
Connessione	Nome di un'impostazione o di una raccolta di impostazioni dell'app che specifica come connettersi a Hub eventi. Per altre informazioni, vedere Connessioni.

Elementi Decorator

Si applica solo al modello di programmazione Python v2.

Per le funzioni Python v2 definite usando un elemento Decorator, queste proprietà sono supportate per event_hub_output:

Proprietà	Descrizione
arg_name	Nome della variabile usato nel codice della funzione che rappresenta l'evento.
event_hub_name	nome dell'hub eventi. Quando il nome dell'hub eventi è presente anche nella stringa di connessione, tale valore sostituisce questa proprietà in fase di runtime.
connection	Nome di un'impostazione o di una raccolta di impostazioni dell'app che specifica come connettersi a Hub eventi. Per altre informazioni, vedere Connessioni.

Per le funzioni Python definite tramite function.json, vedere la sezione Configurazione .

Annotazioni

Nella libreria di runtime delle funzioni Java usare l'annotazione EventHubOutput sui parametri il cui valore verrebbe pubblicato in Hub eventi. Le impostazioni seguenti sono supportate nell'annotazione:

• name
• dataType
• eventHubName
• connection

Impostazione

Si applica solo al modello di programmazione Python v1.

Modello v4

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

Proprietà	Descrizione
eventHubName	Nome di Hub eventi. Quando il nome dell'hub eventi è presente anche nella stringa di connessione, tale valore sostituisce questa proprietà in fase di runtime.
connection	Nome di un'impostazione o di una raccolta di impostazioni dell'app che specifica come connettersi a Hub eventi. Per altre informazioni, vedere Connessioni.

Modello v3

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

Proprietà	Descrizione
type	Deve essere impostato su eventHub.
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.
eventHubName	Nome di Hub eventi. Quando il nome dell'hub eventi è presente anche nella stringa di connessione, tale valore sostituisce questa proprietà in fase di runtime.
connection	Nome di un'impostazione o di una raccolta di impostazioni dell'app che specifica come connettersi a Hub eventi. Per altre informazioni, vedere Connessioni.

La tabella seguente illustra le proprietà di configurazione dell'associazione impostate nel file function.json, che differisce dalla versione di runtime.

Funzioni 2.x+

Proprietà di function.json	Descrizione
type	Deve essere impostato su eventHub.
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.
eventHubName	Funzioni 2.x e versioni successive. Nome di Hub eventi. Quando il nome dell'hub eventi è presente anche nella stringa di connessione, tale valore sostituisce questa proprietà in fase di runtime.
connection	Nome di un'impostazione o di una raccolta di impostazioni dell'app che specifica come connettersi a Hub eventi. Per altre informazioni, vedere Connessioni.

Funzioni 1.x

Proprietà di function.json	Descrizione
type	Deve essere impostato su eventHub.
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.
path	Solo Funzioni 1.x. Nome di Hub eventi. Quando il nome dell'hub eventi è presente anche nella stringa di connessione, tale valore sostituisce questa proprietà in fase di runtime.
connection	Nome di un'impostazione o di una raccolta di impostazioni dell'app che specifica come connettersi a Hub eventi. Per altre informazioni, vedere Connessioni.

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

Utilizzo

Il tipo di parametro supportato dall'associazione di output di Hub eventi dipende dalla versione del runtime di Funzioni, dalla versione del pacchetto di estensione e dalla modalità C# usata.

Estensione v5.x+

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

• Azure.Messaging.EventHubs.EventData
• String
• Matrice di byte
• Oggetto CLR normale (POCO)

Questa versione di EventData elimina il supporto per il tipo legacy Body a favore di EventBody.

Inviare messaggi con un parametro del metodo, ad esempio out string paramName. Per scrivere più messaggi, è possibile usare ICollector<EventData> o IAsyncCollector<EventData> al posto di out string. Le chiavi di partizione possono essere usate solo con IAsyncCollector<EventData>.

Estensione v3.x+

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

• Microsoft.Azure.EventHubs.EventData
• String
• Matrice di byte
• Oggetto CLR normale (POCO)

Inviare messaggi con un parametro del metodo, ad esempio out string paramName. Per scrivere più messaggi, è possibile usare ICollector<string> o IAsyncCollector<string> al posto di out string.

Estensione v5.x+

Quando si vuole che la funzione scriva un singolo evento, l'associazione di output di Hub eventi può essere associata ai tipi seguenti:

Tipo	Descrizione
string	Evento come stringa. Usare quando l'evento è testo semplice.
byte[]	Byte dell'evento.
Tipi serializzabili JSON	Oggetto che rappresenta l'evento. 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 Hub 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 Microsoft.Azure.EventHubs .

Estensione v3.x+

Richiede di definire un tipo personalizzato o di usare una stringa. Altre opzioni sono disponibili in Estensione v5.x+.

Sono disponibili due opzioni per l'output di un messaggio di Hub eventi da una funzione usando l'annotazione EventHubOutput :

• Valore restituito: applicando l'annotazione alla funzione stessa, il valore restituito della funzione viene salvato in modo permanente come messaggio di Hub eventi.

• Imperativo: per impostare in modo esplicito il valore del messaggio, applicare l'annotazione a un parametro specifico del tipo OutputBinding<T>, dove T è un POJO o qualsiasi tipo Java nativo. Con questa configurazione, il passaggio di un valore al setValue metodo mantiene il valore come messaggio di Hub eventi.

Gli esempi completi di PowerShell sono in sospeso.

Modello v4

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

Modello v3

Accedere all'evento di output usando context.bindings.<name> dove <name> è il valore specificato nella proprietà name di function.json.

Sono disponibili due opzioni per l'output di un messaggio di Hub 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 Hub 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 Hub eventi.

Connessioni

La connection proprietà è un riferimento alla configurazione dell'ambiente che specifica come l'app deve connettersi a Hub eventi. Può specificare:

• Nome di un'impostazione dell'applicazione contenente un stringa di connessione
• Nome di un prefisso condiviso per più impostazioni dell'applicazione, definendo insieme una connessione basata sull'identità.

Se il valore configurato è una corrispondenza esatta per una singola impostazione e una corrispondenza di prefisso per altre impostazioni, viene usata la corrispondenza esatta.

Stringa di connessione

Ottenere questo stringa di connessione facendo clic sul pulsante Informazioni di connessione per lo spazio dei nomi e non sull'hub eventi stesso. Il stringa di connessione deve essere per uno spazio dei nomi di Hub eventi, non per l'hub eventi stesso.

Se usato per i trigger, il stringa di connessione deve avere almeno le autorizzazioni di lettura per attivare la funzione. Se usato per le associazioni di output, il stringa di connessione deve disporre delle autorizzazioni di "invio" per inviare messaggi al flusso di eventi.

Questo stringa di connessione deve essere archiviato in un'impostazione dell'applicazione con un nome corrispondente al valore specificato dalla connection proprietà della configurazione dell'associazione.

Connessioni basate su identità

Se si usa la versione 5.x o successiva dell'estensione, invece di usare un stringa di connessione con un segreto, è possibile che l'app usi un'identità di Microsoft Entra. A tale scopo, è necessario definire le impostazioni con un prefisso comune che esegue il connection mapping alla proprietà nella configurazione del trigger e dell'associazione.

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

Proprietà	Modello di variabile di ambiente	Descrizione	Valore di esempio
Namespace completi	<CONNECTION_NAME_PREFIX>__fullyQualifiedNamespace	Spazio dei nomi completo di Hub eventi.	myeventhubns.servicebus.windows.net

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

Nota

Quando si usano Configurazione app di Azure o Key Vault per fornire le impostazioni per le connessioni di Identità gestita, i nomi delle impostazioni devono usare un separatore di chiavi valido, ad esempio : o / invece di __ per garantire che i nomi vengano risolti correttamente.

Ad esempio: <CONNECTION_NAME_PREFIX>:fullyQualifiedNamespace.

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.

Sarà necessario creare un'assegnazione di ruolo che fornisca l'accesso all'hub eventi in fase di esecuzione. L'ambito dell'assegnazione di ruolo può essere per uno spazio dei nomi di Hub eventi o per l'hub eventi stesso. I ruoli di gestione come Proprietario non sono sufficienti. Nella tabella seguente vengono illustrati i ruoli predefiniti consigliati quando si usa l'estensione Hub eventi in condizioni di normale funzionamento. L'applicazione potrebbe richiedere autorizzazioni aggiuntive in base al codice scritto.

Tipo di associazione	Ruoli predefiniti di esempio
Trigger	Ricevitore dati di Hub eventi di Azure, Proprietario dei dati di Hub eventi di Azure
Associazione di output	Mittente dei dati di Hub eventi di Azure

Eccezioni e codici restituiti

Binding	Riferimento
Hub eventi	Operations Guide (Guida operativa)

Passaggi successivi

• Rispondere agli eventi inviati a un flusso di eventi dell'hub eventi (trigger)