翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。
Step Functions のエラー処理
状態でランタイムエラーが発生することがあります。エラーはさまざまな理由で発生します。
-
ステートマシンの定義の問題 (例えば、
Choice
状態に一致するルールがない)。 -
タスクの失敗 (例えば、Lambda 関数の例外)。
-
一時的な問題 (例えば、ネットワークパーティションイベント)。
デフォルトでは、状態でエラーが報告されると、AWS Step Functions の実行全体が失敗します。
エラー名
Step Functions は大文字と小文字を区別する文字列を使用して Amazon States Language でエラーを識別します。これをエラー名といいます。Amazon States Language は、よく知られているエラー名を付ける一連の組み込み文字列を定義します。すべて States.
プレフィックスが付いています。
-
States.ALL
-
あらゆる既知のエラー名に一致するワイルドカード。
注記 このエラーcatch は
States.DataLimitExceeded
ターミナルエラータイプとランタイムエラータイプ。このエラータイプの詳細については、「」を参照してください。States.DataLimitExceededそしてStates.Runtime。 -
States.BranchFailed
-
A のブランチ
Parallel
stateFAILED -
States.DataLimitExceeded
-
States.DataLimitExceeded
の例外は、次の場合に発生します。-
コネクタの出力がペイロードサイズクォータより大きい場合。
-
ステートの出力がペイロードサイズクォータより大きい場合。
-
Parameters
処理の後、状態の入力がペイロードサイズクォータよりも大きい場合。
クォータに関する詳細については、クォータ を参照してください。
注記 これはターミナルエラーで、
States.ALL
エラータイプ。 -
-
States.HeartbeatTimeout
-
HeartbeatSeconds
値より長時間実行されたため ハートビートの送信に失敗したTask
状態。注記 このエラーは
Catch
そしてRetry
フィールド。 -
States.IntrinsicFailure
-
このエラーは、ペイロードテンプレート内の組み込み関数の呼び出しが失敗した場合に発生します。
-
States.NoChoiceMatched
-
このランタイムエラーは、
Choice
state が Choice Rule で定義された条件と入力を一致させず、デフォルト遷移が指定されていません。 -
States.ParameterPathFailure
-
このエラーは、ある州の
Parameters
field、名前がで終わるフィールドを置換する試み.$
パスの使用は失敗します。 -
States.Permissions
-
指定されたコードの実行に必要な特権が足りないため失敗した
Task
状態。 -
States.ResultPathMatchFailure
-
ステータス
ResultPath
フィールドは、州が受け取った入力には適用できません。 States.Runtime
-
処理できなかった例外のため、実行に失敗しました。多くの場合、これらは実行時のエラー (null JSON ペイロードに
InputPath
またはOutputPath
を適用しようとしたなど) によって発生します。States.Runtime
エラーは再試行可能ではなく、常に実行が失敗します。States.ALL
での再試行またはキャッチではStates.Runtime
エラーは検出されません。 -
States.TaskFailed
-
実行中に失敗した
Task
状態。リトライやキャッチで使用すると、States.TaskFailed
は、States.Timeout
以外のあらゆる既知のエラー名に一致するワイルドカードとして機能します。 -
States.Timeout
-
TimeoutSeconds
値より長時間実行されたか、HeartbeatSeconds
値より長い間隔ハートビートの送信に失敗したTask
状態。
状態は別の名前でエラーを報告することがあります。ただし、これらは States.
プレフィックスで始まるとは限りません。
ベストプラクティスとして、本番稼働用コードが AWS Lambda のサービス例外 (Lambda.ServiceException
および Lambda.SdkClientException
) を処理できることを確認します。詳細については、「Lambda サービスの例外を処理する」を参照してください。
Lambda での未処理のエラーは、エラー出力で Lambda.Unknown
として報告されます。具体的には次のとおりです。 out-of-memory エラーと機能のタイムアウト。Lambda.Unknown
、States.ALL
、または States.TaskFailed
を一致させて、こういったエラーに処理できます。Lambda が最大呼び出し数に達すると、エラーは Lambda.TooManyRequestsException
となります。Lambda 関数のエラーの詳細については、「」を参照してください。エラー処理と自動再試行のAWS Lambdaデベロッパーガイド。
エラー後の再試行
Task
および Parallel
状態は Retry
という名前のフィールドを持つことができます。その値は retriers と呼ばれるオブジェクトの配列にする必要があります。個々の retrier は特定回数の再試行を表し、通常は時間間隔が増加していきます。
再試行は状態遷移として扱われます。状態遷移が課金に及ぼす影響については、Step Functions コスト
retrier には以下のフィールドがあります。
-
ErrorEquals
(必須) -
エラー名に一致する空でない文字列の配列です。状態がエラーを報告すると、Step Functions は再試行全体をスキャンします。エラー名がこの配列に表示されている場合、この retrier に記述されている再試行ポリシーを実装します。
-
IntervalSeconds
(オプション) -
最初の再試行前の秒数を表す整数 (デフォルトで
1
)。IntervalSeconds
には99999999
の最大値があります。 -
MaxAttempts
(オプション) -
再試行の最大回数を表す正の整数 (デフォルトでは
3
)。エラーが指定された回数を超えて再発する場合は、再試行が停止され通常のエラー処理が再開されます。0
の値 は、エラーが再試行されないことを指定します。MaxAttempts
には99999999
の最大値があります。 -
BackoffRate
(オプション) -
各試行間で再試行間隔が増加する乗数 (デフォルトでは
2.0
)。
この Retry
の例では、2 回の再試行を、3 秒および 4.5 秒間待機した後に行います。
"Retry": [ {
"ErrorEquals": [ "States.Timeout" ],
"IntervalSeconds": 3,
"MaxAttempts": 2,
"BackoffRate": 1.5
} ]
retrier の ErrorEquals
フィールドにあらかじめ表示される名前 States.ALL
は、すべてのエラー名に一致するワイルドカードです。ErrorEquals
配列では単独で表示される必要があり、Retry
配列では最後の retrier に表示される必要があります。名前 States.TaskFailed
もワイルドカードの役割を果たし、States.Timeout
を除くあらゆるエラーに一致します。
この Retry
フィールドの例では、States.Timeout
を除くすべてのエラーを再試行します。
"Retry": [ {
"ErrorEquals": [ "States.Timeout" ],
"MaxAttempts": 0
}, {
"ErrorEquals": [ "States.ALL" ]
} ]
複雑な再試行シナリオ
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
) その特定のエラーに対して。したがって、その再試行は失敗し、実行はZ
州を通ってCatch
フィールド。
Fallback 状態
Task
、Map
および Parallel
状態は Catch
というフィールドを持つことができます。このフィールドの値は、catchers と言われるオブジェクトの配列である必要があります。
catcher には以下のフィールドがあります。
-
ErrorEquals
(必須) -
同じ名前の retrier フィールドで指定されたエラー名と正確に一致する空ではない文字列。
-
Next
(必須) -
ステートマシンの状態名のいずれかに正確に一致する必要がある文字列。
-
ResultPath
(オプション) -
Next
フィールドに指定された状態に送信される入力を決定するパス。
状態がエラーを報告し、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 ではエラー出力が error-info
という名前のフィールドとして入力に追加されます (入力にこの名前のフィールドが存在しない場合)。次に、入力全体が RecoveryState
に送信されます。2 番目 catcher では、エラー出力によって入力が上書きされ、エラー出力のみが EndState
に送信されます。
ResultPath
フィールドを指定しない場合、入力全体を選択して上書きする $
がデフォルトで設定されます。
状態に Retry
および Catch
フィールドの両方がある場合、Step Functions はまず、適切な再試行を使用し、その後になってはじめて、再試行ポリシーでエラーを解決出来なかった場合、一致するキャッチャーを適用します。
ペイロードとサービス統合の原因
キャッチャーは、文字列ペイロードを出力として返します。Amazon Athena や AWS CodeBuild のようなサービス統合を使って作業する場合、Cause
文字列を JSON に指定します。組み込み関数を使用したパス状態の次の例は、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 つはステートマシンで定義されたタイムアウトが発生するのに十分な時間待機する許可をだします。
これは、常に失敗してメッセージを返す Node.js の Lambda 関数の定義です。error
。続くステートマシンの例では、この 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
フィールドを入力して再試行できるかTask
で指定されたタイムアウト値に基づいてタイムアウトする状態TimeoutSeconds
。この中の Lambda 関数の呼び出しTask
stateは 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 に含める」を参照してください。