Step Functions のエラー処理

Pass と Wait 状態を除くすべての状態でランタイムエラーが発生する可能性があります。エラーは、以下の例のようにさまざまな理由で発生する可能性があります。

• ステートマシンの定義の問題 (例えば、Choice 状態に一致するルールがない)。

• タスクの失敗 (例えば、AWS Lambda 関数の例外)。

• 一時的な問題 (例えば、ネットワークパーティションイベント)。

デフォルトでは、状態でエラーが報告されると、AWS Step Functions の実行全体が失敗します。

ヒント

エラー処理を含むワークフローの例を AWS アカウント にデプロイするには、AWS Step Functions ワークショップの「モジュール 8 - エラー処理」を参照してください。

エラー名

Step Functions は大文字と小文字を区別する文字列を使用して Amazon States Language でエラーを識別します。これをエラー名といいます。Amazon States Language は、よく知られているエラー名を付ける一連の組み込み文字列を定義します。すべて States. プレフィックスが付いています。

States.ALL

あらゆる既知のエラー名に一致するワイルドカード。

注記

このエラータイプは、States.DataLimitExceeded ターミナルエラータイプとランタイムエラータイプをキャッチできません。これらのエラータイプについては、「States.DataLimitExceeded」および「States.Runtime」を参照してください。

States.DataLimitExceeded

Step Functions では、以下の条件で States.DataLimitExceeded 例外が報告されます。

• コネクタの出力がペイロードサイズクォータより大きい場合。

• ステートの出力がペイロードサイズクォータより大きい場合。

• Parameters 処理の後、状態の入力がペイロードサイズクォータよりも大きい場合。

クォータに関する詳細については、クォータ を参照してください。

注記

これは States.ALL エラータイプでは検出できないターミナルエラーです。

States.ExceedToleratedFailureThreshold

失敗したアイテムの数がステートマシン定義で指定されたしきい値を超えたため、Map 状態が失敗しました。詳細については「分散マップ状態の許容される失敗しきい値」を参照してください。

States.HeartbeatTimeout

HeartbeatSeconds 値より長時間実行されたため ハートビートの送信に失敗した Task 状態。

注記

このエラーは、Catch および Retry フィールド内でのみ表示されます。

States.IntrinsicFailure

ペイロードテンプレート内で組み込み関数を呼び出そうとしましたが、失敗しました。

States.ItemReaderFailed

ItemReader フィールドに指定されたアイテムソースから読み取れなかったため、Map 状態が失敗しました。詳細については「ItemReader」を参照してください。

States.NoChoiceMatched

Choice 状態が選択ルールで定義された条件と入力を一致させることができず、デフォルト遷移も指定されていません。

States.ParameterPathFailure

状態の Parameters フィールド内で、名前の末尾がパスを使用する .$ になっているフィールドを置換しようとしても失敗します。

States.Permissions

指定されたコードの実行に必要な特権が足りないため Task 状態が失敗しました。

States.ResultPathMatchFailure

Step Functions は、 状態が受け取った入力に状態の ResultPath フィールドを適用できませんでした。

States.ResultWriterFailed

ResultWriter フィールドに指定された宛先に結果を書き込めなかったため、Map 状態が失敗しました。詳細については「ResultWriter」を参照してください。

States.Runtime

処理できない例外のため、実行に失敗しました。多くの場合、これらは実行時のエラー (null JSON ペイロードに InputPath または OutputPath を適用しようとしたなど) によって発生します。States.Runtime エラーは再試行可能ではなく、常に実行が失敗する原因になります。States.ALL での再試行またはキャッチでは States.Runtime エラーはキャッチされません。

States.TaskFailed

実行中に失敗した Task 状態。リトライやキャッチで使用すると、States.TaskFailed は、States.Timeout 以外のあらゆる既知のエラー名に一致するワイルドカードとして機能します。

States.Timeout

TimeoutSeconds 値より長時間実行されたか、HeartbeatSeconds 値より長い間隔ハートビートの送信に失敗した Task 状態。

さらに、ステートマシンが指定された TimeoutSeconds 値より長く実行されると、実行は States.Timeout エラーで失敗します。

状態は別の名前でエラーを報告することがあります。ただし、これらのエラー名は、States. プレフィックスから始めることはできません。

