翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。
# Step Functions ワークフローでのエラー処理
`Pass` と `Wait` 状態を除くすべての状態でランタイムエラーが発生する可能性があります。エラーは、次のようなさまざまな理由で発生する可能性があります。
+ **ステートマシン定義の問題** – 条件に一致するルールのない Choice ステートなど
+ **タスクの失敗** – AWS Lambda 関数内での例外など
+ **一時的な問題** – ネットワーク分断など
ステートでエラーが報告されると、Step Functions はデフォルトでステートマシン**全体**の実行を失敗とみなします。Step Functions には、より高度なエラー処理機能もあります。エラーをキャッチし、失敗したステートを再試行して、エラー処理プロトコルを適切に実装するようにステートマシンを設定できます。
Step Functions の catcher は **Task**、**Parallel**、および **Map** ステートで使用できますが、トップレベルのステートマシンの実行失敗には適用できません。失敗が予想される実行に対処するには、呼び出し元でエラーを処理するか、それらの実行を子ワークフローにネストして親ワークフロー内でエラーをキャッチできます。あるいは、EventBridge バスで Standard ワークフローからの `TIMED_OUT` イベントをリッスンし、失敗した実行を処理するアクションを呼び出すこともできます。
**エラー処理の実例**
エラー処理を含むワークフローの例をデプロイするには、このガイドの[Step Functions ステートマシンでのエラー条件の処理](tutorial-handling-error-conditions.md)チュートリアルとワークショップの[エラー処理](https://catalog.workshops.aws/stepfunctions/handling-errors)を参照してください* AWS Step Functions *。
## エラー名
Step Functions は、大文字小文字を区別する文字列 (*エラー名*) を使用してエラーを識別します。Amazon States Language は、よく知られているエラー名を付ける一連の組み込み文字列を定義します。すべて `States.` プレフィックスが付いています。
状態は別の名前でエラーを報告することがあります。ただし、エラー名は `States.` プレフィックスで始めることはできません。
本番コードが AWS Lambda サービス例外 (`Lambda.ServiceException` および ) を処理できることを確認します`Lambda.SdkClientException`。詳細については、「*ベストプラクティス*」で [Lambda サービスの一時的な例外の処理](sfn-best-practices.md#bp-lambda-serviceexception) の方法を参照してください。
** `States.ALL` **
あらゆる既知のエラー名に一致するワイルドカード。
`States.ALL` エラータイプは `Catcher` に単独で記述する必要があり、`States.DataLimitExceeded` 致命的エラーや `Runtime` エラータイプはキャッチできません。
詳細については、「[`States.DataLimitExceeded`](#error-data-limit-exceed)」および「[`States.Runtime`](#states-runtime-error)」を参照してください。
** `States.DataLimitExceeded` **
`States.ALL` エラータイプではキャッチできない致命的エラーです。
以下の条件により報告されます。
+ コネクタの出力がペイロードサイズのクォータを超えた。
+ ステートの出力がペイロードサイズのクォータを超えた。
+ `Parameters` の処理後、ステートの入力がペイロードサイズのクォータを超えた。
クォータに関する詳細については、[Step Functions のサービスクォータ](service-quotas.md) を参照してください。
**`States.ExceedToleratedFailureThreshold`**
失敗したアイテムの数がステートマシン定義で指定されたしきい値を超えたため、`Map` 状態が失敗しました。詳細については、「[Step Functions での分散マップ状態の失敗しきい値の設定](state-map-distributed.md#maprun-fail-threshold)」を参照してください。
** `States.HeartbeatTimeout` **
`HeartbeatSeconds` 値より長時間実行されたため ハートビートの送信に失敗した `Task` 状態。
`HeartbeatTimeout` は `Catch` および `Retry` フィールド内で使用できます。
** `States.Http.Socket` **
HTTP タスクが 60 秒後にタイムアウトすると発生します。「[HTTP タスクに関連するクォータ](service-quotas.md#service-limits-http-task)」を参照してください。
**`States.ItemReaderFailed`**
`ItemReader` フィールドに指定されたアイテムソースから読み取れなかったため、`Map` 状態が失敗しました。詳細については、「`ItemReader (Map)`」を参照してください。
** `States.Permissions` **
指定されたコードの実行に必要な特権が足りないため `Task` 状態が失敗しました。
**`States.ResultWriterFailed`**
`ResultWriter` フィールドに指定された宛先に結果を書き込めなかったため、`Map` 状態が失敗しました。詳細については、「`ResultWriter (Map)`」を参照してください。
**`States.Runtime`**
処理できない例外のため、実行に失敗しました。多くの場合、これらは実行時のエラー (null JSON ペイロードに `InputPath` または `OutputPath` を適用しようとしたなど) によって発生します。`States.Runtime` エラーは再試行可能ではなく、常に実行が失敗する原因になります。`States.ALL` での再試行またはキャッチでは `States.Runtime` エラーはキャッチされません。
** `States.TaskFailed` **
実行中に失敗した `Task` 状態。リトライやキャッチで使用すると、`States.TaskFailed` は、`States.Timeout` 以外のあらゆる既知のエラー名に一致するワイルドカードとして機能します。
** `States.Timeout` **
`HeartbeatSeconds` ステートが `Task` の値より長く実行されたか、`TimeoutSeconds` の値の期間内にハートビートを送信できなかった場合に報告されます。
*ネストされたステートマシン*が `States.Timeout` をスローすると、親は `States.TaskedFailed` エラーを受け取ります。
ステートマシン全体の実行が、指定された `TimeoutSeconds` の値より長く実行された場合にも、`States.Timeout` エラーが報告されます。
**注記**
Lambda ランタイムの未処理のエラーは、以前は `Lambda.Unknown` としてのみ報告されていました。新しいランタイムでは、タイムアウトはエラー出力で `Sandbox.Timedout` として報告されます。
Lambda が最大呼び出し回数を超えると、報告されるエラーは `Lambda.TooManyRequestsException` となります。
`Lambda.Unknown`、`Sandbox.Timedout`、`States.TaskFailed` で照合して、考えられるエラーを処理します。`States.ALL` も使用できますが、単独で、かつリストの最後に記述する必要があります。
Lambda `Handled` と `Unhandled` エラーの詳細については、[AWS Lambda デベロッパーガイド](https://docs.aws.amazon.com/lambda/latest/dg/API_Invoke.html#API_Invoke_ResponseSyntax)の `FunctionError` を参照してください。
## エラー後の再試行
`Task`、`Parallel`、`Map` の状態は `Retry` という名前のフィールドを持つことができます。その値は *Retrier* と呼ばれるオブジェクトの配列にする必要があります。個々の retrier は特定回数の再試行を表し、通常は時間間隔が増加していきます。
いずれかの状態がエラーを報告し、`Retry` フィールドがある場合、Step Functions は配列にリストされた順序で Retrier をスキャンします。Retrier の `ErrorEquals` フィールドの値にエラー名が表示されると、ステートマシンは `Retry` フィールドで定義されているとおりに再試行します。
[再試行](#error-handling-retrying-after-an-error)を定義した、[Task ワークフロー状態](state-task.md)、[Parallel ワークフローの状態](state-parallel.md)、または [インラインマップステート](state-map-inline.md)を redriven で再実行すると、redrive での再試行回数が最大になるように、これらのステートの再試行回数は 0 にリセットされます。redriven 実行では、コンソールを使用してこれらのステートでの再試行を個別に追跡できます。詳細については、「[Step Functions で redrive を使用してステートマシン実行を再開する](redrive-executions.md)」の [再処理された実行の再試行動作](redrive-executions.md#redrive-retry-behavior) を参照してください。
retrier には以下のフィールドがあります。
** `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 秒の間でランダム化されます。
**注記**
再試行は状態遷移として扱われます。状態遷移が課金に及ぼす影響については、[Step Functions コスト](https://aws.amazon.com/step-functions/pricing/)を参照してください。
### 再試行フィールドの例
このセクションには、次の `Retry` フィールドの例が含まれます。
+ [Retry with BackoffRate](#retrybackoffrate)
+ [Retry with MaxDelaySeconds](#retrymaxdelayseconds)
+ [Retry all errors except States.Timeout](#retrytimeout)
+ [Complex retry scenario](#complexretryeg)
**例 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:region: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` (JSONPath、オプション)**
`Next` フィールドに指定された状態に catcher が送信する入力を決定する[パス](concepts-input-output-filtering.md)。
状態がエラーを報告し、`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 はいくつのエラーをキャッチできますか?**
各 catcher には、処理対象となる**複数のエラー**を指定できます。
### エラー出力
Step Functions が catch 名に指定された状態に移行する場合、オブジェクトには通常 `Cause` というフィールドが含まれます。このフィールドの値は人間が読んで理解できるエラーの説明です。このオブジェクトは*エラー出力*といいます。
前の JSONPath の例では、最初の catcher に `ResultPath` フィールドが含まれています。これは状態の最上位の `ResultPath` フィールドに似た動作を行い、次のいずれかの結果になります。
+ そのステートの実行結果を取得して、ステートの入力全体または一部を上書きします。
+ その結果を取得し、入力に追加します。catcher によって処理されたエラーの場合、状態の実行の結果はエラー出力です。
したがって、この例の最初の catcher の場合、catcher がエラー出力が `error-info` という名前のフィールドとして入力に追加します (入力にこの名前のフィールドが存在しない場合)。次に、catcher は入力全体を `RecoveryState` に送信します。2 番目 catcher では、エラー出力によって入力が上書きされ、catcher はエラー出力のみを `EndState` に送信します。
JSONPath ワークフローでは、`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 関数を作成する](tutorial-creating-lambda-state-machine.md#create-lambda-function)」セクションを参照してください。
```
exports.handler = (event, context, callback) => {
callback("error");
};
```
これは、10 秒間スリープする Node.js Lambda 関数の定義です。続くステートマシンの例では、この Lambda 関数の名前は `sleep10` です。
```
exports.handler = (event, context, callback) => {
setTimeout(function(){
}, 11000);
};
```
**関数のタイムアウト設定**
例用に Lambda 関数を作成するときは、忘れずに詳細設定で `Timeout` の値を 11 秒に設定してください。
### Retry を使用して失敗を処理する
このステートマシンは `Retry` フィールドを使用して、失敗してエラー名 `HandledError` を出力する関数を再試行します。この関数は 2 回再試行され、再試行間にはエクスポネンシャルパックオフが使用されます。
```
{
"Comment": "A Hello World example invoking Lambda function",
"StartAt": "HelloWorld",
"States": {
"HelloWorld": {
"Type": "Task",
"Resource": "arn:aws:lambda:region:123456789012:function:FailFunction",
"Retry": [ {
"ErrorEquals": ["HandledError"],
"IntervalSeconds": 1,
"MaxAttempts": 2,
"BackoffRate": 2.0
} ],
"End": true
}
}
}
```
このバリエーションでは、Lambda 関数が出力するあらゆるエラーに一致する事前定義されたエラーコード `States.TaskFailed` を使用します。
```
{
"Comment": "Hello World example which invokes a AWS Lambda function",
"StartAt": "HelloWorld",
"States": {
"HelloWorld": {
"Type": "Task",
"Resource": "arn:aws:lambda:region:123456789012:function:FailFunction",
"Retry": [ {
"ErrorEquals": ["States.TaskFailed"],
"IntervalSeconds": 1,
"MaxAttempts": 2,
"BackoffRate": 2.0
} ],
"End": true
}
}
}
```
**Lambda 例外の処理に関するベストプラクティス**
Lambda 関数を参照するタスクは、Lambda サービスの例外を処理する必要があります。詳細については、「ベストプラクティス」の「[Lambda サービスの一時的な例外の処理](sfn-best-practices.md#bp-lambda-serviceexception)」を参照してください。
### Catch を使用して失敗を処理する
この例では、`Catch` フィールドを使用します。Lambda 関数がエラーを出力すると、そのエラーをキャッチし、ステートマシンは `fallback` 状態に移行します。
```
{
"Comment": "Hello World example which invokes a AWS Lambda function",
"StartAt": "HelloWorld",
"States": {
"HelloWorld": {
"Type": "Task",
"Resource": "arn:aws:lambda:region:123456789012:function:FailFunction",
"Catch": [ {
"ErrorEquals": ["HandledError"],
"Next": "fallback"
} ],
"End": true
},
"fallback": {
"Type": "Pass",
"Result": "Hello, AWS Step Functions!",
"End": true
}
}
}
```
このバリエーションでは、Lambda 関数が出力するあらゆるエラーに一致する事前定義されたエラーコード `States.TaskFailed` を使用します。
```
{
"Comment": "Hello World example which invokes a AWS Lambda function",
"StartAt": "HelloWorld",
"States": {
"HelloWorld": {
"Type": "Task",
"Resource": "arn:aws:lambda:region: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": "Hello World example which invokes a AWS Lambda function",
"StartAt": "HelloWorld",
"States": {
"HelloWorld": {
"Type": "Task",
"Resource": "arn:aws:lambda:region:123456789012:function:sleep10",
"TimeoutSeconds": 2,
"Retry": [ {
"ErrorEquals": ["States.Timeout"],
"IntervalSeconds": 1,
"MaxAttempts": 2,
"BackoffRate": 2.0
} ],
"End": true
}
}
}
```
### Catch を使用してタイムアウトを処理する
この例では、`Catch` フィールドを使用します。タイムアウトが発生すると、ステートマシンは `fallback` 状態に移行します。
```
{
"Comment": "Hello World example which invokes a AWS Lambda function",
"StartAt": "HelloWorld",
"States": {
"HelloWorld": {
"Type": "Task",
"Resource": "arn:aws:lambda:region:123456789012:function:sleep10",
"TimeoutSeconds": 2,
"Catch": [ {
"ErrorEquals": ["States.Timeout"],
"Next": "fallback"
} ],
"End": true
},
"fallback": {
"Type": "Pass",
"Result": "Hello, AWS Step Functions!",
"End": true
}
}
}
```
**JSONPath でのステートの入力とエラーの保持**
JSONPath では、`ResultPath` を使用してステートの入力とエラーを保持できます。「[ResultPath を使用してエラーと入力の両方を `Catch` に含める](input-output-resultpath.md#input-output-resultpath-catch)」を参照してください。