Gestion des erreurs dans Step Functions - AWS Step Functions
Noms des erreursRéessayer après une erreurÉtats de repliExemples de machines à états utilisant Retry et Catch

Les traductions sont fournies par des outils de traduction automatique. En cas de conflit entre le contenu d'une traduction et celui de la version originale en anglais, la version anglaise prévaudra.

Gestion des erreurs dans Step Functions

Tous les états, à l'exception Pass des Wait états, peuvent rencontrer des erreurs d'exécution. Des erreurs peuvent se produire pour différentes raisons, comme dans les exemples suivants :

  • Problèmes de définition de la machine d'état (par exemple, aucune règle correspondante dans un état Choice)

  • Echecs de tâche (par exemple, une exception dans une fonction AWS Lambda)

  • Problèmes temporaires (par exemple, les événements de partition du réseau)

Par défaut, lorsqu'un état signale une erreur, AWS Step Functions entraîne l'échec complet de l'exécution.

Astuce

Pour déployer un exemple de flux de travail incluant la gestion des erreurs sur votre ordinateurCompte AWS, consultez le Module 8 - Gestion des erreurs dans l'AWS Step Functionsatelier.

Noms des erreurs

Step Functions identifie les erreurs dans l'Amazon States Language à l'aide de chaînes distinguant majuscules et minuscules, appelées noms d'erreur. L'Amazon States Language définit un ensemble de chaînes intégrées qui nomment les erreurs connues, en commençant toutes par le States. préfixe.

States.ALL

Un caractère générique qui correspond à n'importe quel nom d'erreur connu.

Note

Ce type d'erreur ne peut pas détecter le type d'erreur du States.DataLimitExceeded terminal et les types d'erreur d'exécution. Pour plus d'informations sur ces types d'erreur, reportez-vous States.DataLimitExceededaux sections et States.Runtime.

States.DataLimitExceeded

Step Functions signale une States.DataLimitExceeded exception dans les conditions suivantes :

  • Lorsque la sortie d'un connecteur est supérieure au quota de charge utile.

  • Lorsque le résultat d'un état est supérieur au quota de taille de charge utile.

  • Lorsque, après le Parameters traitement, l'entrée d'un état est supérieure au quota de taille de charge utile.

Pour plus d'informations sur les quotas, voirQuotas.

Note

Il s'agit d'une erreur de terminal qui ne peut pas être détectée par le type States.ALL d'erreur.

States.ExceedToleratedFailureThreshold

Un Map état a échoué car le nombre d'éléments défaillants a dépassé le seuil spécifié dans la définition de la machine à états. Pour en savoir plus, consultez Seuil de défaillance toléré pour l'état de la carte distribuée.

States.HeartbeatTimeout

Un Task état n'a pas réussi à envoyer un battement de cœur pendant une période supérieure à la HeartbeatSeconds valeur.

Note

Cette erreur n'est disponible que dans les Retry champs Catch et.

States.IntrinsicFailure

Une tentative d'appel d'une fonction intrinsèque dans un modèle de charge utile a échoué.

States.ItemReaderFailed

Un Map état a échoué car il n'a pas pu lire à partir de la source de l'élément spécifiée dans le ItemReader champ. Pour en savoir plus, consultez ItemReader.

States.NoChoiceMatched

Un Choice état n'a pas réussi à faire correspondre l'entrée aux conditions définies dans la règle de choix et aucune transition par défaut n'est spécifiée.

States.ParameterPathFailure

Une tentative de remplacement d'un champ, dans le champ d'un État, dont Parameters le nom se termine par l'.$utilisation d'un chemin échoue.

States.Permissions

Un Task état a échoué car il ne disposait pas de privilèges suffisants pour exécuter le code spécifié.

States.ResultPathMatchFailure

Step Functions n'a pas réussi à appliquer ResultPath le champ d'un état à l'entrée que l'état a reçue.

States.ResultWriterFailed

Un Map état a échoué car il n'a pas pu écrire les résultats vers la destination spécifiée dans le ResultWriter champ. Pour en savoir plus, consultez ResultWriter.

States.Runtime

