翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。

Step Functions ワークフローでのエラー処理

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

状態がエラーを報告すると、Step Functions はデフォルトでステートマシンの実行全体を失敗させます。Step Functions には、より高度なエラー処理機能もあります。エラーをキャッチし、失敗した状態を再試行し、エラー処理プロトコルを適切に実装するようにステートマシンを設定できます。

Step Functions キャッチャーは、タスク、並列、マップの各状態で使用できますが、最上位のステートマシンの実行失敗では利用できません。予想される実行を処理するには、発信者がエラーを処理するか、それらの実行を子ワークフロー内にネストして親ワークフロー内のエラーをキャッチします。または、EventBridge バスを使用して標準ワークフローからTIMED_OUTイベントをリッスンし、失敗した実行を処理するアクションを呼び出すこともできます。

エラー名

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

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

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

エラー後の再試行

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

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

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

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

再試行フィールドの例

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

例 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 を出力します。結果として以下が発生します。

フォールバック状態

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

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

エラー出力

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

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

したがって、この例の最初の 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"
},

再試行とキャッチを使用したステートマシンの例

次の例で定義されたステートマシンには、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 です。

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

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

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