ベストプラクティスとして、本番稼働用コードが AWS Lambda のサービス例外 (Lambda.ServiceException および Lambda.SdkClientException) を処理できることを確認します。詳細については「Lambda サービスの例外を処理する」を参照してください。

注記

Lambda での未処理のエラーは、エラー出力で Lambda.Unknown として報告されます。これには、メモリ不足エラーと関数のタイムアウトが含まれます。Lambda.Unknown、States.ALL、または States.TaskFailed を一致させて、こういったエラーに処理できます。Lambda が最大呼び出し数に達すると、エラーは Lambda.TooManyRequestsException となります。Lambda 関数のエラーの詳細については、「AWS Lambda デベロッパーガイド」の「エラー処理と自動再試行」を参照してください。

エラー後の再試行

Task、Parallel、Map の状態は Retry という名前のフィールドを持つことができます。その値は Retrier と呼ばれるオブジェクトの配列にする必要があります。個々の retrier は特定回数の再試行を表し、通常は時間間隔が増加していきます。

いずれかの状態がエラーを報告し、Retry フィールドがある場合、Step Functions は配列にリストされた順序で Retrier をスキャンします。Retrier の ErrorEquals フィールドの値にエラー名が表示されると、ステートマシンは Retry フィールドで定義されているとおりに再試行します。

再試行を定義した、タスクの状態、並行、または インラインマップステートを redriven で再実行すると、redrive での再試行回数が最大になるように、これらのステートの再試行回数は 0 にリセットされます。redriven 実行では、コンソールを使用してこれらのステートでの再試行を個別に追跡できます。詳細については、「」の 再処理された実行の再試行動作 を参照してください。

retrier には以下のフィールドがあります。

注記

再試行は状態遷移として扱われます。状態遷移が課金に及ぼす影響については、‭‬Step Functions コスト‭を参照してください。

ErrorEquals (必須)

エラー名に一致する空でない文字列の配列です。状態がエラーを報告すると、Step Functions は再試行全体をスキャンします。エラー名がこの配列に表示されている場合、この retrier に記述されている再試行ポリシーを実装します。

IntervalSeconds (オプション)

最初の再試行前の秒数を表す整数 (デフォルトで 1)。IntervalSeconds には 99999999 の最大値があります。

MaxAttempts (オプション)

再試行の最大回数を表す正の整数 (デフォルトでは 3)。エラーが指定された回数を超えて再発する場合は、再試行が停止され通常のエラー処理が再開されます。0 の値は、エラーが再試行されないことを指定します。MaxAttempts には 99999999 の最大値があります。

BackoffRate (オプション)

各試行間の後に IntervalSeconds で表される再試行間隔が増加する乗数。デフォルトでは、BackoffRate 値は 2.0 ずつ増加します。

例えば、IntervalSeconds が 3、MaxAttempts が 3、BackoffRate が 2 だとします。最初の再試行は、エラーが発生した 3 秒後に行われます。2 回目の再試行は、1 回目の再試行の 6 秒後に行われます。また、3 回目の再試行は 2 回目の再試行の 12 秒後に行われます。

MaxDelaySeconds (オプション)

再試行間隔を延長できる最大値を秒単位で設定する正の整数。このフィールドは BackoffRate フィールドと併用すると便利です。このフィールドで指定する値によって、連続する再試行ごとにバックオフ率の乗数が適用されることによる指数関数的な待機時間を制限できます。MaxDelaySeconds には 0 より大きく 31622401 より小さい値を指定する必要があります。

この値を指定しない場合、Step Functions は再試行間の待機時間を制限しません。

JitterStrategy (オプション)

連続する再試行間の待機時間にジッターを含めるかどうかを決定する文字列。ジッターは、ランダムな遅延間隔にわたって再試行回数を分散させて同時再試行回数を減らします。この文字列は、FULL または NONE を値として受け入れます。デフォルト値は、「NONE」です。

例えば、MaxAttempts を 3、IntervalSeconds を 2、BackoffRate を 2 に設定したとします。最初の再試行は、エラーが発生した 2 秒後に行われます。2 回目の再試行は 1 回目の再試行の 4 秒後に行われ、3 回目の再試行は 2 回目の再試行の 8 秒後に行われます。JitterStrategy を FULL に設定した場合、1 回目の再試行間隔は 0～2 秒の間でランダム化され、2 回目の再試行間隔は 0～4 秒の間でランダム化され、3 回目の再試行間隔は 0～8 秒の間でランダム化されます。

