Amazon Web Services 文档中描述的 Amazon Web Services 服务或功能可能因区域而异。要查看适用于中国区域的差异，请参阅 中国的 Amazon Web Services 服务入门 (PDF)。

本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

Step Functions 中的错误处理

除 Pass 和 Wait 状态之外的所有状态都可能遇到运行时错误。有多种原因可导致错误发生，例如以下示例：

默认情况下，当某个状态报告错误时，Amazon Step Functions 会导致执行完全失败。

错误名称

Step Functions 使用区分大小写的字符串（称为错误名称）来识别 Amazon States Language 中的错误。Amazon States Language 定义了一组内置字符串用于命名广为人知的错误，均以 States. 前缀开头。

状态可以报告具有其他名称的错误。但是，这些错误名称不能以 States. 前缀开头。

作为最佳实操，确保生产代码可以处理 Amazon Lambda 服务异常（Lambda.ServiceException 和 Lambda.SdkClientException）。有关更多信息，请参阅处理 Lambda 服务异常。

出错后重试

Task、Parallel 和 Map 状态可以有名为 Retry 的字段，其值必须是称为重试器 的对象数组。单个重试器表示特定的重试次数，通常是以递增的时间间隔。

当其中一个状态报告错误并且有一个 Retry 字段时，Step Functions 会按照数组中列出的顺序扫描重试器。当错误名称出现在某个重试器的 ErrorEquals 字段中时，状态机就会按照 Retry 字段中的定义进行重试。

如果redriven执行重新运行了已定义重试的 Task、Parallel 或内联 Map 状态，这些状态的重试尝试计数将重置为 0，以便允许redrive上的最大尝试次数。对于redriven执行，您可以使用控制台跟踪这些状态的单个重试尝试。有关更多信息，请参阅Redriving执行中的redriven执行的重试行为。

重试器包含以下字段：

重试字段示例

本节包含以下 Retry 字段示例。

示例 1 – 使用 BackoffRate 重试

下面的 Retry 示例进行了两次重试，第一次重试在等待 3 秒后进行。根据指定的 BackoffRate，Step Functions 会增加每次重试的间隔时间，直到达到重试尝试的最大次数。在下面的示例中，第二次重试在第一次重试 3 秒后开始。

"Retry": [ {
   "ErrorEquals": [ "States.Timeout" ],
   "IntervalSeconds": 3,
   "MaxAttempts": 2,
   "BackoffRate": 1
} ]

示例 2 – 使用 MaxDelaySeconds 重试

以下示例进行了三次重试尝试，并将 BackoffRate 产生的等待时间限制为 5 秒。第一次重试在等待 3 秒钟后进行。由于 MaxDelaySeconds 设置了最长等待时间限制，第二次和第三次重试将在前一次重试后等待 5 秒后进行。

"Retry": [ {
    "ErrorEquals": [ "States.Timeout" ],
    "IntervalSeconds": 3,
    "MaxAttempts": 3,
    "BackoffRate":2,
    "MaxDelaySeconds": 5,
    "JitterStrategy": "FULL"
} ]

如果未设置 MaxDelaySeconds，第二次重试将在第一次重试后 6 秒进行，第三次重试将在第二次重试后 12 秒进行。

示例 3 – 重试除 States.Timeout 之外的所有错误

重试器的 ErrorEquals 字段中显示的保留名称 States.ALL 是一个通配符，与所有错误名称匹配。它必须单独显示在 ErrorEquals 数组中，并且必须显示在 Retry 数组的最后一个重试器中。名称 States.TaskFailed 也是一个通配符，可匹配除 States.Timeout 以外的任何错误。

下面的 Retry 字段示例重试了除 States.Timeout 以外的任何错误。

"Retry": [ {
   "ErrorEquals": [ "States.Timeout" ],
   "MaxAttempts": 0
}, {
   "ErrorEquals": [ "States.ALL" ]
} ]

