Condividi tramite


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.

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

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

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

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.

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

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

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.

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:

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

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

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.

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.

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 .

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.

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

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