AWS Step Functions
开发人员指南
AWS 文档中描述的 AWS 服务或功能可能因区域而异。要查看适用于中国区域的差异,请参阅中国的 AWS 服务入门

错误

任何状态都可能会遇到运行时错误。由于状态机定义问题(例如,Choice 状态中没有匹配规则)、任务失败(例如,来自 AWS Lambda 函数的异常)或由于暂时性问题(例如网络分区事件),会引发错误。当状态报告错误时,AWS Step Functions 的默认处理方法是完全使执行失败。

错误表示形式

在 Amazon 状态语言中使用称为错误名称的区分大小写的字符串来标识错误。Amazon 状态语言定义一组内置字符串用于命名广为人知的错误,它们均以前缀 "States." 开头:

预定义的错误代码

States.ALL

一个表示匹配任何错误名称的通配符。

States.Timeout

一个 Task 状态,该状态要么运行时间长度超过 "TimeoutSeconds" 值,要么在超过 "HeartbeatSeconds" 值的时间长度中未能发送检测信号。

States.TaskFailed

一个在执行期间失败的 Task 状态。

States.Permissions

一个 Task 状态,该状态由于没有足够的权限执行指定代码而失败。

状态可以使用其他名称报告错误,错误名称不是必须以前缀 "States." 开头。

出错后重试

TaskParallel 状态可能有名为 Retry 的字段,其值必须是称为重试器的对象的数组。一个重试器表示特定重试次数,通常重试之间的时间间隔会增加。

注意

重试被视为状态转换。有关状态转换如何影响账单的信息,请参阅 Step Functions 定价

重试器包含以下字段。

ErrorEquals (必需)

一个匹配错误名称的非空字符串数组。当状态报告错误时,Step Functions 会全面地扫描重试器,并且当错误名称出现在此数组中时,它会实现此重试器中描述的重试策略。

IntervalSeconds(可选)

一个整数,表示第一次重试之前等待的秒数 (默认值为 1)。

MaxAttempts(可选)

一个正整数,表示重试的最大次数 (默认值为 3)。如果错误重复发生超过指定次数,则停止重试并恢复正常错误处理。允许的值为 0(零),该值指示错误永远不应重试。

BackoffRate(可选)

一个在每次重试之间使重试时间间隔增长的倍数(默认值为 2.0)。

以下示例显示的是一个 Retry 字段,它在等待 3、4.5、6.75 和 10.125 秒后将重试 4 次。

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

重试器的 ErrorEquals 字段中显示的保留名称 States.ALL 是一个通配符,表示与所有错误名称匹配。它必须单独显示在 ErrorEquals 数组中,并且必须显示在 Retry 数组的最后一个重试器中。

以下示例显示的是 Retry 字段,它将重试除 States.Timeout 之外的任何错误。

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

复杂的重试场景

在单状态执行的上下文中,重试器的参数应用到对该重试器的所有访问。这可以通过一个示例来说明。考虑以下 Task 状态:

"X": { "Type": "Task", "Resource": "arn:aws-cn: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”和“ErrorB”。前两个错误与第一个重试器匹配,导致等待 1 秒和 2 秒。第三个错误与第二个重试器匹配,导致等待 5 秒。第四个错误与第一个重试器匹配,导致等待 4 秒。第五个错误也与第一个重试器匹配,但是,它已经达到了该特定错误 (“ErrorB”) 的两次重试 (“MaxAttempts”) 限制,因此失败,系统通过 "Catch" 字段将执行重定向到 "Z" 状态。

请注意,一旦系统转换为另一状态,无论什么情况都将重置所有重试器参数。

注意

您可以使用活动Lambda 函数生成自定义错误名称(例如上面的 ErrorAErrorB)。有关更多信息,请参阅使用状态机处理错误情况

回退状态

TaskParallel 状态可以具有名为 Catch 的字段,其值必须是称为捕获器的对象的数组。

捕获器包含以下字段。

ErrorEquals (必需)

一个与错误名称匹配的非空字符串数组,由同名的重试器字段完全按其原样指定。

Next (必需)

一个字符串,必须与状态机的状态名称之一完全匹配。

ResultPath(可选)

一个路径,用于确定将什么内容作为输入发送到 Next 字段所指定的状态。

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

捕获器的 ErrorEquals 字段中显示的保留名称 States.ALL 是一个通配符,表示与所有错误名称匹配。它必须单独显示在 ErrorEquals 数组中,并且必须显示在 Catch 数组的最后一个捕获器中。

以下示例显示的是一个 Catch 字段,当 Lambda 函数输出未处理的 Java 异常时,该字段将转换为“RecoveryState”状态,否则将转换为 "EndState" 状态。

"Catch": [ { "ErrorEquals": [ "java.lang.Exception" ], "ResultPath": "$.error-info", "Next": "RecoveryState" }, { "ErrorEquals": [ "States.ALL" ], "Next": "EndState" } ]

每个捕获器可以指定多个要处理的错误。

当 Step Functions 转换为捕获器中指定的状态时,它将作为输入 JSON 文本发送,该文本不同于在无错误情况下正常发送到下一个状态的文本。此 JSON 文本表示一个对象,其中包含字段 "Error",该字段的值为一个包含错误名称的字符串。通常,该对象还包含字段 "Cause",该字段具有有关错误的人类可读格式的说明。我们将此对象称为错误输出。

在本示例中,第一个捕获器包含一个 ResultPath 字段。它的工作方式类似于状态顶层的 ResultPath 字段,接受执行状态的结果,并覆盖状态输入的一部分或全部,或者接受结果并将它们添加到输入。在由捕获器处理错误时,状态执行的结果是错误输出。

因此在该示例中,对于第一个捕获器,错误输出将作为名为 error-info 的字段添加到输入(假设输入中尚不存在具有该名称的字段),并且将整个输入发送到 RecoveryState。对于第二个捕获器,错误输出将会覆盖输入,因此仅将错误输出发送到 EndState。如果未指定,则 ResultPath 字段会默认为 $,这会选择并因此覆盖整个输入。

当状态同时具有 Retry 和 Catch 字段时,Step Functions 首先使用任意合适的重试器;仅当重试策略无法解决错误时,才会应用匹配的捕获器转换。