Step Functions のエラー処理 - AWS Step Functions
エラー名エラー後の再試行Fallback 状態Retry の使用例と Catch の使用例

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

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 のブランチParallelstateFAILED

States.DataLimitExceeded

States.DataLimitExceeded の例外は、次の場合に発生します。

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

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

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

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

注記

これはターミナルエラーで、States.ALLエラータイプ。

States.HeartbeatTimeout

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

注記

このエラーはCatchそしてRetryフィールド。

States.IntrinsicFailure

このエラーは、ペイロードテンプレート内の組み込み関数の呼び出しが失敗した場合に発生します。

States.NoChoiceMatched

このランタイムエラーは、Choicestate が Choice Rule で定義された条件と入力を一致させず、デフォルト遷移が指定されていません。

States.ParameterPathFailure

このエラーは、ある州のParametersfield、名前がで終わるフィールドを置換する試み.$パスの使用は失敗します。

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 関数の呼び出しTaskstateは 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 に含める」を参照してください。