Une exécution a échoué en raison d'une exception qu'elle n'a pas pu traiter. Souvent, ces erreurs sont causées par des erreurs lors de l'exécution, telles que la tentative d'application InputPath ou OutputPath sur une charge utile JSON nulle. Une States.Runtime erreur n'est pas récupérable et entraîne toujours l'échec de l'exécution. Une nouvelle tentative ou un catch on States.ALL ne détectera pas States.Runtime les erreurs.

States.TaskFailed

L'état Task a échoué au cours de l'exécution. Lorsqu'il est utilisé dans un retry ou un catch, States.TaskFailed agit comme un caractère générique qui correspond à n'importe quel nom d'erreur connu, à l'exception de. States.Timeout

States.Timeout

Un état Task a été exécuté plus longtemps que la valeur TimeoutSeconds ou n'est pas parvenu à envoyer une pulsation pendant une période plus longue que la valeur HeartbeatSeconds.

De plus, si une machine à états fonctionne plus longtemps que la TimeoutSeconds valeur spécifiée, l'exécution échoue avec une States.Timeout erreur.

Les états peuvent signaler les erreurs avec d'autres noms. Toutefois, ces noms d'erreur ne peuvent pas commencer par le States. préfixe.

Une bonne pratique consiste à s'assurer que le code de production puisse gérer les exceptions de service AWS Lambda (Lambda.ServiceException et Lambda.SdkClientException). Pour en savoir plus, consultez Gérer les exceptions du service Lambda.

Note

Les erreurs non gérées dans Lambda sont signalées Lambda.Unknown comme dans le résultat d'erreur. Il s'agit notamment out-of-memory des erreurs et des délais d'expiration des fonctions. Vous pouvez effectuer une correspondance ou States.TaskFailed pour gérer ces erreurs. Lambda.Unknown States.ALL Lorsque Lambda atteint le nombre maximum d'appels, l'erreur est. Lambda.TooManyRequestsException Pour plus d'informations sur les erreurs liées aux fonctions Lambda, consultez la section Gestion des erreurs et tentatives automatiques dans le Guide du AWS Lambda développeur.

Réessayer après une erreur

TaskParallel, et Map les états peuvent avoir un champ nomméRetry, dont la valeur doit être un tableau d'objets appelés retriers. Un réessayeur représente un certain nombre de nouvelles tentatives, généralement à intervalles de temps croissants.

Lorsque l'un de ces états signale une erreur et qu'un Retry champ apparaît, Step Functions parcourt les récupérateurs dans l'ordre indiqué dans le tableau. Lorsque le nom de l'erreur apparaît dans la valeur du ErrorEquals champ d'un récupérateur, la machine à états effectue de nouvelles tentatives comme indiqué dans le Retry champ.

Si votre redriven exécution réexécute un état État de la tâcheParallèle, ou Inline Map, pour lequel vous avez défini de nouvelles tentatives, le nombre de tentatives pour ces états est remis à 0 pour tenir compte du nombre maximum de tentatives. redrive Pour une redriven exécution, vous pouvez suivre les tentatives de tentative individuelles de ces états à l'aide de la console. Pour plus d'informations, consultez Réessayer le comportement des exécutions redriven dans Redrivingexécutions.

Un réessayeur contient les champs suivants :

Note

Les nouvelles tentatives sont traitées comme des transitions d'état. Pour plus d'informations sur l'impact des transitions entre États sur la facturation, consultez Step Functions Pricing.

ErrorEquals (Obligatoire)

Tableau non vide de chaînes qui correspondent aux noms d'erreur. Lorsqu'un état signale une erreur, Step Functions analyse les récupérateurs. Lorsque le nom de l'erreur apparaît dans ce tableau, il met en œuvre la stratégie de nouvelle tentative décrite dans ce réessayeur.

IntervalSeconds (facultatif)

Un entier positif qui représente le nombre de secondes avant la première tentative (1par défaut). IntervalSecondsa une valeur maximale de 99999999.

MaxAttempts (facultatif)

