Gestione degli errori in Step Functions - AWS Step Functions
Nomi degli erroriRiprovare dopo un erroreStati di fallbackEsempi di macchine a stati che utilizzano Retry e Catch

Le traduzioni sono generate tramite traduzione automatica. In caso di conflitto tra il contenuto di una traduzione e la versione originale in Inglese, quest'ultima prevarrà.

Gestione degli errori in Step Functions

Tutti gli stati, tranne Wait gli stati Pass e, possono presentare errori di runtime. Gli errori possono verificarsi per vari motivi, ad esempio i seguenti esempi:

  • Problemi relativi alla definizione della macchina a stati (ad esempio, assenza di regola corrispondente in uno stato Choice)

  • Esito negativo dei task (ad esempio un'eccezione in una funzione AWS Lambda)

  • Problemi transitori (ad esempio eventi di partizione della rete)

Per impostazione predefinita, quando uno stato riporta un errore, AWS Step Functions causa il totale insuccesso dell'esecuzione.

Suggerimento

Per implementare un esempio di flusso di lavoro che include la gestione degli errori nel vostro ambienteAccount AWS, consultate il Modulo 8 - Gestione degli errori di The AWS Step Functions Workshop.

Nomi degli errori

Step Functions identifica gli errori in Amazon States Language utilizzando stringhe con distinzione tra maiuscole e minuscole, note come nomi di errore. Amazon States Language definisce un set di stringhe integrate che denominano errori noti, tutti a partire dal States. prefisso.

States.ALL

Un carattere jolly che corrisponde a qualsiasi nome di errore noto.

Nota

Questo tipo di errore non è in grado di catturare il tipo di errore del States.DataLimitExceeded terminale e i tipi di errore di runtime. Per ulteriori informazioni su questi tipi di errore, consulta States.DataLimitExceedede States.Runtime.

States.DataLimitExceeded

Step Functions riporta un'States.DataLimitExceededeccezione nelle seguenti condizioni:

  • Quando l'uscita di un connettore supera la quota di dimensione del payload.

  • Quando l'uscita di uno stato è maggiore della quota di dimensione del payload.

  • Quando, dopo l'Parameterselaborazione, l'input di uno stato è maggiore della quota di dimensione del payload.

Per ulteriori informazioni sulle quote, vedere. Quote

Nota

Si tratta di un errore del terminale che non può essere rilevato dal tipo di States.ALL errore.

States.ExceedToleratedFailureThreshold

Uno Map stato non è riuscito perché il numero di elementi non riusciti ha superato la soglia specificata nella definizione della macchina a stati. Per ulteriori informazioni, consulta Soglia di errore tollerata per lo stato della mappa distribuita.

States.HeartbeatTimeout

Uno Task stato non è riuscito a inviare un battito cardiaco per un periodo più lungo del HeartbeatSeconds valore.

Nota

Questo errore è disponibile solo all'interno dei Retry campi Catch e.

States.IntrinsicFailure

Un tentativo di richiamare una funzione intrinseca all'interno di un modello di payload non è riuscito.

States.ItemReaderFailed

Uno Map stato non è riuscito perché non è stato in grado di leggere la fonte dell'elemento specificata nel campo. ItemReader Per ulteriori informazioni, consulta ItemReader.

States.NoChoiceMatched

Uno Choice stato non è riuscito a far corrispondere l'input alle condizioni definite nella regola di scelta e non è stata specificata una transizione predefinita.

States.ParameterPathFailure

Un tentativo di sostituire un campo, all'interno del Parameters campo di uno stato, il cui nome termina .$ con l'utilizzo di un percorso fallisce.

States.Permissions

Uno Task stato non è riuscito perché non disponeva di privilegi sufficienti per eseguire il codice specificato.

States.ResultPathMatchFailure

Step Functions non è riuscito ad applicare il ResultPath campo di uno stato all'input ricevuto dallo stato.

States.ResultWriterFailed

Uno Map stato non è riuscito perché non è stato in grado di scrivere risultati nella destinazione specificata nel ResultWriter campo. Per ulteriori informazioni, consulta ResultWriter.

States.Runtime

Un'esecuzione non è riuscita a causa di un'eccezione che non è stata in grado di elaborare. Spesso questo è causato da errori in fase di esecuzione, come il tentativo di applicare InputPath o OutputPath su un payload JSON null. Un States.Runtime errore non è recuperabile e causerà sempre il fallimento dell'esecuzione. Un nuovo tentativo o un catch on States.ALL non rileveranno States.Runtime errori.

States.TaskFailed

Uno stato Task ha avuto esito negativo durante l'esecuzione. Quando viene utilizzato in un retry o catch, States.TaskFailed funge da jolly che corrisponde a qualsiasi nome di errore noto ad eccezione di. States.Timeout

States.Timeout

Uno stato Task è rimasto in esecuzione più a lungo del valore di TimeoutSeconds oppure non è riuscito a inviare un heartbeat per un periodo di durata superiore al valore HeartbeatSeconds.

Inoltre, se una macchina a stati funziona più a lungo del TimeoutSeconds valore specificato, l'esecuzione fallisce con un States.Timeout errore.

Gli stati possono riportare errori con altri nomi. Tuttavia, questi nomi di errore non possono iniziare con il States. prefisso.

Come best practice, assicurati che il codice di produzione sia in grado di gestire le eccezioni del servizio AWS Lambda (Lambda.ServiceException e Lambda.SdkClientException). Per ulteriori informazioni, consulta Gestire le eccezioni del servizio Lambda.

Nota

Gli errori non gestiti in Lambda vengono riportati come Lambda.Unknown nell'output degli errori. Questi includono out-of-memory errori e timeout delle funzioni. Puoi abbinare o States.TaskFailed gestire questi errori. Lambda.Unknown States.ALL Quando Lambda raggiunge il numero massimo di chiamate, l'errore è. Lambda.TooManyRequestsException Per ulteriori informazioni sugli errori della funzione Lambda, consulta Gestione degli errori e tentativi automatici nella Developer Guide. AWS Lambda

Riprovare dopo un errore

TaskParallel, e Map gli stati possono avere un campo denominatoRetry, il cui valore deve essere una matrice di oggetti noti come retrier. Un singolo retrier rappresenta un determinato numero di tentativi, di solito a intervalli di tempo crescenti.

Quando uno di questi stati segnala un errore ed è presente un Retry campo, Step Functions analizza i retrier nell'ordine elencato nell'array. Quando il nome dell'errore compare nel valore del ErrorEquals campo di un retrier, la macchina a stati esegue nuovi tentativi come definito nel campo. Retry

Se redriven l'esecuzione esegue nuovamente uno statoStato dell'attività, o Inline Map Parallel, per il quale sono stati definiti nuovi tentativi, il conteggio dei tentativi per questi stati viene ripristinato a 0 per consentire il numero massimo di tentativi. redrive Per un'redrivenesecuzione, è possibile tenere traccia dei singoli tentativi di nuovi tentativi di questi stati utilizzando la console. Per ulteriori informazioni, consulta Riprova il comportamento delle esecuzioni redriven in Redrivingesecuzioni.

Un retrier contiene i seguenti campi:

Nota

I nuovi tentativi vengono trattati come transizioni di stato. Per informazioni su come le transizioni di stato influiscono sulla fatturazione, consulta Step Functions Pricing.

ErrorEquals (Obbligatorio)

Un array non vuoto di stringhe che corrispondono a nomi di errore. Quando uno stato segnala un errore, Step Functions analizza i retrier. Quando nell'array compare il nome dell'errore, implementa la policy per i nuovi tentativi descritta nel retrier.

IntervalSeconds (facoltativo).

Un numero intero positivo che rappresenta il numero di secondi prima del primo tentativo (1per impostazione predefinita). IntervalSecondsha un valore massimo di 99999999.

MaxAttempts (facoltativo).

Un numero intero positivo che rappresenta il numero massimo di tentativi (3 per impostazione predefinita). Se l'errore si ripete più volte di quanto specificato, i tentativi cessano e viene ripristinata la gestione normale degli errori. Il valore di 0 specifica che l'errore non viene mai ritentato. MaxAttemptsha un valore massimo di 99999999.

BackoffRate (facoltativo).

Il moltiplicatore con il quale l'intervallo di tentativi indicato da IntervalSeconds aumenta dopo ogni nuovo tentativo. Per impostazione predefinita, il valore aumenta di. BackoffRate 2.0

Ad esempio, supponiamo che il tuo IntervalSeconds MaxAttempts sia 3, sia 3 e BackoffRate sia 2. Il primo tentativo viene eseguito tre secondi dopo il verificarsi dell'errore. Il secondo tentativo ha luogo sei secondi dopo il primo tentativo. Mentre il terzo tentativo ha luogo 12 secondi dopo il secondo tentativo.

MaxDelaySeconds (facoltativo).

Un numero intero positivo che imposta il valore massimo, in secondi, fino al quale un intervallo di tentativi può aumentare. Questo campo è utile da usare con il campo. BackoffRate Il valore specificato in questo campo limita i tempi di attesa esponenziali risultanti dal moltiplicatore della frequenza di backoff applicato a ogni tentativo consecutivo. È necessario specificare un valore maggiore di 0 e minore di 31622401 per. MaxDelaySeconds

Se non si specifica questo valore, Step Functions non limita i tempi di attesa tra un tentativo e l'altro.

JitterStrategy (facoltativo).

Una stringa che determina se includere o meno il jitter nei tempi di attesa tra tentativi consecutivi. Il jitter riduce i tentativi simultanei di nuovi tentativi distribuendoli su un intervallo di ritardo randomizzato. Questa stringa accetta or come valori. FULL NONE Il valore predefinito è NONE.

Ad esempio, supponiamo di aver impostato MaxAttempts come 3, IntervalSeconds come 2 e BackoffRate come 2. Il primo tentativo viene eseguito due secondi dopo il verificarsi dell'errore. Il secondo tentativo ha luogo quattro secondi dopo il primo tentativo e il terzo tentativo ha luogo otto secondi dopo il secondo tentativo. Se si imposta su JitterStrategyFULL, il primo intervallo di tentativi viene randomizzato tra 0 e 2 secondi, il secondo intervallo di tentativi viene randomizzato tra 0 e 4 secondi e il terzo intervallo tra 0 e 8 secondi.

Esempi di campi Riprova

Questa sezione include i seguenti esempi di Retry campo.

Suggerimento

Per implementare un esempio di flusso di lavoro per la gestione degli errori nel tuoAccount AWS, consulta il modulo Error Handling di The AWS Step Functions Workshop.

Esempio 1 — Riprova con BackoffRate

L'esempio seguente di a Retry effettua due tentativi di nuovo tentativo, il primo dopo aver atteso tre secondi. In base a BackoffRate quanto specificato, Step Functions aumenta l'intervallo tra ogni tentativo fino al raggiungimento del numero massimo di tentativi. Nell'esempio seguente, il secondo tentativo inizia dopo aver atteso tre secondi dopo il primo tentativo.

"Retry": [ {
   "ErrorEquals": [ "States.Timeout" ],
   "IntervalSeconds": 3,
   "MaxAttempts": 2,
   "BackoffRate": 1
} ]
Esempio 2 — Riprova con MaxDelaySeconds

L'esempio seguente esegue tre tentativi e limita il tempo di attesa risultante BackoffRate a 5 secondi. Il primo tentativo viene eseguito dopo un'attesa di tre secondi. Il secondo e il terzo tentativo hanno luogo dopo aver atteso cinque secondi dopo il tentativo precedente a causa del limite massimo di attesa impostato da. MaxDelaySeconds

"Retry": [ {
    "ErrorEquals": [ "States.Timeout" ],
    "IntervalSeconds": 3,
    "MaxAttempts": 3,
    "BackoffRate":2,
    "MaxDelaySeconds": 5,
    "JitterStrategy": "FULL"
} ]

In caso contrarioMaxDelaySeconds, il secondo tentativo avrebbe luogo sei secondi dopo il primo e il terzo tentativo 12 secondi dopo il secondo.

Esempio 3: riprova tutti gli errori tranne States.Timeout

Il nome riservato States.ALL che compare nel campo ErrorEquals di un retrier è un carattere jolly che corrisponde a qualsiasi nome di errore. Deve apparire da solo nell'array ErrorEquals e deve figurare nell'ultimo retrier dell'array Retry. Il nome funge States.TaskFailed anche da jolly e corrisponde a qualsiasi errore tranne. States.Timeout

Il seguente esempio di Retry campo riprova qualsiasi errore tranne. States.Timeout

"Retry": [ {
   "ErrorEquals": [ "States.Timeout" ],
   "MaxAttempts": 0
}, {
   "ErrorEquals": [ "States.ALL" ]
} ]
Esempio 4 — Scenario di tentativi complessi

I parametri di un retrier si applicano a tutte le visite al retrier nel contesto di un'esecuzione a stato singolo.

Considera lo stato Task seguente.

"X": {
   "Type": "Task",
   "Resource": "arn:aws:states:us-east-1:123456789012:task:X",
   "Next": "Y",
   "Retry": [ {
      "ErrorEquals": [ "ErrorA", "ErrorB" ],
      "IntervalSeconds": 1,
      "BackoffRate": 2.0,
      "MaxAttempts": 2
   }, {
      "ErrorEquals": [ "ErrorC" ],
      "IntervalSeconds": 5
   } ],
   "Catch": [ {
      "ErrorEquals": [ "States.ALL" ],
      "Next": "Z"
   } ]
}

Questa attività ha esito negativo quattro volte di seguito, e vengono restituiti i seguenti nomi di errore:ErrorA,ErrorB, ErrorC e. ErrorB Il risultato è il seguente:

  • I primi due errori corrispondono al primo retrier e causano attese di uno e due secondi.

  • Il terzo errore corrisponde al secondo retrier e causa un'attesa di cinque secondi.

  • Il quarto errore corrisponde anche al primo retrier. Tuttavia, ha già raggiunto il numero massimo di due tentativi (MaxAttempts) per quel particolare errore. Pertanto, quel retrier ha esito negativo e l'esecuzione reindirizza il flusso di lavoro Z allo stato tramite il campo. Catch

Stati di fallback

Task, Map e Parallel gli stati possono avere ciascuno un campo denominatoCatch. Il valore di questo campo deve essere un array di oggetti conosciuti come catchers.

Un catcher contiene i seguenti campi.

ErrorEquals (Obbligatorio)

Un array non vuoto di stringhe che corrispondono a nomi di errore, specificati in modo identico al campo del retrier con il medesimo nome.

Next (Obbligatorio)

Una stringa che deve corrispondere esattamente a uno dei nomi di stato della macchina a stati.

ResultPath (facoltativo).

Un percorso che determina l'input che il catcher invia allo stato specificato nel Next campo.

Quando uno stato segnala un errore e non è presente alcun Retry campo o se i nuovi tentativi non riescono a risolvere l'errore, Step Functions analizza i catcher nell'ordine elencato nell'array. Quando il nome dell'errore compare nel valore del campo ErrorEquals di un catcher, la macchina a stati passa allo stato denominato nel campo Next.

Il nome riservato States.ALL che compare nel campo ErrorEquals di un catcher è un carattere jolly che corrisponde a qualsiasi nome di errore. Deve apparire da solo nell'array ErrorEquals e deve figurare nell'ultimo catcher dell'array Catch. Il nome funge States.TaskFailed anche da jolly e corrisponde a qualsiasi errore tranne. States.Timeout

Il seguente esempio di un Catch campo passa allo stato denominato RecoveryState quando una funzione Lambda genera un'eccezione Java non gestita. In caso contrario, il campo passa allo stato EndState.

"Catch": [ {
   "ErrorEquals": [ "java.lang.Exception" ],
   "ResultPath": "$.error-info",
   "Next": "RecoveryState"
}, {
   "ErrorEquals": [ "States.ALL" ],
   "Next": "EndState"
} ]
Nota

Ogni catcher può specificare più errori da gestire.

Output dell'errore

Quando Step Functions passa allo stato specificato in un catch name, l'oggetto di solito contiene il campoCause. Il valore di questo campo è una descrizione leggibile dell'errore. L'oggetto è noto come output dell'errore.

Nel presente esempio il primo catcher contiene un campo ResultPath. Questo funziona in modo analogo a un campo ResultPath nel livello superiore di uno stato e genera due possibilità:

  • Prende i risultati dell'esecuzione di quello stato e sovrascrive tutto o parte dell'input dello stato.

  • Prende i risultati e li aggiunge all'input. Nel caso di un errore gestito da un catcher, il risultato dell'esecuzione dello stato è l'output dell'errore.

Pertanto, per il primo catcher dell'esempio, il catcher aggiunge l'output di errore all'input come campo denominato error-info se nell'input non è già presente un campo con questo nome. Quindi, il catcher invia l'intero input a. RecoveryState Per il secondo ricevitore, l'output di errore sovrascrive l'input e il catcher invia solo l'output di errore a. EndState

Nota

Se non specifichi il campo ResultPath, l'impostazione predefinita è $, che seleziona e sovrascrive l'intero input.

Quando uno stato ha entrambi Catch i campi Retry e, Step Functions utilizza prima tutti i retrier appropriati. Se la politica di riprova non riesce a risolvere l'errore, Step Functions applica la transizione matching catcher.

Causa payload e integrazioni di servizi

Un catcher restituisce un payload di stringa come output. Quando lavori con integrazioni di servizi come Amazon Athena AWS CodeBuild o, potresti voler convertire Cause la stringa in JSON. Il seguente esempio di Pass stato con funzioni intrinseche mostra come convertire una stringa in JSON. Cause

"Handle escaped JSON with JSONtoString": {
  "Type": "Pass",
  "Parameters": {
    "Cause.$": "States.StringToJson($.Cause)"
  },
  "Next": "Pass State with Pass Processing"
},

Esempi di macchine a stati che utilizzano Retry e Catch

Le macchine a stati definite negli esempi seguenti presuppongono l'esistenza di due funzioni Lambda: una che fallisce sempre e una che attende abbastanza a lungo da consentire il verificarsi di un timeout definito nella macchina a stati.

Questa è una definizione di una funzione Lambda di Node.js che fallisce sempre e restituisce il messaggio. error Negli esempi di macchine a stati che seguono, questa funzione Lambda è denominata. FailFunction Per informazioni sulla creazione di una funzione Lambda, vedere Fase 1: Creazione di una funzione Lambda la sezione.

exports.handler = (event, context, callback) => {
    callback("error");
};

Questa è una definizione di una funzione Lambda di Node.js che rimane inattiva per 10 secondi. Negli esempi di macchine a stati che seguono, questa funzione Lambda è denominata. sleep10

Nota

Quando crei questa funzione Lambda nella console Lambda, ricordati di modificare il valore di Timeout nella sezione Impostazioni avanzate da 3 secondi (impostazione predefinita) a 11 secondi.

exports.handler = (event, context, callback) => {
    setTimeout(function(){
    }, 11000);
};

Gestione di un errore utilizzando Retry

Questa macchina a stati utilizza un campo Retry per ritentare una funzione che ha esito negativo e genera il nome di errore HandledError. Riprova questa funzione due volte con un backoff esponenziale tra un tentativo e l'altro.

{
   "Comment": "A Hello World example of the Amazon States Language using an AWS Lambda function",
   "StartAt": "HelloWorld",
   "States": {
      "HelloWorld": {
         "Type": "Task",
         "Resource": "arn:aws:lambda:us-east-1:123456789012:function:FailFunction",
         "Retry": [ {
            "ErrorEquals": ["HandledError"],
            "IntervalSeconds": 1,
            "MaxAttempts": 2,
            "BackoffRate": 2.0
         } ],
      "End": true
      }
   }
}

Questa variante utilizza il codice di errore predefinitoStates.TaskFailed, che corrisponde a qualsiasi errore generato da una funzione Lambda.

{
   "Comment": "A Hello World example of the Amazon States Language using an AWS Lambda function",
   "StartAt": "HelloWorld",
   "States": {
      "HelloWorld": {
         "Type": "Task",
         "Resource": "arn:aws:lambda:us-east-1:123456789012:function:FailFunction",
         "Retry": [ {
            "ErrorEquals": ["States.TaskFailed"],
            "IntervalSeconds": 1,
            "MaxAttempts": 2,
            "BackoffRate": 2.0
         } ],
         "End": true
      }
   }
}
Nota

Come best practice, le attività che fanno riferimento a una funzione Lambda dovrebbero gestire le eccezioni del servizio Lambda. Per ulteriori informazioni, consulta Gestire le eccezioni del servizio Lambda.

Gestione di un errore utilizzando Catch

In questo esempio viene utilizzato un campo Catch. Quando una funzione Lambda emette un errore, rileva l'errore e la macchina a stati passa allo stato. fallback

{
   "Comment": "A Hello World example of the Amazon States Language using an AWS Lambda function",
   "StartAt": "HelloWorld",
   "States": {
      "HelloWorld": {
         "Type": "Task",
         "Resource": "arn:aws:lambda:us-east-1:123456789012:function:FailFunction",
         "Catch": [ {
            "ErrorEquals": ["HandledError"],
            "Next": "fallback"
         } ],
         "End": true
      },
      "fallback": {
         "Type": "Pass",
         "Result": "Hello, AWS Step Functions!",
         "End": true
      }
   }
}

Questa variante utilizza il codice di errore predefinitoStates.TaskFailed, che corrisponde a qualsiasi errore generato da una funzione Lambda.

{
   "Comment": "A Hello World example of the Amazon States Language using an AWS Lambda function",
   "StartAt": "HelloWorld",
   "States": {
      "HelloWorld": {
         "Type": "Task",
         "Resource": "arn:aws:lambda:us-east-1:123456789012:function:FailFunction",
         "Catch": [ {
            "ErrorEquals": ["States.TaskFailed"],
            "Next": "fallback"
         } ],
      "End": true
      },
      "fallback": {
         "Type": "Pass",
         "Result": "Hello, AWS Step Functions!",
         "End": true
      }
   }
}

Gestione di un timeout utilizzando Retry

Questa macchina a stati utilizza un Retry campo per riprovare uno Task stato scaduto, in base al valore di timeout specificato in. TimeoutSeconds Step Functions ritenta l'invocazione della funzione Lambda in Task questo stato due volte, con un backoff esponenziale tra un tentativo e l'altro.

{
   "Comment": "A Hello World example of the Amazon States Language using an AWS Lambda function",
   "StartAt": "HelloWorld",
   "States": {
      "HelloWorld": {
         "Type": "Task",
         "Resource": "arn:aws:lambda:us-east-1:123456789012:function:sleep10",
         "TimeoutSeconds": 2,
         "Retry": [ {
            "ErrorEquals": ["States.Timeout"],
            "IntervalSeconds": 1,
            "MaxAttempts": 2,
            "BackoffRate": 2.0
         } ],
         "End": true
      }
   }
}

Gestione di un timeout utilizzando Catch

In questo esempio viene utilizzato un campo Catch. Quando si verifica un timeout, la macchina a stati passa allo stato fallback.

{
   "Comment": "A Hello World example of the Amazon States Language using an AWS Lambda function",
   "StartAt": "HelloWorld",
   "States": {
      "HelloWorld": {
         "Type": "Task",
         "Resource": "arn:aws:lambda:us-east-1:123456789012:function:sleep10",
         "TimeoutSeconds": 2,
         "Catch": [ {
            "ErrorEquals": ["States.Timeout"],
            "Next": "fallback"
         } ],
         "End": true
      },
      "fallback": {
         "Type": "Pass",
         "Result": "Hello, AWS Step Functions!",
         "End": true
      }
   }
}
Nota

Puoi conservare l'input di stato e l'errore utilizzando ResultPath. Consulta ResultPath Da utilizzare per includere sia l'errore che l'input in un Catch.