再試行フィールドの例

このセクションには、次の Retry フィールドの例が含まれます。

• Retry with BackoffRate

• Retry with MaxDelaySeconds

• Retry all errors except States.Timeout

• Complex retry scenario

ヒント

エラー処理ワークフローの例を AWS アカウント にデプロイするには、AWS Step Functions ワークショップの「エラー処理」を参照してください。

例 1 - BackoffRate を使用して再試行する

次の Retry の例では、2 回の再試行を行い、3 秒待ってから最初の再試行します。Step Functions は、指定した BackoffRate に基づいて、再試行の最大回数に達するまで各再試行の間隔を増やします。次の例では、1 回目の再試行から 3 秒待ってから 2 回目の再試行が開始されます。

"Retry": [ {
   "ErrorEquals": [ "States.Timeout" ],
   "IntervalSeconds": 3,
   "MaxAttempts": 2,
   "BackoffRate": 1
} ]

例 2 - MaxDelaySeconds を指定して再試行する

次の例では、再試行を 3 回行い、BackoffRate から生じる待機時間を 5 秒に制限しています。最初の再試行は 3 秒待ってから行われます。2 回目と 3 回目の再試行は、MaxDelaySeconds で設定されている最大待機時間制限により、前回の再試行から 5 秒間待ってから行われます。

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

MaxDelaySeconds を使用しない場合、2 回目の再試行は 1 回目の再試行の 6 秒後に行われ、3 回目の再試行は 2 回目の再試行の 12 秒後に行われます。

例 3 - States.Timeout を除くすべてのエラーを再試行する

retrier の ErrorEquals フィールドにあらかじめ表示される名前 States.ALL は、すべてのエラー名に一致するワイルドカードです。ErrorEquals 配列では単独で表示される必要があり、Retry 配列では最後の retrier に表示される必要があります。名前 States.TaskFailed もワイルドカードの役割を果たし、States.Timeout を除くあらゆるエラーに一致します。

Retry フィールドの例では、States.Timeout を除くすべてのエラーを再試行します。

"Retry": [ {
   "ErrorEquals": [ "States.Timeout" ],
   "MaxAttempts": 0
}, {
   "ErrorEquals": [ "States.ALL" ]
} ]

例 4 - 複雑な再試行シナリオ

retrier のパラメータは、単一状態実行のコンテキストの retrier に対するすべてのアクセスに適用されます。

次の Task 状態の場合を考えてみます。

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

このタスクは 4 回連続で失敗し、エラー名 ErrorA、ErrorB、ErrorC,ErrorB を出力します。結果として以下が発生します。

• 最初の 2 つのエラーが最初の retrier に一致し、1 秒および 2 秒の待機が発生します。

• 3 番目のエラーが 2 番目の retrier に一致し、5 秒の待機が発生します。

• 4 番目のエラーも最初の retrier に一致します。ただし、その特定のエラーに対する再試行の最大回数 2 回 (MaxAttempts) に達しています。そのため、その retrier は失敗し、実行によってワークフローが Catch フィールドを通じて Z 状態にリダイレクトされます。

Fallback 状態

Task、Map、Parallel 状態はそれぞれ Catch というフィールドを持つことができます。このフィールドの値は、catchers と言われるオブジェクトの配列である必要があります。

catcher には以下のフィールドがあります。

ErrorEquals (必須)

同じ名前の retrier フィールドで指定されたエラー名と正確に一致する空ではない文字列。

Next (必須)

ステートマシンの状態名のいずれかに正確に一致する必要がある文字列。

ResultPath (オプション)

Next フィールドに指定された状態に catcher が送信する入力を決定するパス。

状態がエラーを報告し、Retry フィールドがないか、再試行でエラーが解決できなかった場合、Step Functions は配列にリストされた順序で catcher をスキャンします。エラー名が catcher の ErrorEquals フィールドの値に表示される場合、ステートマシンは Next フィールドに名前がある状態に移行します。

catcher の ErrorEquals フィールドにあらかじめ表示される名前 States.ALL は、すべてのエラー名に一致するワイルドカードです。ErrorEquals 配列では単独で表示される必要があり、Catch 配列では最後の catcher に表示される必要があります。名前 States.TaskFailed もワイルドカードの役割を果たし、States.Timeout を除くあらゆるエラーに一致します。