Nombre entier positif qui représente le nombre maximum de nouvelles tentatives (3 par défaut). Si l'erreur se produit un nombre de fois supérieur à la valeur spécifiée, les nouvelles tentatives cessent et la gestion normale des erreurs reprend. La valeur de 0 indique que l'erreur n'est jamais réessayée. MaxAttemptsa une valeur maximale de 99999999.

BackoffRate (facultatif)

Multiplicateur par lequel l'intervalle de tentatives indiqué par IntervalSeconds augmente après chaque nouvelle tentative. Par défaut, la BackoffRate valeur augmente de2.0.

Par exemple, disons IntervalSeconds que vous êtes MaxAttempts 3, 3 et BackoffRate 2. La première tentative a lieu trois secondes après l'apparition de l'erreur. La deuxième tentative a lieu six secondes après la première tentative. Alors que la troisième tentative a lieu 12 secondes après la deuxième tentative.

MaxDelaySeconds (facultatif)

Nombre entier positif qui définit la valeur maximale, en secondes, jusqu'à laquelle un intervalle de nouvelles tentatives peut être augmenté. Ce champ est utile à utiliser avec le BackoffRate champ. La valeur que vous spécifiez dans ce champ limite les temps d'attente exponentiels résultant du multiplicateur du taux de ralentissement appliqué à chaque nouvelle tentative consécutive. Vous devez spécifier une valeur supérieure à 0 et inférieure à 31622401 pour. MaxDelaySeconds

Si vous ne spécifiez pas cette valeur, Step Functions ne limite pas les temps d'attente entre les nouvelles tentatives.

JitterStrategy (facultatif)

Chaîne qui détermine s'il faut ou non inclure la gigue dans les temps d'attente entre deux tentatives consécutives. Jitter réduit le nombre de tentatives simultanées en les répartissant sur un intervalle de temporisation aléatoire. Cette chaîne accepte FULL ou NONE comme valeurs. La valeur par défaut est NONE.

Supposons, par exemple, que vous ayez défini MaxAttempts IntervalSeconds comme 3, comme 2 et BackoffRate comme 2. La première tentative a lieu deux secondes après l'apparition de l'erreur. La deuxième tentative a lieu quatre secondes après la première tentative et la troisième tentative huit secondes après la deuxième tentative. Si vous définissez JitterStrategy commeFULL, le premier intervalle de tentatives est randomisé entre 0 et 2 secondes, le deuxième intervalle entre 0 et 4 secondes, et le troisième intervalle entre 0 et 8 secondes.

Exemples de champs à réessayer

Cette section inclut les exemples de Retry champs suivants.

Astuce

Pour déployer un exemple de flux de travail de gestion des erreurs sur votre ordinateurCompte AWS, consultez le module de gestion des erreurs de The AWS Step Functions Workshop.

Exemple 1 — Réessayez avec BackoffRate

L'exemple suivant montre Retry deux tentatives de tentative, la première ayant lieu après trois secondes d'attente. En fonction de ce BackoffRate que vous spécifiez, Step Functions augmente l'intervalle entre chaque nouvelle tentative jusqu'à ce que le nombre maximum de tentatives soit atteint. Dans l'exemple suivant, la deuxième tentative commence après une attente de trois secondes après la première tentative.

"Retry": [ {
   "ErrorEquals": [ "States.Timeout" ],
   "IntervalSeconds": 3,
   "MaxAttempts": 2,
   "BackoffRate": 1
} ]
Exemple 2 — Réessayez avec MaxDelaySeconds

L'exemple suivant effectue trois tentatives de nouvelle tentative et limite le temps d'attente BackoffRate à 5 secondes. La première tentative a lieu après trois secondes d'attente. Les deuxième et troisième tentatives ont lieu après une attente de cinq secondes après la tentative précédente en raison de la limite de temps d'attente maximale définie par. MaxDelaySeconds

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

Dans le cas contraireMaxDelaySeconds, la deuxième tentative aurait lieu six secondes après la première tentative, et la troisième tentative aurait lieu 12 secondes après la deuxième tentative.

Exemple 3 — Réessayez toutes les erreurs sauf States.Timeout

