Gestione degli errori di Funzioni di Azure e tentativi

La gestione degli errori in Funzioni di Azure è importante per evitare perdite di dati, evitare eventi mancanti e monitorare l'integrità dell'applicazione. È anche un modo importante per comprendere i comportamenti di ripetizione dei tentativi dei trigger basati su eventi.

Questo articolo descrive le strategie generali per la gestione degli errori e le strategie di ripetizione dei tentativi disponibili.

Importante

Il supporto dei criteri di ripetizione dei tentativi viene rimosso nel runtime per trigger diversi da Timer, Kafka e Hub eventi dopo che questa funzionalità diventa disponibile a livello generale. Il supporto dei criteri di ripetizione dei tentativi di anteprima per tutti i trigger diversi da Timer e Hub eventi è stato rimosso nel dicembre 2022. Per altre informazioni, vedere la sezione Tentativi .

Gestione degli errori

Gli errori che si verificano in una funzione di Azure possono derivare da uno dei seguenti:

• Uso di trigger e associazioni Funzioni di Azure predefiniti
• Chiamate alle API dei servizi di Azure sottostanti
• Chiamate agli endpoint REST
• Chiamate a librerie client, pacchetti o API di terze parti

Per evitare la perdita di dati o messaggi persi, è importante eseguire una corretta gestione degli errori. In questa sezione vengono descritte alcune procedure consigliate per la gestione degli errori e vengono forniti collegamenti ad altre informazioni.

Abilita Application Insights

Funzioni di Azure si integra con Application Insights per raccogliere dati sugli errori, dati sulle prestazioni e log di runtime. È consigliabile usare Application Insights per individuare e comprendere meglio gli errori che si verificano nelle esecuzioni delle funzioni. Per altre informazioni, vedere Monitorare Funzioni di Azure.

Usare la gestione degli errori strutturati

L'acquisizione e la registrazione degli errori è fondamentale per monitorare l'integrità dell'applicazione. Il livello più alto di qualsiasi codice di funzione deve includere un blocco try/catch. Nel blocco catch è possibile acquisire e registrare gli errori. Per informazioni sugli errori che possono essere generati dalle associazioni, vedere Binding error codes .For information about what errors might be generate by binding binding error codes, see Binding error codes.

Pianificare la strategia di ripetizione dei tentativi

Diverse estensioni delle associazioni di Funzioni offrono il supporto predefinito per i tentativi. Il runtime consente inoltre di definire criteri di ripetizione dei tentativi per le funzioni attivate da Timer, Kafka e Hub eventi. Per altre informazioni, vedere Tentativi. Per i trigger che non forniscono comportamenti di ripetizione dei tentativi, è possibile implementare uno schema di ripetizione dei tentativi personalizzato.

Progettare per idempotency

L'occorrenza di errori durante l'elaborazione dei dati può essere un problema per le funzioni, soprattutto quando si elaborano messaggi. È importante considerare cosa accade quando si verifica l'errore e come evitare l'elaborazione duplicata. Per altre informazioni, vedere Progettazione di Funzioni di Azure per un input identico.

Nuovi tentativi

Per le funzioni sono disponibili due tipi di tentativi:

• Comportamenti di ripetizione dei tentativi predefiniti delle singole estensioni di trigger
• Criteri di ripetizione dei tentativi forniti dal runtime di Funzioni

La tabella seguente indica quali trigger supportano i tentativi e dove è configurato il comportamento di ripetizione dei tentativi. Sono inoltre disponibili collegamenti ad altre informazioni sugli errori provenienti dai servizi sottostanti.

