Associazioni del bus di servizio di Azure per Funzioni di Azure

  • Articolo

Funzioni di Azure si integra con bus di servizio di Azure tramite trigger e associazioni. L'integrazione con bus di servizio consente di creare funzioni che reagiscono e inviano messaggi di coda o argomenti.

Azione Type
Eseguire una funzione quando viene creato un messaggio di bus di servizio coda o argomento Trigger
Inviare messaggi di bus di servizio di Azure Associazione di output

Installare l'estensione

Il pacchetto NuGet di estensione installato dipende dalla modalità C# usata nell'app per le funzioni:

Le funzioni sono eseguite in un processo di lavoro C# isolato. Per altre informazioni, vedere Guida per l'esecuzione di Funzioni di Azure C# in un processo di lavoro isolato.

Aggiungere l'estensione al progetto installando questo pacchetto NuGet.

La funzionalità dell'estensione varia a seconda della versione dell'estensione:

Questa versione introduce la possibilità di connettersi usando un'identità anziché un segreto. Per un'esercitazione sulla configurazione delle app per le funzioni con identità gestite, vedere l'esercitazione Creazione di un'app per le funzioni con connessioni basate sull'identità.

Questa versione consente di eseguire l'associazione ai tipi da Azure.Messaging.ServiceBus.

Questa versione supporta la configurazione di trigger e associazioni tramite l'integrazione di .NET Aspire.

Aggiungere l'estensione al progetto installando il pacchetto NuGet versione 5.x.

Installare il bundle

L'associazione bus di servizio fa parte di un bundle di estensione, specificato nel file di progetto host.json. Potrebbe essere necessario modificare questo bundle per modificare la versione dell'associazione o se i bundle non sono già installati. Per altre informazioni, vedere bundle di estensioni.

Questa versione introduce la possibilità di connettersi usando un'identità anziché un segreto. Per un'esercitazione sulla configurazione delle app per le funzioni con identità gestite, vedere l'esercitazione Creazione di un'app per le funzioni con connessioni basate sull'identità.

È possibile aggiungere questa versione dell'estensione dal bundle di estensione v3 aggiungendo o sostituendo il codice seguente nel host.json file:

{
    "version": "2.0",
    "extensionBundle": {
        "id": "Microsoft.Azure.Functions.ExtensionBundle",
        "version": "[3.3.0, 4.0.0)"
    }
}

Per altre informazioni, vedere Aggiornare le estensioni.

Tipi di associazioni

I tipi di associazione supportati per .NET dipendono sia dalla versione dell'estensione che dalla modalità di esecuzione di C#, che può essere una delle seguenti:

Una funzione C# compilata di libreria di classi di processo di lavoro viene eseguita in un processo isolato dal runtime.

Scegliere una versione per visualizzare i dettagli del tipo di associazione per la modalità e la versione.

Il processo di lavoro isolato supporta i tipi di parametro in base alle tabelle seguenti.

Trigger per bus di servizio

Quando si vuole che la funzione elabori un singolo messaggio, il trigger bus di servizio può essere associato ai tipi seguenti:

Tipo Descrizione
string Messaggio come stringa. Usare quando il messaggio è testo semplice.
byte[] Byte del messaggio.
Tipi serializzabili JSON Quando un evento contiene dati JSON, Funzioni tenta di deserializzare i dati JSON in un tipo POCO (Plain-Old CLR Object).
ServiceBusReceivedMessage1 Oggetto messaggio.

Quando si esegue l'associazione a ServiceBusReceivedMessage, è anche possibile includere un parametro di tipo ServiceBusMessageActions1,2 per eseguire azioni di liquidazione dei messaggi.

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

Tipo Descrizione
T[] dove T è uno dei singoli tipi di messaggio Matrice di eventi del batch. Ogni voce rappresenta un evento.

Quando si esegue l'associazione a ServiceBusReceivedMessage[], è anche possibile includere un parametro di tipo ServiceBusMessageActions1,2 per eseguire azioni di liquidazione dei messaggi.

1 Per usare questi tipi, è necessario fare riferimento a Microsoft.Azure.Functions.Worker.Extensions.ServiceBus 5.14.1 o versioni successive e alle dipendenze comuni per le associazioni di tipi SDK.

2 Quando si usa ServiceBusMessageActions, impostare la AutoCompleteMessages proprietà dell'attributo trigger su false. Ciò impedisce al runtime di tentare di completare i messaggi dopo una chiamata di funzione riuscita.

bus di servizio binding di output

Quando si vuole che la funzione scriva un singolo messaggio, l'associazione di output bus di servizio può essere associata ai tipi seguenti:

Tipo Descrizione
string Messaggio come stringa. Usare quando il messaggio è testo semplice.
byte[] Byte del messaggio.
Tipi serializzabili JSON Oggetto che rappresenta il messaggio. Funzioni tenta di serializzare un tipo di oggetto CLR (POCO) normale in dati JSON.

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

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

Per altri scenari di output, creare e usare un ServiceBusClient con altri tipi direttamente da Azure.Messaging.ServiceBus . Vedere Registrare i client di Azure per un esempio di uso dell'inserimento delle dipendenze per creare un tipo di client da Azure SDK.

impostazioni host.json

Questa sezione descrive le impostazioni di configurazione disponibili per questa associazione, che dipende dal runtime e dalla versione dell'estensione.

