trigger Hub eventi di Azure per Funzioni di Azure

  • Articolo

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

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

Usare il trigger di funzioni per rispondere a un evento inviato a un flusso di eventi di Hub eventi. Per configurare il trigger è necessario avere accesso in lettura all'hub eventi sottostante. Quando la funzione viene attivata, il messaggio passato alla funzione viene tipizzato come stringa.

Le decisioni di ridimensionamento di Hub eventi per i piani a consumo e Premium vengono eseguite tramite scalabilità basata su destinazione. Per altre informazioni, vedere Scalabilità basata su destinazione.

Per informazioni su come Funzioni di Azure risponde agli eventi inviati a un flusso di eventi dell'hub eventi tramite trigger, vedere Integrare Hub eventi con funzioni serverless in 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.

Esempio

L'esempio seguente mostra una funzione C# attivata in base a un hub eventi, in cui la stringa del messaggio di input viene scritta nei log:

{
    private readonly ILogger<EventHubsFunction> _logger;

    public EventHubsFunction(ILogger<EventHubsFunction> logger)
    {
        _logger = logger;
    }

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

L'esempio seguente mostra una funzione TypeScript trigger di Hub eventi. La funzione legge i metadati dell'evento e registra il messaggio.

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

export async function eventHubTrigger1(message: unknown, context: InvocationContext): Promise<void> {
    context.log('Event hub function processed message:', message);
    context.log('EnqueuedTimeUtc =', context.triggerMetadata.enqueuedTimeUtc);
    context.log('SequenceNumber =', context.triggerMetadata.sequenceNumber);
    context.log('Offset =', context.triggerMetadata.offset);
}

app.eventHub('eventHubTrigger1', {
    connection: 'myEventHubReadConnectionAppSetting',
    eventHubName: 'MyEventHub',
    cardinality: 'one',
    handler: eventHubTrigger1,
});

Per ricevere eventi in un batch, impostare su cardinalitymany, come illustrato nell'esempio seguente.

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

export async function eventHubTrigger1(messages: unknown[], context: InvocationContext): Promise<void> {
    context.log(`Event hub function processed ${messages.length} messages`);
    for (let i = 0; i < messages.length; i++) {
        context.log('Event hub message:', messages[i]);
        context.log(`EnqueuedTimeUtc = ${context.triggerMetadata.enqueuedTimeUtcArray[i]}`);
        context.log(`SequenceNumber = ${context.triggerMetadata.sequenceNumberArray[i]}`);
        context.log(`Offset = ${context.triggerMetadata.offsetArray[i]}`);
    }
}

app.eventHub('eventHubTrigger1', {
    connection: 'myEventHubReadConnectionAppSetting',
    eventHubName: 'MyEventHub',
    cardinality: 'many',
    handler: eventHubTrigger1,
});

L'esempio seguente mostra una funzione JavaScript trigger di Hub eventi. La funzione legge i metadati dell'evento e registra il messaggio.

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

app.eventHub('eventHubTrigger1', {
    connection: 'myEventHubReadConnectionAppSetting',
    eventHubName: 'MyEventHub',
    cardinality: 'one',
    handler: (message, context) => {
        context.log('Event hub function processed message:', message);
        context.log('EnqueuedTimeUtc =', context.triggerMetadata.enqueuedTimeUtc);
        context.log('SequenceNumber =', context.triggerMetadata.sequenceNumber);
        context.log('Offset =', context.triggerMetadata.offset);
    },
});

Per ricevere eventi in un batch, impostare su cardinalitymany, come illustrato nell'esempio seguente.

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

app.eventHub('eventHubTrigger1', {
    connection: 'myEventHubReadConnectionAppSetting',
    eventHubName: 'MyEventHub',
    cardinality: 'many',
    handler: (messages, context) => {
        context.log(`Event hub function processed ${messages.length} messages`);
        for (let i = 0; i < messages.length; i++) {
            context.log('Event hub message:', messages[i]);
            context.log(`EnqueuedTimeUtc = ${context.triggerMetadata.enqueuedTimeUtcArray[i]}`);
            context.log(`SequenceNumber = ${context.triggerMetadata.sequenceNumberArray[i]}`);
            context.log(`Offset = ${context.triggerMetadata.offsetArray[i]}`);
        }
    },
});

Ecco il codice di PowerShell:

param($eventHubMessages, $TriggerMetadata)

Write-Host "PowerShell eventhub trigger function called for message array: $eventHubMessages"

$eventHubMessages | ForEach-Object { Write-Host "Processed message: $_" }

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

import logging
import azure.functions as func

app = func.FunctionApp()

@app.function_name(name="EventHubTrigger1")
@app.event_hub_message_trigger(arg_name="myhub", 
                               event_hub_name="<EVENT_HUB_NAME>",
                               connection="<CONNECTION_SETTING>") 
def test_function(myhub: func.EventHubEvent):
    logging.info('Python EventHub trigger processed an event: %s',
                myhub.get_body().decode('utf-8'))

L'esempio seguente mostra un'associazione di trigger di Hub eventi che registra il corpo del messaggio del trigger di Hub eventi.

@FunctionName("ehprocessor")
public void eventHubProcessor(
  @EventHubTrigger(name = "msg",
                  eventHubName = "myeventhubname",
                  connection = "myconnvarname") String message,
       final ExecutionContext context )
       {
          context.getLogger().info(message);
 }

Nella libreria di runtime delle funzioni Java usare l'annotazione EventHubTrigger sui parametri il cui valore proviene dall'hub 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>.

Nell'esempio seguente viene illustrato un uso esteso di SystemProperties e altre opzioni di binding per ulteriori introspezioni dell'evento, oltre a fornire un percorso ben formato BlobOutput gerarchico.

package com.example;
import java.util.Map;
import java.time.ZonedDateTime;

import com.microsoft.azure.functions.annotation.*;
import com.microsoft.azure.functions.*;

/**
 * Azure Functions with Event Hub trigger.
 * and Blob Output using date in path along with message partition ID
 * and message sequence number from EventHub Trigger Properties
 */
public class EventHubReceiver {

    @FunctionName("EventHubReceiver")
    @StorageAccount("bloboutput")

    public void run(
            @EventHubTrigger(name = "message",
                eventHubName = "%eventhub%",
                consumerGroup = "%consumergroup%",
                connection = "eventhubconnection",
                cardinality = Cardinality.ONE)
            String message,

            final ExecutionContext context,

            @BindingName("Properties") Map<String, Object> properties,
            @BindingName("SystemProperties") Map<String, Object> systemProperties,
            @BindingName("PartitionContext") Map<String, Object> partitionContext,
            @BindingName("EnqueuedTimeUtc") Object enqueuedTimeUtc,

            @BlobOutput(
                name = "outputItem",
                path = "iotevents/{datetime:yy}/{datetime:MM}/{datetime:dd}/{datetime:HH}/" +
                       "{datetime:mm}/{PartitionContext.PartitionId}/{SystemProperties.SequenceNumber}.json")
            OutputBinding<String> outputItem) {

        var et = ZonedDateTime.parse(enqueuedTimeUtc + "Z"); // needed as the UTC time presented does not have a TZ
                                                             // indicator
        context.getLogger().info("Event hub message received: " + message + ", properties: " + properties);
        context.getLogger().info("Properties: " + properties);
        context.getLogger().info("System Properties: " + systemProperties);
        context.getLogger().info("partitionContext: " + partitionContext);
        context.getLogger().info("EnqueuedTimeUtc: " + et);

        outputItem.setValue(message);
    }
}

Attributi

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

EventHubTriggerAttribute Usare per definire un trigger in 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. È possibile fare riferimento alle impostazioni dell'app, ad esempio%eventHubName%
ConsumerGroup Proprietà facoltativa usata per impostare il gruppo di consumer usato per effettuare la sottoscrizione agli eventi nell'hub. Se omesso, viene utilizzato il $Default gruppo di consumer.
Connessione Nome di un'impostazione o di una raccolta di impostazioni dell'app che specifica come connettersi a Hub eventi. Per altre informazioni, vedere Connessione ions.

Elementi Decorator

Si applica solo al modello di programmazione Python v2.

Per le funzioni Python v2 definite usando un elemento Decorator, le proprietà seguenti in cosmos_db_trigger:

Proprietà Descrizione
arg_name Nome della variabile che rappresenta l'elemento evento nel codice della funzione.
event_hub_name 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. Vedere Connessione ions.

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

Annotazioni

Nella libreria di runtime delle funzioni Java usare l'annotazione EventHubTrigger, che supporta le impostazioni seguenti:

Impostazione

Si applica solo al modello di programmazione Python v1.

Nella tabella seguente vengono illustrate le proprietà che è possibile impostare sull'oggetto options passato al app.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. È possibile fare riferimento tramite le impostazioni dell'app%eventHubName%
consumerGroup Proprietà facoltativa usata per impostare il gruppo di consumer usato per effettuare la sottoscrizione agli eventi nell'hub. Se omessa, al suo posto viene usato il gruppo di consumer $Default.
cardinality Impostare su many per abilitare l'invio in batch. Se omessa o impostata su one, alla funzione viene passato un singolo messaggio.
connection Nome di un'impostazione o di una raccolta di impostazioni dell'app che specifica come connettersi a Hub eventi. Vedere Connessione ions.

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

Proprietà di function.json Descrizione
type Deve essere impostato su eventHubTrigger. Questa proprietà viene impostata automaticamente quando si crea il trigger nel portale di Azure.
direction Deve essere impostato su in. Questa proprietà viene impostata automaticamente quando si crea il trigger nel portale di Azure.
name Nome della variabile che rappresenta l'elemento evento nel codice della funzione.
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. È possibile fare riferimento tramite le impostazioni dell'app%eventHubName%
consumerGroup Proprietà facoltativa usata per impostare il gruppo di consumer usato per effettuare la sottoscrizione agli eventi nell'hub. Se omessa, al suo posto viene usato il gruppo di consumer $Default.
cardinality Impostare su many per abilitare l'invio in batch. Se omessa o impostata su one, alla funzione viene passato un singolo messaggio.
connection Nome di un'impostazione o di una raccolta di impostazioni dell'app che specifica come connettersi a Hub eventi. Vedere Connessione ions.

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

Utilizzo

Per altre informazioni sul modo in cui Hub eventi attiva e hub IoT la scalabilità dei trigger, vedere Utilizzo di eventi con Funzioni di Azure.

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.

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

Tipo Descrizione
string Evento come stringa. Usare quando l'evento è testo semplice.
byte[] Byte dell'evento.
Tipi serializzabili JSON Quando un evento contiene dati JSON, Funzioni tenta di deserializzare i dati JSON in un tipo POCO (Plain-Old CLR Object).
Azure.Messaging.EventHubs.EventData1 Oggetto evento.
Se si esegue la migrazione da versioni precedenti degli SDK di Hub eventi, si noti che questa versione elimina il supporto per il tipo legacy Body a favore di EventBody.

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

Tipo Descrizione
string[] Matrice di eventi del batch, sotto forma di stringhe. Ogni voce rappresenta un evento.
EventData[]1 Matrice di eventi del batch, come istanze di Azure.Messaging.EventHubs.EventData. Ogni voce rappresenta un evento.
T[] dove T è un tiposerializzabile JSON 1 Matrice di eventi del batch, come istanze di un tipo POCO personalizzato. Ogni voce rappresenta un evento.

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

Il tipo di parametro può essere uno dei seguenti:

  • Qualsiasi tipo Java nativo, ad esempio int, String, byte[].
  • Valori nullable usando Facoltativo.
  • Qualsiasi tipo POJO.

Per altre informazioni, vedere le informazioni di riferimento su EventHubTrigger .

Metadati di evento

Il trigger di Hub eventi fornisce diverse proprietà di metadati. Le proprietà di metadati possono essere usate come parte delle espressioni di associazione in altre associazioni o come parametri nel codice. Le proprietà derivano dalla classe EventData.

Proprietà Type Descrizione
PartitionContext PartitionContext Istanza PartitionContext.
EnqueuedTimeUtc DateTime Il tempo di accodamento in formato UTC.
Offset string Offset dei dati relativi al flusso di partizione dell'hub eventi. L'offset è un indicatore o un identificatore per un evento all'interno del flusso di Hub eventi. L'identificatore è univoco all'interno di una partizione del flusso di Hub eventi.
PartitionKey string La partizione a cui devono essere inviati i dati dell'evento.
Properties IDictionary<String,Object> Le proprietà dell'utente dei dati dell'evento.
SequenceNumber Int64 Il numero di sequenza logica dell'evento.
SystemProperties IDictionary<String,Object> Le proprietà di sistema, inclusi di dati dell'evento.

Vedere gli esempi di codice che usano queste proprietà in precedenza in questo articolo.

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.

Connection string

Ottenere questo stringa di connessione facendo clic sul pulsante informazioni Connessione ion per lo spazio dei nomi, 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
Spazio dei nomi completo <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 usa app Azure Configurazione o Insieme di credenziali delle chiavi per specificare le impostazioni per le connessioni con identità gestite, 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>: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 fornisce 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. 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
Trigger Hub eventi di Azure Ricevitore dati, proprietario Hub eventi di Azure dati
Associazione di output Mittente dei dati di Hub eventi di Azure

impostazioni host.json

Il file host.json contiene le impostazioni che controllano il comportamento del trigger per Hub eventi. Per informazioni dettagliate sulle impostazioni disponibili, vedere la sezione impostazioni host.json .

Passaggi successivi