Trigger/binding	Riprovare l'origine	Impostazione
Azure Cosmos DB	Criteri di ripetizione dei tentativi	Livello di funzione
Archiviazione BLOB di Azure	Estensione dell'associazione	host.json
Griglia di eventi di Azure	Estensione dell'associazione	Sottoscrizione evento
Hub eventi di Azure	Criteri di ripetizione dei tentativi	Livello di funzione
Archiviazione code di Azure	Estensione dell'associazione	host.json
RabbitMQ	Estensione dell'associazione	Coda di messaggi non recapitabili
Bus di servizio di Azure	Estensione dell'associazione	Coda di messaggi non recapitabili
Timer	Criteri di ripetizione dei tentativi	Livello di funzione
Kafka	Criteri di ripetizione dei tentativi	Livello di funzione

Criteri di ripetizione dei tentativi

A partire dalla versione 3.x del runtime di Funzioni di Azure, è possibile definire criteri di ripetizione dei tentativi per timer, Kafka, Hub eventi e trigger di Azure Cosmos DB applicati dal runtime di Funzioni.

Il criterio di ripetizione dei tentativi indica al runtime di eseguire di nuovo un'esecuzione non riuscita fino a quando non si verifica il completamento corretto o viene raggiunto il numero massimo di tentativi.

Un criterio di ripetizione dei tentativi viene valutato quando una funzione attivata da Timer, Kafka, Hub eventi o Azure Cosmos DB genera un'eccezione non rilevata. Come procedura consigliata, è consigliabile intercettare tutte le eccezioni nel codice e generare nuovamente eventuali errori che si desidera generare un nuovo tentativo.

Importante

I checkpoint di Hub eventi non verranno scritti fino al termine del criterio di ripetizione dei tentativi per l'esecuzione. A causa di questo comportamento, lo stato di avanzamento della partizione specifica viene sospeso fino al termine del batch corrente.

L'estensione Hub eventi v5 supporta funzionalità di ripetizione dei tentativi aggiuntive per le interazioni tra l'host funzioni e l'hub eventi. Per altre informazioni, vedere la clientRetryOptionssezione Hub eventi del file di host.json .

Strategie di ripetizione dei tentativi

È possibile configurare due strategie di ripetizione dei tentativi supportate dai criteri:

Ritardo fisso

È consentito un intervallo di tempo specificato tra ogni tentativo.

Backoff esponenziale

Il primo tentativo attende il ritardo minimo. Nei tentativi successivi, il tempo viene aggiunto in modo esponenziale alla durata iniziale per ogni tentativo, fino a quando non viene raggiunto il ritardo massimo. Il back-off esponenziale aggiunge alcune piccole sequenze casuali ai ritardi nei tentativi di sfalsare in scenari a velocità effettiva elevata.

Numero massimo di tentativi

È possibile configurare il numero massimo di tentativi di esecuzione di una funzione prima dell'eventuale errore. Il conteggio dei tentativi corrente viene archiviato in memoria dell'istanza di .

È possibile che un'istanza abbia un errore tra i tentativi di ripetizione. Quando un'istanza ha esito negativo durante un criterio di ripetizione dei tentativi, il numero di tentativi viene perso. In caso di errori di istanza, il trigger di Hub eventi è in grado di riprendere l'elaborazione e ripetere l'elaborazione in una nuova istanza, con il numero di tentativi reimpostato su zero. Il trigger timer non riprende in una nuova istanza.

Questo comportamento indica che il numero massimo di tentativi è un'operazione ottimale. In alcuni rari casi, un'esecuzione potrebbe essere ritentata più del numero massimo di volte richiesto. Per i trigger timer, i tentativi possono essere inferiori al numero massimo richiesto.

Esempi di ripetizione dei tentativi

Modello di lavoro isolato

I tentativi a livello di funzione sono supportati con i pacchetti NuGet seguenti:

• Microsoft.Azure.Functions.Worker.Sdk>= 1.9.0
• Microsoft.Azure.Functions.Worker.Extensions.EventHubs>= 5.2.0
• Microsoft.Azure.Functions.Worker.Extensions.Kafka>= 3.8.0
• Microsoft.Azure.Functions.Worker.Extensions.Timer>= 4.2.0