Catch フィールドの次の例では、Lambda 関数が処理されない Java 例外を出力した場合に RecoveryState という名前の状態に移行します。それ以外の場合は、フィールドは EndState 状態に移行します。

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

注記

各 catcher には処理するエラーを複数指定できます。

エラー出力

Step Functions が catch 名に指定された状態に移行する場合、オブジェクトには通常 Cause というフィールドが含まれます。このフィールドの値は人間が読んで理解できるエラーの説明です。このオブジェクトはエラー出力といいます。

この例では、最初の catcher に ResultPath フィールドが含まれています。これは状態の最上位の ResultPath フィールドに似た動作を行い、次のいずれかの結果になります。

• 状態の実行の結果を取得して、状態の入力のすべてまたは一部を上書きします。

• 結果を取得して入力に追加します。catcher によって処理されたエラーの場合、状態の実行の結果はエラー出力です。

したがって、この例の最初の catcher の場合、catcher がエラー出力が error-info という名前のフィールドとして入力に追加します (入力にこの名前のフィールドが存在しない場合)。次に、catcher は入力全体を RecoveryState に送信します。2 番目 catcher では、エラー出力によって入力が上書きされ、catcher はエラー出力のみを EndState に送信します。

注記

ResultPath フィールドを指定しない場合、入力全体を選択して上書きする $ がデフォルトで設定されます。

状態に Retry と Catch フィールドの両方がある場合、Step Functions は最初に適切な Retrier を使用します。リトライポリシーがエラーを解決できなかった場合、Step Functions は一致する catcher の移行を適用します。

ペイロードとサービス統合の原因

キャッチャーは、文字列ペイロードを出力として返します。Amazon Athena や AWS CodeBuild のようなサービス統合を使って作業する場合、Cause 文字列を JSON に指定します。組み込み関数を使用した Pass 状態の次の例は、Cause 文字列を JSON に変換する方法を示しています。

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

Retry と Catch を使用するステートマシンの例

次の例で定義されたステートマシンには、2 つの Lambda 関数があるとします。1 つは常に失敗し、1 つはステートマシンで定義されたタイムアウトが発生するのに十分な時間待機する許可をだします。

これは、常に失敗してメッセージ error を返す Node.js Lambda 関数の定義です。続くステートマシンの例では、この Lambda 関数の名前は FailFunction です。Lambda 関数の作成の詳細については、「ステップ 1: Lambda 関数を作成する」セクションを参照してください。

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

これは、10 秒間スリープする Node.js Lambda 関数の定義です。続くステートマシンの例では、この Lambda 関数の名前は sleep10 です。

注記

Lambda コンソールでこの Lambda 関数を作成するときは、[Advanced settings] (アドバンスト設定) セクションの [Timeout] (タイムアウト) 値を 3 秒 (デフォルト) から 11 秒に変更してください。

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

Retry を使用して失敗を処理する

このステートマシンは Retry フィールドを使用して、失敗してエラー名 HandledError を出力する関数を再試行します。この関数は 2 回再試行され、再試行間にはエクスポネンシャルパックオフが使用されます。

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

このバリエーションでは、Lambda 関数が出力するあらゆるエラーに一致する事前定義されたエラーコード States.TaskFailed を使用します。

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

注記

ベストプラクティスとしては、Lambda 関数をリファレンスするタスクが Lambda サービス例外を処理する必要があります。詳細については「Lambda サービスの例外を処理する」を参照してください。

Catch を使用して失敗を処理する

この例では、Catch フィールドを使用します。Lambda 関数がエラーを出力すると、そのエラーをキャッチし、ステートマシンは 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
      }
   }
}

このバリエーションでは、Lambda 関数が出力するあらゆるエラーに一致する事前定義されたエラーコード States.TaskFailed を使用します。

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

Retry を使用してタイムアウトを処理する

このステートマシンは Retry フィールドを使用して、TimeoutSeconds で指定されたタイムアウト値に基づいてタイムアウトした Task 状態を再試行します。Step Functions は、この Task 状態で Lambda 関数の呼び出しを 2 回再試行し、再試行間にはエクスポネンシャルパックオフが使用されます。

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

Catch を使用してタイムアウトを処理する

この例では、Catch フィールドを使用します。タイムアウトが発生すると、ステートマシンは 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
      }
   }
}

注記

状態入力とエラーを保持するには、ResultPath を使用します。 ResultPath を使用して、エラーと入力の両方を に含める Catch を参照してください。