Le nom réservé States.ALL qui apparaît dans le champ ErrorEquals du Réessayeur est une valeur générique correspondant à n'importe quel nom d'erreur. Il doit apparaître seul dans le tableau ErrorEquals et doit figurer dans le dernier réessayeur du tableau Retry. Le nom agit States.TaskFailed également comme un caractère générique et correspond à toutes les erreurs, à l'exception deStates.Timeout.

Dans l'exemple de Retry champ suivant, une nouvelle tentative d'erreur est effectuée, saufStates.Timeout.

"Retry": [ {
   "ErrorEquals": [ "States.Timeout" ],
   "MaxAttempts": 0
}, {
   "ErrorEquals": [ "States.ALL" ]
} ]
Exemple 4 — Scénario de nouvelle tentative complexe

Les paramètres d'un réessayeur s'appliquent à toutes les visites de ce réessayeur dans le cadre d'une seule exécution d'état.

Prenons l'exemple de l'état Task suivant :

"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"
   } ]
}

Cette tâche échoue quatre fois de suite et affiche les noms d'erreur suivants :ErrorA, ErrorBErrorC, etErrorB. Voici ce qui se produit ensuite :

  • Les deux premières erreurs correspondent au premier retrier et entraînent des temps d'attente d'une ou deux secondes.

  • La troisième erreur correspond au deuxième retrier et entraîne une attente de cinq secondes.

  • La quatrième erreur correspond également au premier retrier. Cependant, il a déjà atteint son maximum de deux tentatives (MaxAttempts) pour cette erreur particulière. Par conséquent, ce récupérateur échoue et l'exécution redirige le flux de travail vers l'Zétat via le Catch champ.

États de repli

Task, Map et Parallel les états peuvent chacun avoir un champ nomméCatch. La valeur de ce champ doit être un tableau d'objets, nommés receveurs.

Un receveur contient les champs suivants.

ErrorEquals (Obligatoire)

Un tableau non vide de chaînes qui correspondent à des noms d'erreur, spécifiées exactement comme dans le champ de réessayeur du même nom.

Next (Obligatoire)

Une chaîne qui doit correspondre exactement à l'un des noms d'état de la machine d'état.

ResultPath (facultatif)

Un chemin qui détermine l'entrée que le receveur envoie à l'état spécifié dans le Next champ.

Lorsqu'un État signale une erreur et qu'il n'y a aucun Retry champ, ou si les tentatives échouent à résoudre l'erreur, Step Functions analyse les capteurs dans l'ordre indiqué dans le tableau. Lorsque le nom de l'erreur apparaît dans la valeur du champ ErrorEquals d'un receveur, la machine d'état passe à l'état nommé dans le champ Next.

Le nom réservé States.ALL qui apparaît dans le champ ErrorEquals du receveur est une valeur générique correspondant à n'importe quel nom d'erreur. Il doit apparaître seul dans le tableau ErrorEquals et doit figurer dans le dernier receveur du tableau Catch. Le nom agit States.TaskFailed également comme un caractère générique et correspond à toutes les erreurs, à l'exception deStates.Timeout.

L'exemple suivant d'un Catch champ passe à l'état nommé RecoveryState lorsqu'une fonction Lambda génère une exception Java non gérée. Sinon, le champ passe à l'état EndState.

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

Chaque receveur peut spécifier plusieurs erreurs à gérer.

Sortie d'erreur

Lorsque Step Functions passe à l'état spécifié dans un catch name, l'objet contient généralement le champCause. La valeur de ce champ est une description lisible de l'erreur. Cet objet est connu sous le nom de sortie de l'erreur.

Dans cet exemple, le premier receveur contient un champ ResultPath. Cela fonctionne de la même manière qu'un champ ResultPath au niveau supérieur d'un état, ce qui se traduit par deux possibilités :

  • Il prend les résultats de l'exécution de cet état et remplace la totalité ou une partie des entrées de l'état.

  • Il prend les résultats et les ajoute à l'entrée. Dans le cas d'une erreur gérée par un catcher, le résultat de l'exécution de l'état est la sortie d'erreur.