[Function(nameof(TimerFunction))]
[FixedDelayRetry(5, "00:00:10")]
public static void Run([TimerTrigger("0 */5 * * * *")] TimerInfo timerInfo,
    FunctionContext context)
{
    var logger = context.GetLogger(nameof(TimerFunction));
    logger.LogInformation($"Function Ran. Next timer schedule = {timerInfo.ScheduleStatus.Next}");
}

Proprietà	Descrizione
MaxRetryCount	Obbligatorio. Numero massimo di tentativi consentiti per ogni esecuzione di funzione. -1 significa riprovare per un periodo illimitato.
DelayInterval	Ritardo usato tra i tentativi. Specificarlo come stringa con il formato HH:mm:ss.

Modello in-process

I tentativi richiedono il pacchetto NuGet Microsoft.Azure.WebJobs>= 3.0.23

[FunctionName("EventHubTrigger")]
[FixedDelayRetry(5, "00:00:10")]
public static async Task Run([EventHubTrigger("myHub", Connection = "EventHubConnection")] EventData[] events, ILogger log)
{
// ...
}

Proprietà	Descrizione
MaxRetryCount	Obbligatorio. Numero massimo di tentativi consentiti per ogni esecuzione di funzione. -1 significa riprovare per un periodo illimitato.
DelayInterval	Ritardo usato tra i tentativi. Specificarlo come stringa con il formato HH:mm:ss.

Modello di lavoro isolato

I tentativi a livello di funzione sono supportati con i pacchetti NuGet seguenti:

• Microsoft.Azure.Functions.Worker.Sdk>= 1.9.0
• Microsoft.Azure.Functions.Worker.Extensions.EventHubs>= 5.2.0
• Microsoft.Azure.Functions.Worker.Extensions.Kafka>= 3.8.0
• Microsoft.Azure.Functions.Worker.Extensions.Timer>= 4.2.0

[Function(nameof(CosmosDBFunction))]
[ExponentialBackoffRetry(5, "00:00:04", "00:15:00")]
[CosmosDBOutput("%CosmosDb%", "%CosmosContainerOut%", Connection = "CosmosDBConnection", CreateIfNotExists = true)]
public object Run(
    [CosmosDBTrigger(
        "%CosmosDb%",
        "%CosmosContainerIn%",
        Connection = "CosmosDBConnection",
        LeaseContainerName = "leases",
        CreateLeaseContainerIfNotExists = true)] IReadOnlyList<MyDocument> input,
    FunctionContext context)
{
    if (input != null && input.Any())
    {
        foreach (var doc in input)
        {
            _logger.LogInformation("Doc Id: {id}", doc.Id);
        }

        // Cosmos Output
        return input.Select(p => new { id = p.Id });
    }

    return null;
}

Modello in-process

I tentativi richiedono il pacchetto NuGet Microsoft.Azure.WebJobs>= 3.0.23

[FunctionName("EventHubTrigger")]
[ExponentialBackoffRetry(5, "00:00:04", "00:15:00")]
public static async Task Run([EventHubTrigger("myHub", Connection = "EventHubConnection")] EventData[] events, ILogger log)
{
// ...
}

Proprietà	Descrizione
MaxRetryCount	Obbligatorio. Numero massimo di tentativi consentiti per ogni esecuzione di funzione. -1 significa riprovare per un periodo illimitato.
MinimumInterval	Ritardo minimo dei tentativi. Specificarlo come stringa con il formato HH:mm:ss.
MaximumInterval	Ritardo massimo tra tentativi. Specificarlo come stringa con il formato HH:mm:ss.

Ecco i criteri di ripetizione dei tentativi nel file function.json :

Ritardo fisso

{
    "disabled": false,
    "bindings": [
        {
            ....
        }
    ],
    "retry": {
        "strategy": "fixedDelay",
        "maxRetryCount": 4,
        "delayInterval": "00:00:10"
    }
}