示例 4 – 复杂的重试场景

在单状态执行的上下文中，重试器的参数应用到对该重试器的所有访问。

考虑以下 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"
   } ]
}

此任务连续失败四次，输出以下错误名称：ErrorA、ErrorB、ErrorC 和 ErrorB。出现以下结果：

回退状态

Task、Map 和 Parallel 状态可以具有名为 Catch 的字段。此字段的值必须是称为捕获器 的对象的数组。

捕获器包含以下字段。

当某个状态报告错误并且没有 Retry 字段或者重试无法解决错误时，Step Functions 按照数组中列出的顺序全面地扫描捕获器。当错误名称显示在捕获器的 ErrorEquals 字段中时，状态机转换为在 Next 字段中指定的状态。

捕获器的 ErrorEquals 字段中显示的保留名称 States.ALL 是一个通配符，与所有错误名称匹配。它必须单独显示在 ErrorEquals 数组中，并且必须显示在 Catch 数组的最后一个捕获器中。名称 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。此字段的值是人类可读格式的错误说明。该对象称为错误输出。

在本示例中，第一个捕获器包含一个 ResultPath 字段。其工作方式类似于状态顶级中的 ResultPath 字段，有两种可能的结果：

因此，在本示例中，对于第一个捕获器，如果输入中还没有名为 error-info 的字段，捕获器就会将错误输出添加到输入中。然后，捕获器会将整个输入发送到 RecoveryState。对于第二个捕获器，错误输出会覆盖输入，捕获器只会将错误输出发送到 EndState。

当状态同时包含 Retry 和 Catch 字段时，Step Functions 会首先使用任何合适的重试器。如果重试策略无法解决错误，Step Functions 会应用匹配的捕获器转换。

原因有效负载和服务集成

捕获器会返回一个字符串有效负载作为输出。在使用诸如 Amazon Athena 或 Amazon 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 的状态机示例

以下示例中定义的状态机假定存在两个 Lambda 函数：一个始终失败，另一个等待足够长的时间，以允许发生状态机中定义的超时。

这是始终失败的 Lambda 函数的定义，返回消息 error。在后面的状态机示例中，此 Lambda 函数名为 FailFunction。有关创建 Lambda 函数的信息，请参阅第 1 步：创建 Lambda 函数部分。

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

这是一个休眠 10 秒的 Lambda 函数的定义。在后面的状态机示例中，此 Lambda 函数名为 sleep10。

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

使用 Retry 处理失败

此状态机使用 Retry 字段重试失败的函数，并输出错误名称 HandledError。该函数重试两次，在两次重试之间使用指数回退。

{
   "Comment": "A Hello World example of the Amazon States Language using an Amazon 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.TaskFailed，这与 Lambda 函数输出的任意错误匹配。

{
   "Comment": "A Hello World example of the Amazon States Language using an Amazon 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
      }
   }
}

使用 Catch 处理失败

此示例使用 Catch 字段。当 Lambda 函数输出错误时，将会捕获错误，并且状态机转换为 fallback 状态。

{
   "Comment": "A Hello World example of the Amazon States Language using an Amazon 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, Amazon Step Functions!",
         "End": true
      }
   }
}

此变体使用预定义的错误代码 States.TaskFailed，这与 Lambda 函数输出的任意错误匹配。

{
   "Comment": "A Hello World example of the Amazon States Language using an Amazon 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, Amazon Step Functions!",
         "End": true
      }
   }
}

使用 Retry 处理超时

此状态机根据 TimeoutSeconds 中指定的超时值，使用 Retry 字段重试超时的 Task 状态。Step Functions 在此 Task 状态下重试两次 Lambda 函数调用，两次重试之间会出现指数回退。

{
   "Comment": "A Hello World example of the Amazon States Language using an Amazon 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 Amazon 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, Amazon Step Functions!",
         "End": true
      }
   }
}