Step Functions エラー処理

状態でランタイムエラーが発生することがあります。エラーはさまざまな理由で発生します。

• ステートマシンの定義の問題 (たとえば、Choice 状態に一致するルールがない)。

• タスクの失敗 (たとえば、Lambda 関数の例外)。

• 一時的な問題 (たとえば、ネットワークパーティションイベント)。

デフォルトでは、状態がエラーを報告すると、AWS Step Functions の実行全体が失敗します。

エラー名

Step Functions は大文字と小文字を区別する文字列を使用して Amazon State言語でエラーを識別します。これをエラー名。Amazon States Language は、よく知られているエラー名付ける一連の組み込み文字列を定義します。すべてStates.prefix.

States.ALL

すべての既知のエラー名に一致するワイルドカード。

States.DataLimitExceeded

AStates.DataLimitExceeded例外は、次の場合にスローされます。

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

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

• いつ, 後Parameters処理では、状態の入力がペイロードサイズクォータよりも大きくなります。

クォータの詳細については、「」を参照してください。標準ワークフローのクォータおよびExpress ワークフローのクォータ。

States.Runtime

処理できなかった例外のため、実行に失敗しました。多くの場合、これらは実行時のエラー (null JSON ペイロードに InputPath または OutputPath を適用しようとしたなど) によって発生します。States.Runtime エラーは再試行可能ではなく、常に実行が失敗します。States.ALL での再試行またはキャッチでは States.Runtime エラーは検出されません。

States.Timeout

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

States.TaskFailed

実行中に失敗した Task 状態。再試行またはキャッチで使用すると、States.TaskFailedは、すべての既知のエラー名に一致するワイルドカードとして機能します。States.Timeout。

States.Permissions

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

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

ベストプラクティスとしては、本番稼働用コードが AWS Lambda サービス例外 (Lambda.ServiceExceptionおよびLambda.SdkClientException). 詳細については、「Lambda サービスの例外を処理する」を参照してください。

注記

Lambda での未処理のエラーはLambda.Unknownをエラー出力に入力します。これには、メモリ不足エラーや関数のタイムアウトが含まれます。あなたは上で一致することができますLambda.Unknown,States.ALL, またはStates.TaskFailedを使用してこれらのエラーを処理します。Lambda が最大呼び出し回数に達すると、エラーはLambda.TooManyRequestsException。Lambda の詳細については、「」を参照してください。HandledおよびUnhandledエラーの詳細については、FunctionError()AWS Lambda デベロッパーガイド。

エラー後の再試行

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

注記

再試行は状態遷移として扱われます。状態遷移が課金に及ぼす影響については、「」を参照してください。Step Functions。

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

ErrorEquals (必須)

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

IntervalSeconds（オプション）

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

MaxAttempts（オプション）

再試行の最大回数を表す正の整数 (デフォルトでは 3)。エラーが指定された回数を超えて再発する場合は、再試行が停止され通常のエラー処理が再開されます。値 0 を指定すると、エラーは再試行されません。

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

このタスクは 5 回連続で失敗し、エラー名 ErrorA、ErrorB、ErrorC、ErrorB、および ErrorB を出力します。結果として以下が発生します。

• 最初の 2 つのエラーが最初の retrier に一致し、1 秒および 2 秒の待機が発生します。

• 3 番目のエラーが 2 番目の retrier に一致し、5 秒の待機が発生します。

• 4 番目のエラーが 1 番目の retrier に一致し、4 秒の待機が発生します。

• 5 番目のエラーも最初の retrier に一致します。ただし、その特定のエラー (ErrorB) における再試行の上限 (MaxAttempts) である 2 回にすでに達しているため、再試行は失敗し、実行は Catch フィールドを介して Z 状態にリダイレクトされます。

フォールバック状態

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フィールドはという状態に移行します。RecoveryStateLambda 関数が未処理の Java 例外を出力するとき。それ以外の場合は、フィールドは 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 は最初に該当する retriers を使用し、その後、再試行ポリシーがエラーを解決できなかった場合、一致する 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 つはステートマシンで定義されたタイムアウトが発生するのに十分な時間待機します。

これは、常に失敗してメッセージを返す Lambda 関数の定義です。error。以下のステートマシンの例では、この Lambda 関数の名前はです。FailFunction。

exports.handler = (event, context, callback) => {
    callback("error");
};

これは、10 秒間スリープする Lambda 関数の定義です。以下のステートマシンの例では、この Lambda 関数の名前はです。sleep10。

注記

Lambda コンソールで Lambda 関数を作成するときは、タイムアウトの値を詳細設定セクションを 3 秒 (デフォルト) から 11 秒まで設定します。

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

[再試行] を使用した失敗の処理

このステートマシンは 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
      }
   }
}

このバリアントは、定義済みのエラーコードを使用しますStates.TaskFailedLambda 関数が出力するすべてのエラーに一致します。

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

このバリアントは、定義済みのエラーコードを使用しますStates.TaskFailedLambda 関数が出力するすべてのエラーに一致します。

{
   "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 フィールドを使用して、タイムアウトした関数を再試行します。この関数は 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 フィールドを使用します。タイムアウトが発生すると、ステートマシンは 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 に含める」を参照してください。