Backoff esponenziale

{
    "disabled": false,
    "bindings": [
        {
            ....
        }
    ],
    "retry": {
        "strategy": "exponentialBackoff",
        "maxRetryCount": 5,
        "minimumInterval": "00:00:10",
        "maximumInterval": "00:15:00"
    }
}

function.json proprietà	Descrizione
aziendale	Obbligatorio. La strategia di ripetizione dei tentativi da usare. I valori validi sono fixedDelay o exponentialBackoff.
maxRetryCount	Obbligatorio. Numero massimo di tentativi consentiti per ogni esecuzione di funzione. -1 significa riprovare per un periodo illimitato.
delayInterval	Ritardo usato tra i tentativi quando si usa una fixedDelay strategia. Specificarlo come stringa con il formato HH:mm:ss.
minimumInterval	Ritardo minimo dei tentativi quando si usa una exponentialBackoff strategia. Specificarlo come stringa con il formato HH:mm:ss.
maximumInterval	Ritardo massimo dei tentativi quando si usa exponentialBackoff la strategia. Specificarlo come stringa con il formato HH:mm:ss.

Ecco un esempio python che usa il contesto di ripetizione dei tentativi in una funzione:

import azure.functions
import logging


def main(mytimer: azure.functions.TimerRequest, context: azure.functions.Context) -> None:
    logging.info(f'Current retry count: {context.retry_context.retry_count}')

    if context.retry_context.retry_count == context.retry_context.max_retry_count:
        logging.warn(
            f"Max retries of {context.retry_context.max_retry_count} for "
            f"function {context.function_name} has been reached")

Ritardo fisso

@FunctionName("TimerTriggerJava1")
@FixedDelayRetry(maxRetryCount = 4, delayInterval = "00:00:10")
public void run(
    @TimerTrigger(name = "timerInfo", schedule = "0 */5 * * * *") String timerInfo,
    final ExecutionContext context
) {
    context.getLogger().info("Java Timer trigger function executed at: " + LocalDateTime.now());
}

Backoff esponenziale

@FunctionName("TimerTriggerJava1")
@ExponentialBackoffRetry(maxRetryCount = 5 , maximumInterval = "00:15:00", minimumInterval = "00:00:10")
public void run(
    @TimerTrigger(name = "timerInfo", schedule = "0 */5 * * * *") String timerInfo,
    final ExecutionContext context
) {
    context.getLogger().info("Java Timer trigger function executed at: " + LocalDateTime.now());
}

Elemento	Descrizione
maxRetryCount	Obbligatorio. Numero massimo di tentativi consentiti per ogni esecuzione di funzione. -1 significa riprovare per un periodo illimitato.
delayInterval	Ritardo usato tra i tentativi quando si usa una fixedDelay strategia. Specificarlo come stringa con il formato HH:mm:ss.
minimumInterval	Ritardo minimo dei tentativi quando si usa una exponentialBackoff strategia. Specificarlo come stringa con il formato HH:mm:ss.
maximumInterval	Ritardo massimo dei tentativi quando si usa exponentialBackoff la strategia. Specificarlo come stringa con il formato HH:mm:ss.

Codici degli errori di associazione

Quando si esegue l'integrazione con i servizi di Azure, gli errori potrebbero provenire dalle API dei servizi sottostanti. Le informazioni correlate agli errori specifici dell'associazione sono disponibili nelle sezioni "Eccezioni e codici restituiti" degli articoli seguenti:

• Azure Cosmos DB
• Archiviazione BLOB
• Griglia di eventi
• Hub eventi
• Hub IoT
• Hub di notifica di Azure
• Archiviazione code
• Bus di servizio
• Archiviazione tabelle

Passaggi successivi

• Concetti relativi a trigger e associazioni in Funzioni di Azure
• Procedure consigliate per funzioni di Azure affidabili