{
    "version": "2.0",
    "extensions": {
        "serviceBus": {
            "clientRetryOptions":{
                "mode": "exponential",
                "tryTimeout": "00:01:00",
                "delay": "00:00:00.80",
                "maxDelay": "00:01:00",
                "maxRetries": 3
            },
            "prefetchCount": 0,
            "transportType": "amqpWebSockets",
            "webProxy": "https://proxyserver:8080",
            "autoCompleteMessages": true,
            "maxAutoLockRenewalDuration": "00:05:00",
            "maxConcurrentCalls": 16,
            "maxConcurrentSessions": 8,
            "maxMessageBatchSize": 1000,
            "minMessageBatchSize": 1,
            "maxBatchWaitTime": "00:00:30",
            "sessionIdleTimeout": "00:01:00",
            "enableCrossEntityTransactions": false
        }
    }
}

Le clientRetryOptions impostazioni si applicano solo alle interazioni con il servizio bus di servizio. Non influiscono sui tentativi di esecuzione delle funzioni. Per altre informazioni, vedere Tentativi.

Proprietà Predefinito Descrizione
mode Exponential Approccio da usare per calcolare i ritardi di ripetizione dei tentativi. La modalità esponenziale predefinita ritenta i tentativi con un ritardo in base a una strategia di back-off in cui ogni tentativo aumenta la durata di attesa prima di riprovare. La Fixed modalità ritenta i tentativi a intervalli fissi con ogni ritardo con una durata coerente.
tryTimeout 00:01:00 Durata massima di attesa di un'operazione per ogni tentativo.
delay 00:00:00.80 Fattore di ritardo o back-off da applicare tra i tentativi di ripetizione.
maxDelay 00:01:00 Ritardo massimo consentito tra i tentativi di ripetizione
maxRetries 3 Numero massimo di tentativi prima di considerare l'operazione associata non riuscita.
prefetchCount 0 Ottiene o imposta il numero di messaggi che il destinatario del messaggio può richiedere contemporaneamente.
transportType amqpTcp Protocollo e trasporto utilizzato per comunicare con bus di servizio. Opzioni disponibili: amqpTcp, amqpWebSockets
webProxy n/d Proxy da usare per comunicare con bus di servizio tramite web socket. Non è possibile utilizzare un proxy con il amqpTcp trasporto.
autoCompleteMessages true Determina se completare automaticamente i messaggi dopo l'esecuzione corretta della funzione.
maxAutoLockRenewalDuration 00:05:00 La durata massima entro il quale il blocco del messaggio verrà rinnovato automaticamente. Questa impostazione si applica solo alle funzioni che ricevono un singolo messaggio alla volta.
maxConcurrentCalls 16 Numero massimo di chiamate simultanee al callback che deve essere avviato per ogni istanza ridimensionata. Per impostazione predefinita, il runtime di Funzioni elabora più messaggi contemporaneamente. Questa impostazione viene utilizzata solo quando la proprietà o l'attributo isSessionsEnabled nel trigger è impostato su false. Questa impostazione si applica solo alle funzioni che ricevono un singolo messaggio alla volta.
maxConcurrentSessions 8 Numero massimo di sessioni che possono essere gestite contemporaneamente per ogni istanza ridimensionata. Questa impostazione viene utilizzata solo quando la proprietà o l'attributo isSessionsEnabled nel trigger è impostato su true. Questa impostazione si applica solo alle funzioni che ricevono un singolo messaggio alla volta.
maxMessageBatchSize 1000 Numero massimo di messaggi che verranno passati a ogni chiamata di funzione. Questa impostazione si applica solo alle funzioni che ricevono un batch di messaggi.
minMessageBatchSize1 1 Numero minimo di messaggi desiderati in un batch. Il valore minimo si applica solo quando la funzione riceve più messaggi e deve essere minore di maxMessageBatchSize.
Le dimensioni minime non sono strettamente garantite. Un batch parziale viene inviato quando non è possibile preparare un batch completo prima che maxBatchWaitTime sia trascorso.
maxBatchWaitTime1 00:00:30 Intervallo massimo di attesa del trigger per riempire un batch prima di richiamare la funzione. Il tempo di attesa viene considerato solo quando minMessageBatchSize è maggiore di 1 e viene ignorato in caso contrario. Se sono disponibili meno messaggi minMessageBatchSize prima della scadenza del tempo di attesa, la funzione viene richiamata con un batch parziale. Il tempo di attesa consentito più lungo è il 50% della durata del blocco del messaggio di entità, ovvero il massimo consentito è 2 minuti e 30 secondi. In caso contrario, è possibile ottenere eccezioni di blocco.

NOTA: questo intervallo non è una garanzia rigorosa per l'intervallo esatto in cui viene richiamata la funzione. C'è un piccolo margine di errore a causa della precisione del timer.
sessionIdleTimeout n/d Quantità massima di tempo di attesa per la ricezione di un messaggio per la sessione attualmente attiva. Dopo che è trascorso questo tempo, la sessione verrà chiusa e la funzione tenterà di elaborare un'altra sessione.
enableCrossEntityTransactions false Indica se abilitare o meno transazioni che si estendono su più entità in uno spazio dei nomi bus di servizio.

1 L'uso minMessageBatchSize di e maxBatchWaitTime richiede la versione 5.10.0 del Microsoft.Azure.WebJobs.Extensions.ServiceBus pacchetto o una versione successiva.

Passaggi successivi