Ainsi, pour le premier capteur de l'exemple, le capteur ajoute la sortie d'erreur à l'entrée sous forme de champ nommé error-info s'il n'existe pas déjà de champ portant ce nom dans l'entrée. Ensuite, le receveur envoie l'intégralité de l'entrée àRecoveryState. Pour le second capteur, la sortie d'erreur remplace l'entrée et le capteur envoie uniquement la sortie d'erreur à. EndState

Note

Lorsque la valeur du champ ResultPath n'est pas spécifiée, c'est $ qui est utilisée par défaut afin de sélectionner, et donc de remplacer, toute l'entrée.

Lorsqu'un état possède à la fois Retry des Catch champs et, Step Functions utilise d'abord les récupérateurs appropriés. Si la politique de nouvelles tentatives ne parvient pas à résoudre l'erreur, Step Functions applique la transition de capture correspondante.

Provoquer des charges utiles et des intégrations de services

Un catcher renvoie une charge utile sous forme de chaîne en sortie. Lorsque vous travaillez avec des intégrations de services telles qu'Amazon Athena AWS CodeBuild ou, vous souhaiterez peut-être convertir Cause la chaîne en JSON. L'exemple suivant d'un Pass état avec des fonctions intrinsèques montre comment convertir une Cause chaîne en JSON.

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

Exemples de machines à états utilisant Retry et Catch

Les machines à états définies dans les exemples suivants supposent l'existence de deux fonctions Lambda : l'une qui échoue toujours et l'autre qui attend suffisamment longtemps pour qu'un délai défini dans la machine à états se produise.

Il s'agit de la définition d'une fonction Lambda Node.js qui échoue toujours et renvoie le message. error Dans les exemples de machine à états suivants, cette fonction Lambda est nommée. FailFunction Pour plus d'informations sur la création d'une fonction Lambda, reportez-vous Étape 1 : Créer une fonction Lambda à la section.

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

Il s'agit de la définition d'une fonction Lambda de Node.js qui est en veille pendant 10 secondes. Dans les exemples de machine à états suivants, cette fonction Lambda est nommée. sleep10

Note

Lorsque vous créez cette fonction Lambda dans la console Lambda, n'oubliez pas de modifier la valeur du délai d'expiration dans la section Paramètres avancés de 3 secondes (par défaut) à 11 secondes.

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

Gérer un échec à l'aide de Retry

Cette machine d'état utilise un champ Retry pour réessayer une fonction qui échoue et génère le nom d'erreur HandledError. Il réessaie cette fonction deux fois avec un décalage exponentiel entre les tentatives.

{
   "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
      }
   }
}

Cette variante utilise le code d'erreur prédéfiniStates.TaskFailed, qui correspond à toute erreur générée par une fonction 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
      }
   }
}
Note

Il est recommandé que les tâches qui font référence à une fonction Lambda gèrent les exceptions de service Lambda. Pour en savoir plus, consultez Gérer les exceptions du service Lambda.

Gérer une panne à l'aide de Catch

Cet exemple utilise un champ Catch. Lorsqu'une fonction Lambda génère une erreur, elle détecte l'erreur et la machine à états passe à l'fallbackétat.

{
   "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
      }
   }
}

Cette variante utilise le code d'erreur prédéfiniStates.TaskFailed, qui correspond à toute erreur générée par une fonction 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
      }
   }
}

Gestion d'un délai d'attente à l'aide de Retry

Cette machine à états utilise un Retry champ pour réessayer un Task état expirant, en fonction de la valeur de délai spécifiée dans. TimeoutSeconds Step Functions réessaie deux fois d'invoquer la fonction Lambda dans Task cet état, avec un décalage exponentiel entre les tentatives.

{
   "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
      }
   }
}

Gérer un délai d'attente à l'aide de Catch

Cet exemple utilise un champ Catch. Lorsqu'un délai arrive à expiration, la machine d'état passe à l'état 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
      }
   }
}
Note

Vous pouvez conserver l'entrée d'origine avec l'erreur, à l'aide de l'option ResultPath. Consultez ResultPath À utiliser pour inclure à la fois une erreur et une entrée dans un Catch.