AWS Step Functions
開発者ガイド

エラー

状態でランタイムエラーが発生することがあります。ステートマシン定義の問題 (Choice 状態で一致するルールがないなど)、タスクの失敗 (Lambda 関数からの例外など)、ネットワークパーティションイベントなどの一時的な問題により、エラーが発生する場合があります。状態がエラーと表示される場合、AWS Step Functions のデフォルトアクションとして、実行全体が失敗します。

エラーの表現

エラーは、Amazon ステートメント言語 の大文字と小文字を区別する文字列で識別されます。これをエラー名といいます。Amazon ステートメント言語 では、よく知られているエラーに名前を付けるための一連の組み込み文字が定義されます。それらはすべて「States」というプレフィックスで始まります。:

事前定義されたエラーコード

States.ALL

エラー名に一致するワイルドカード。

States.Timeout

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

States.TaskFailed

実行中に失敗した Task 状態。

States.Permissions

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

状態は他の名前でエラーを報告することができます。それらをプレフィックス「States」で始めることはできません。

エラー後の再試行

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

注記

再試行は状態遷移として扱われます。状態遷移が請求に与える影響の詳細については、Step Functions の料金表をご覧ください。

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

ErrorEquals (必須)

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

IntervalSeconds(オプション)

最初の再試行前の秒数を表す整数 (デフォルトは 1)。

MaxAttempts(オプション)

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

BackoffRate(オプション)

試行ごとに再試行間隔が増加する乗数である数値 (デフォルトは 2.0)。

以下は、3 秒および 4.5 秒待機した後で 2 回の再試行を試みる Retry フィールドの例です。

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

Retrier の ErrorEquals フィールドにあらかじめ表示される名前 States.ALL は、すべてのエラー名に一致するワイルドカードです。ErrorEquals 配列では単独で表示される必要があり、Retry 配列では最後の Retrier に表示される必要があります。

以下は、States.Timeout を除くエラーを再試行する Retry フィールドの例です。

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

複雑な再試行シナリオ

Retrier のパラメータは、単一状態実行のコンテキストの Retrier に対するすべてのアクセスに適用されます。これは例で示すのが最適です。次のタスク状態について考えてみてください。

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

このタスクが 5 回連続で失敗し、エラー名「ErrorA」、「ErrorB」、「ErrorC」、「ErrorB」、および「ErrorB」を出力するとします。最初の 2 つのエラーが最初の retrier に一致し、1 秒および 2 秒の待機が発生します。3 番目のエラーが 2 番目の retrier に一致し、5 秒の待機が発生します。4 番目のエラーが 1 番目の retrier に一致し、4 秒の待機が発生します。5 番目のエラーは最初の retrier にも一致しますが、すでに特定のエラー (「ErrorB」) の 2 つの再試行の上限 (「MaxAttempts」) に達しているために失敗し、実行は「Catch」フィールドを介して「Z」状態にリダイレクトされます。

システムが別の状態に移行すると、方法に関係なく、すべての Retrier パラメータがリセットされます。

注記

アクティビティ または Lambda 関数を使用して、カスタムエラー名 (たとえば、上記の ErrorA および ErrorB) を生成できます。詳細については、ステートマシンを使用したエラー条件の処理を参照してください。

Fallback 状態

Task および Parallel 状態は Catch という名前のフィールドを持つことができます。その値は Catcher と呼ばれるオブジェクトの配列にする必要があります。

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

ErrorEquals (必須)

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

Next (必須)

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

ResultPath(オプション)

Next フィールドに指定された状態に入力として送信される内容を決定するパス

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

Catcher の ErrorEquals フィールドにあらかじめ表示される名前 States.ALL は、すべてのエラー名に一致するワイルドカードです。ErrorEquals 配列では単独で表示される必要があり、Catch 配列では最後の Catcher に表示される必要があります。

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

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

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

AWS Step Functions が Catcher で指定された状態に移行すると、エラーがなかった場合に次の状態に通常送信するのとは異なる入力 JSON テキストとして送信します。この JSON テキストは、値がエラー名を含む文字列であるフィールド "Error" を含むオブジェクトを表します。また、通常このオブジェクトには、人間が読み取れるエラーの説明であるフィールド "Cause" が含まれます。このオブジェクトをエラー出力と呼びます。

この例では、最初の Catcher に ResultPath フィールドが含まれています。これは状態の最上位の ResultPath フィールドと同様に機能します。つまり、状態の実行結果を受け取り、状態の入力の一部を上書きするか、状態のすべての入力を受け取るか、結果を受け取って入力に追加します。Catcher によって処理されたエラーの場合、状態の実行結果はエラー出力です。

したがって、この例では、最初の Catcher またはエラー出力が error-info という名前のフィールドとして入力に追加され (入力でその名前のフィールドがすでに存在しないことが前提)、入力全体が RecoveryState に送信されます。2 番目 の Catcher では、エラー出力によって入力が上書きされるため、エラー出力のみが EndState に送信されます。指定しない場合、ResultPath フィールドはデフォルトで $ になり、これにより入力全体が選択されて上書きされます。

状態に Retry および Catch フィールドの両方がある場合、Step Functions は最初に該当する Retrier を使用し、その後、再試行ポリシーがエラーを解決できなかった場合、一致する Catcher の移行を適用します。