使用 TestState API 测试状态 - Amazon Step Functions
使用 TestState API 的注意事项在 TestState API 中使用检查级别IAM使用 TestState API 的权限测试状态（控制台）使用 Amazon CLI 测试状态测试和调试输入和输出数据流
Amazon Web Services 文档中描述的 Amazon Web Services 服务或功能可能因区域而异。要查看适用于中国区域的差异，请参阅 中国的 Amazon Web Services 服务入门 (PDF)。

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

使用 TestState API 测试状态

TestStateAPI 接受单一状态的定义并执行它。您无需创建状态机或更新现有状态机，即可测试状态。

使用 TestState API，您可以测试以下内容：

要测试状态，您还可以使用 Step Functions 控制台、Amazon Command Line Interface (Amazon CLI) 或 SDK。

TestState API 扮演一个 IAM 角色，该角色必须针对状态访问的资源包含必需的 IAM 权限。有关状态可能需要的权限的信息，请参阅IAM使用 TestState API 的权限。

使用 TestState API 的注意事项

使用 TestStateAPI，您一次只能测试一个状态。您可以测试的状态包括：

在使用 TestState API 时，请记住以下注意事项。

  • 该 TestState API 不包括对以下内容的支持：

  • 测试最多可以运行五分钟。如果测试超过此持续时间，则会因 States.Timeout 错误而失败。

在 TestState API 中使用检查级别

要使用 TestStateAPI 测试状态，您需要提供该状态的定义。然后，测试返回输出。对于每种状态，您可以指定要在测试结果中查看的详细信息量。这些详细信息提供有关您要测试的状态的更多信息。例如，如果您使用了任何输入和输出数据处理筛选器，例如状态中的 InputPath 或 ResultPath，则可以查看中间和最终的数据处理结果。

Step Functions 提供以下级别，供您指定要查看的详细信息：

所有这些级别还会返回 status 和 nextState 字段。status 表示状态执行的状态。例如，SUCCEEDED、FAILED、RETRIABLE 和 CAUGHT_ERROR。nextState 表示要过渡到的下一个状态的名称。如果您尚未在定义中定义下一个状态，则此字段会返回一个空值。

有关在 Step Functions 控制台和 Amazon CLI 中使用这些检查级别测试状态的信息，请参阅测试状态（控制台）和使用 Amazon CLI 测试状态。

“信息”检查级别

如果测试成功，此级别会显示状态输出。如果测试失败，此级别会显示错误输出。默认情况下，如果您未指定级别，Step Functions 会将检查级别设置为信息。

下图显示了成功的 Pass 状态测试。此状态的检查级别设置为信息，该状态的输出显示在输出选项卡中。

在信息级别，所选状态的测试成功的输出。

下图显示了当检查级别设置为信息时失败的 Task 状态测试。输出选项卡会显示错误输出，其中包含错误名称和错误原因的详细说明。

在信息级别，所选状态的测试成功的输出。

“调试”检查级别

如果测试成功，此级别会显示状态输出以及输入和输出数据处理的结果。

如果测试失败，此级别会显示错误输出。此级别显示最多到故障点的中间数据处理结果。例如，假设您测试了一个调用 Lambda 函数的 Task 状态。想象一下，您已向 Task 状态应用 InputPath、参数、ResultPath 和 OutputPath 筛选器。假设调用失败。在此例中，DEBUG 级别基于应用的筛选器按以下顺序显示数据处理结果：

  • input：原始状态输入

  • afterInputPath：Step Functions 应用 InputPath 筛选器后的输入。

  • afterParameters：Step Functions 应用 Parameters 筛选器后的有效输入。

此级别中提供的诊断信息可以帮助您排查与服务集成或您可能已定义的输入和输出数据处理流相关的问题。

下图显示了成功的 Pass 状态测试。此状态的检查级别设置为调试。下图中的输入/输出处理选项卡显示了在针对提供的输入应用 Parameters 后此状态的结果。

在调试级别，所选状态的测试成功的输出。

下图显示了当检查级别设置为调试时失败的 Task 状态测试。下图中的输入/输出处理选项卡显示了此状态最多到故障点的输入和输出数据处理结果。

在调试级别，状态的测试失败的输出。

“跟踪”检查级别

Step Functions 提供用于测试 HTTP 任务的跟踪级别。此级别会返回有关 Step Functions 发出的 HTTP 请求和第三方 API 返回的响应的信息。响应可能包含标头和请求正文等信息。此外，您还可以在此级别查看状态输出以及输入和输出数据处理的结果。

如果测试失败，此级别会显示错误输出。

此级别仅适用于 HTTP 任务。如果您将此级别用于其他状态类型，则 Step Functions 会抛出错误。

将检查级别设置为 TRACE 时，您还可以查看EventBridge 连接中包含的密钥。为此，您必须在 TestStateAPI true 中将revealSecrets参数设置为。此外，您必须确保调用 TestState API 的IAM用户拥有该states:RevealSecrets操作的权限。有关设置 states:RevealSecrets 权限的 IAM 策略示例，请参阅IAM使用 TestState API 的权限。如果没有此权限，则 Step Functions 会抛出访问遭拒错误。

如果您将 revealSecrets 参数设置为 false，则 Step Functions 会省略 HTTP 请求和响应数据中的所有密钥。

下图显示了成功的 HTTP 任务测试。此状态的检查级别设置为跟踪。下图中的 HTTP 请求和响应选项卡显示了第三方 API 调用的结果。

在跟踪级别，所选状态的测试成功的输出。

IAM使用 TestState API 的权限

调用 TestState API 的 IAM 用户必须有权执行 states:TestState 和 iam:PassRole 操作。此外，如果您将 revealSecrets 参数设置为 true，则必须确保 IAM 用户有权执行 states:RevealSecrets 操作。如果没有此权限，则 Step Functions 会抛出访问遭拒错误。

此外，对于您的状态访问的资源，您还必须确保执行角色包含必需的 IAM 权限。有关状态可能需要的权限的信息，请参阅管理执行角色。

以下 IAM 策略示例设置了 states:TestState、iam:PassRole 和 states:RevealSecrets 权限。

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "states:TestState",
        "states:RevealSecrets",
        "iam:PassRole"
      ],
      "Resource": "*"
    }
  ]
}

测试状态（控制台）

您可以在控制台中测试状态，并检查状态输出或输入和输出数据处理流。对于 HTTP 任务，您可以测试原始 HTTP 请求和响应。

测试状态

  1. 打开 Step Functions 控制台。

  2. 选择创建状态机开始创建状态机，或选择一个现有状态机。

  3. 在 Workflow Studio 的设计模式中，选择要测试的状态。

  4. 从 Workflow Studio 的 Inspector 面板中选择测试状态。

  5. 在测试状态对话框中，执行以下操作：

    1. 对于执行角色，选择一个执行角色来测试状态。请确保您对要测试的状态具有必需的 IAM 权限。

    2. （可选）针对测试提供所选状态需要的任何 JSON 输入。

    3. 对于检查级别，根据要查看的值选择以下选项之一：

      • 信息：如果测试成功，此级别会在输出选项卡中显示状态输出。如果测试失败，信息级别会显示错误输出，其中包含错误名称和错误原因的详细说明。默认情况下，如果您未选择级别，Step Functions 会将检查级别设置为信息。

      • 调试：如果测试成功，此级别会显示状态输出以及输入和输出数据处理的结果。如果测试失败，调试级别会显示错误输出，其中包含错误名称和错误原因的详细说明。

      • 跟踪：此级别会显示原始的 HTTP 请求和响应，对于验证标头、查询参数和其他特定于 API 的详细信息非常有用。此选项仅适用于 HTTP 任务。

        您可以根据需要选择显示密钥。结合跟踪检查级别，此设置可让您查看 EventBridge 连接插入的敏感数据，例如 API 密钥。您用于访问控制台的 IAM 用户身份必须具有执行 states:RevealSecrets 操作的权限。如果没有此权限，则在您开始测试时 Step Functions 会抛出访问遭拒错误。有关设置 states:RevealSecrets 权限的 IAM 策略示例，请参阅IAM使用 TestState API 的权限。

    4. 选择开始测试。

使用 Amazon CLI 测试状态

您可以使用中的 TestStateAPI 来测试支持的状态Amazon CLI。此 API 会接受状态的定义并执行它。

对于每种状态，您可以指定要在测试结果中查看的详细信息量。这些详细信息提供有关状态执行的额外信息，包括其输入和输出数据处理结果以及 HTTP 请求和响应信息。以下示例展示了您可以为 TestState API 指定的不同检查级别。切记用特定资源信息替换斜体文本。

本部分包含以下示例，它们说明了如何使用 Step Functions 在 Amazon CLI 中提供的不同检查级别：

示例 1：使用 INFO inspectionLevel 来测试 Choice 状态

要使用中的 Insp INFO ectionLevel 测试状态 Amazon CLI，请按以下示例所示运行test-state命令。

aws stepfunctions test-state \
    --definition '{"Type": "Choice", "Choices": [{"Variable": "$.number", "NumericEquals": 1, "Next": "Equals 1"}, {"Variable": "$.number", "NumericEquals": 2, "Next": "Equals 2"}], "Default": "No Match"}' \
    --role-arn arn:aws:iam::123456789012:role/myRole \
    --input '{"number": 2}'

此示例使用 Choice 状态根据您提供的数字输入来确定该状态的执行路径。默认情况下，如果您未设置级别，Step Functions 会将 inspectionLevel 设置为 INFO。

Step Functions 返回以下输出：

{
    "output": "{\"number\": 2}",
    "nextState": "Equals 2",
    "status": "SUCCEEDED"
}

示例 2：使用 DEBUG inspectionLevel 针对 Pass 状态调试输入和输出数据处理

要使用中的 Insp DEBUG ectionLevel 测试状态 Amazon CLI，请按以下示例所示运行test-state命令。

aws stepfunctions test-state \
    --definition '{"Type": "Pass", "InputPath": "$.payload", "Parameters": {"data": 1}, "ResultPath": "$.result", "OutputPath": "$.result.data", "Next": "Another State"}' \
    --role-arn arn:aws:iam::123456789012:role/myRole \
    --input '{"payload": {"foo": "bar"}}' \
    --inspection-level DEBUG

此示例使用 Pass 状态来展示 Step Functions 如何使用输入和输出数据处理筛选器来筛选和处理输入 JSON 数据。此示例使用以下筛选器：InputPath、参数、ResultPath 和 OutputPath。

Step Functions 返回以下输出：

{
    "output": "1",
    "inspectionData": {
        "input": "{\"payload\": {\"foo\": \"bar\"}}",
        "afterInputPath": "{\"foo\":\"bar\"}",
        "afterParameters": "{\"data\":1}",
        "afterResultSelector": "{\"data\":1}",
        "afterResultPath": "{\"payload\":{\"foo\":\"bar\"},\"result\":{\"data\":1}}"
    },
    "nextState": "Another State",
    "status": "SUCCEEDED"
}

示例 3：使用 TRACE inspectionLevel 和 revealSecrets 检查发送到第三方 API 的 HTTP 请求

要使用 Insp TRACE ectionLevel 和中的 revealSecret s 参数测试 HTTP 任务 Amazon CLI，请按以下test-state示例所示运行命令。

aws stepfunctions test-state \
    --definition '{"Type": "Task", "Resource": "arn:aws:states:::http:invoke", "Parameters": {"Method": "GET", "Authentication": {"ConnectionArn": "arn:aws:events:us-east-1:123456789012:connection/MyConnection/0000000-0000-0000-0000-000000000000"}, "ApiEndpoint": "https://httpbin.org/get", "Headers": {"definitionHeader": "h1"}, "RequestBody": {"message": "Hello from Step Functions!"}, "QueryParameters": {"queryParam": "q1"}}, "End": true}' \
    --role-arn arn:aws:iam::123456789012:role/myRole \
    --inspection-level TRACE \
    --reveal-secrets

此示例测试 HTTP 任务是否调用了指定的第三方 API，https://httpbin.org/。它还会显示 API 调用的 HTTP 请求和响应数据。

{
    "output": "{\"Headers\":{\"date\":[\"Tue, 21 Nov 2023 00:06:17 GMT\"],\"access-control-allow-origin\":[\"*\"],\"content-length\":[\"620\"],\"server\":[\"gunicorn/19.9.0\"],\"access-control-allow-credentials\":[\"true\"],\"content-type\":[\"application/json\"]},\"ResponseBody\":{\"args\":{\"QueryParam1\":\"QueryParamValue1\",\"queryParam\":\"q1\"},\"headers\":{\"Authorization\":\"Basic XXXXXXXX\",\"Content-Type\":\"application/json; charset=UTF-8\",\"Customheader1\":\"CustomHeaderValue1\",\"Definitionheader\":\"h1\",\"Host\":\"httpbin.org\",\"Range\":\"bytes=0-262144\",\"Transfer-Encoding\":\"chunked\",\"User-Agent\":\"Amazon|StepFunctions|HttpInvoke|us-east-1\",\"X-Amzn-Trace-Id\":\"Root=1-0000000-0000-0000-0000-000000000000\"},\"origin\":\"12.34.567.891\",\"url\":\"https://httpbin.org/get?queryParam=q1&QueryParam1=QueryParamValue1\"},\"StatusCode\":200,\"StatusText\":\"OK\"}",
    "inspectionData": {
        "input": "{}",
        "afterInputPath": "{}",
        "afterParameters": "{\"Method\":\"GET\",\"Authentication\":{\"ConnectionArn\":\"arn:aws:events:us-east-1:123456789012:connection/foo/a59c10f0-a315-4c1f-be6a-559b9a0c6250\"},\"ApiEndpoint\":\"https://httpbin.org/get\",\"Headers\":{\"definitionHeader\":\"h1\"},\"RequestBody\":{\"message\":\"Hello from Step Functions!\"},\"QueryParameters\":{\"queryParam\":\"q1\"}}",
        "result": "{\"Headers\":{\"date\":[\"Tue, 21 Nov 2023 00:06:17 GMT\"],\"access-control-allow-origin\":[\"*\"],\"content-length\":[\"620\"],\"server\":[\"gunicorn/19.9.0\"],\"access-control-allow-credentials\":[\"true\"],\"content-type\":[\"application/json\"]},\"ResponseBody\":{\"args\":{\"QueryParam1\":\"QueryParamValue1\",\"queryParam\":\"q1\"},\"headers\":{\"Authorization\":\"Basic XXXXXXXX\",\"Content-Type\":\"application/json; charset=UTF-8\",\"Customheader1\":\"CustomHeaderValue1\",\"Definitionheader\":\"h1\",\"Host\":\"httpbin.org\",\"Range\":\"bytes=0-262144\",\"Transfer-Encoding\":\"chunked\",\"User-Agent\":\"Amazon|StepFunctions|HttpInvoke|us-east-1\",\"X-Amzn-Trace-Id\":\"Root=1-0000000-0000-0000-0000-000000000000\"},\"origin\":\"12.34.567.891\",\"url\":\"https://httpbin.org/get?queryParam=q1&QueryParam1=QueryParamValue1\"},\"StatusCode\":200,\"StatusText\":\"OK\"}",
        "afterResultSelector": "{\"Headers\":{\"date\":[\"Tue, 21 Nov 2023 00:06:17 GMT\"],\"access-control-allow-origin\":[\"*\"],\"content-length\":[\"620\"],\"server\":[\"gunicorn/19.9.0\"],\"access-control-allow-credentials\":[\"true\"],\"content-type\":[\"application/json\"]},\"ResponseBody\":{\"args\":{\"QueryParam1\":\"QueryParamValue1\",\"queryParam\":\"q1\"},\"headers\":{\"Authorization\":\"Basic XXXXXXXX\",\"Content-Type\":\"application/json; charset=UTF-8\",\"Customheader1\":\"CustomHeaderValue1\",\"Definitionheader\":\"h1\",\"Host\":\"httpbin.org\",\"Range\":\"bytes=0-262144\",\"Transfer-Encoding\":\"chunked\",\"User-Agent\":\"Amazon|StepFunctions|HttpInvoke|us-east-1\",\"X-Amzn-Trace-Id\":\"Root=1-0000000-0000-0000-0000-000000000000\"},\"origin\":\"12.34.567.891\",\"url\":\"https://httpbin.org/get?queryParam=q1&QueryParam1=QueryParamValue1\"},\"StatusCode\":200,\"StatusText\":\"OK\"}",
        "afterResultPath": "{\"Headers\":{\"date\":[\"Tue, 21 Nov 2023 00:06:17 GMT\"],\"access-control-allow-origin\":[\"*\"],\"content-length\":[\"620\"],\"server\":[\"gunicorn/19.9.0\"],\"access-control-allow-credentials\":[\"true\"],\"content-type\":[\"application/json\"]},\"ResponseBody\":{\"args\":{\"QueryParam1\":\"QueryParamValue1\",\"queryParam\":\"q1\"},\"headers\":{\"Authorization\":\"Basic XXXXXXXX\",\"Content-Type\":\"application/json; charset=UTF-8\",\"Customheader1\":\"CustomHeaderValue1\",\"Definitionheader\":\"h1\",\"Host\":\"httpbin.org\",\"Range\":\"bytes=0-262144\",\"Transfer-Encoding\":\"chunked\",\"User-Agent\":\"Amazon|StepFunctions|HttpInvoke|us-east-1\",\"X-Amzn-Trace-Id\":\"Root=1-0000000-0000-0000-0000-000000000000\"},\"origin\":\"12.34.567.891\",\"url\":\"https://httpbin.org/get?queryParam=q1&QueryParam1=QueryParamValue1\"},\"StatusCode\":200,\"StatusText\":\"OK\"}",
        "request": {
            "protocol": "https",
            "method": "GET",
            "url": "https://httpbin.org/get?queryParam=q1&QueryParam1=QueryParamValue1",
            "headers": "[definitionHeader: h1, Authorization: Basic XXXXXXXX, CustomHeader1: CustomHeaderValue1, User-Agent: Amazon|StepFunctions|HttpInvoke|us-east-1, Range: bytes=0-262144]",
            "body": "{\"message\":\"Hello from Step Functions!\",\"BodyKey1\":\"BodyValue1\"}"
        },
        "response": {
            "protocol": "https",
            "statusCode": "200",
            "statusMessage": "OK",
            "headers": "[date: Tue, 21 Nov 2023 00:06:17 GMT, content-type: application/json, content-length: 620, server: gunicorn/19.9.0, access-control-allow-origin: *, access-control-allow-credentials: true]",
            "body": "{\n  \"args\": {\n    \"QueryParam1\": \"QueryParamValue1\", \n    \"queryParam\": \"q1\"\n  }, \n  \"headers\": {\n    \"Authorization\": \"Basic XXXXXXXX\", \n    \"Content-Type\": \"application/json; charset=UTF-8\", \n    \"Customheader1\": \"CustomHeaderValue1\", \n    \"Definitionheader\": \"h1\", \n    \"Host\": \"httpbin.org\", \n    \"Range\": \"bytes=0-262144\", \n    \"Transfer-Encoding\": \"chunked\", \n    \"User-Agent\": \"Amazon|StepFunctions|HttpInvoke|us-east-1\", \n    \"X-Amzn-Trace-Id\": \"Root=1-0000000-0000-0000-0000-000000000000\"\n  }, \n  \"origin\": \"12.34.567.891\", \n  \"url\": \"https://httpbin.org/get?queryParam=q1&QueryParam1=QueryParamValue1\"\n}\n"
        }
    },
    "status": "SUCCEEDED"
}
显示更多显示更少

示例 4：使用 jq 实用程序筛选并打印 TestState API 返回的响应

TestState API 在其响应中以转义字符串形式返回 JSON 数据。以下Amazon CLI示例扩展了示例 3，并使用该jq实用程序筛选和打印 TestState API 以人类可读的格式返回的 HTTP 响应。有关信息jq及其安装说明，请参阅 jq on。GitHub

aws stepfunctions test-state \
    --definition '{"Type": "Task", "Resource": "arn:aws:states:::http:invoke", "Parameters": {"Method": "GET", "Authentication": {"ConnectionArn": "arn:aws:events:us-east-1:123456789012:connection/MyConnection/0000000-0000-0000-0000-000000000000"}, "ApiEndpoint": "https://httpbin.org/get", "Headers": {"definitionHeader": "h1"}, "RequestBody": {"message": "Hello from Step Functions!"}, "QueryParameters": {"queryParam": "q1"}}, "End": true}' \
    --role-arn arn:aws:iam::123456789012:role/myRole \
    --inspection-level TRACE \
    --reveal-secrets \
    | jq '.inspectionData.response.body | fromjson'

以下示例显示了以人类可读的格式返回的输出。

{
  "args": {
    "QueryParam1": "QueryParamValue1",
    "queryParam": "q1"
  },
  "headers": {
    "Authorization": "Basic XXXXXXXX",
    "Content-Type": "application/json; charset=UTF-8",
    "Customheader1": "CustomHeaderValue1",
    "Definitionheader": "h1",
    "Host": "httpbin.org",
    "Range": "bytes=0-262144",
    "Transfer-Encoding": "chunked",
    "User-Agent": "Amazon|StepFunctions|HttpInvoke|us-east-1",
    "X-Amzn-Trace-Id": "Root=1-0000000-0000-0000-0000-000000000000"
  },
  "origin": "12.34.567.891",
  "url": "https://httpbin.org/get?queryParam=q1&QueryParam1=QueryParamValue1"
}

测试和调试输入和输出数据流

TestState API 有助于测试和调试流经您的工作流的数据。本节提供了一些关键概念，并说明了如何 TestState 为此目的使用。

重要概念

在 Step Functions 中，在 JSON 数据经历状态机中的状态时对其进行筛选和处理的过程称为输入和输出处理。有关其工作方式的信息，请参阅Step Functions 中的输入和输出处理。

Amazon States Language (ASL) 中的所有状态类型（Task、Parallel、Map、Pass、Wait、Choice、Succeed 和 Fail）共用一组公共字段，来筛选和处理经历它们的 JSON 数据。这些字段包括：InputPath、参数、ResultSelector、ResultPath 和 OutputPath。对每个字段的支持因状态而异。在运行时，Step Functions 按特定顺序应用每个字段。下图显示了在 Task 状态内这些字段应用于数据的顺序：

输入和输出处理

以下列表说明了图中显示的输入和输出处理字段的应用顺序。

  1. 状态输入是从先前状态传递到当前状态的 JSON 数据。

  2. InputPath 筛选部分原始状态输入。

  3. 参数 配置要传递给 Task 的一组值。

  4. 任务执行工作并返回结果。

  5. ResultSelector 从任务结果中选择一组要保留的值。

  6. ResultPath 将结果与原始状态输入合并，或者用它替换结果。

  7. OutputPath 筛选输出的一部分以传递到下一状态。

  8. 状态输出是从当前状态传递到下一状态的 JSON 数据。

这些输入和输出处理字段是可选的。如果您在状态定义中未使用这些字段中的任何一个，则任务将使用原始状态输入，并将任务结果作为状态输出返回。

TestState 用于检查输入和输出处理

当您调用 TestState API 并将 inspectionLevel 参数设置为 DEBUG 时，API 响应会包含一个名为 inspectionData 的对象。此对象包含一些字段，可帮助您检查在相应状态执行时，数据是如何筛选或处理的。以下示例显示了 Task 状态的 inspectionData 对象。

"inspectionData":   {
  "input": string, 
  "afterInputPath": string, 
  "afterParameters": string, 
  "result": string, 
  "afterResultSelector": string, 
  "afterResultPath": string,
  "output": string 
}

在此示例中，每个包含 after 前缀的字段都显示特定字段应用后的数据。例如，afterInputPath 显示应用 InputPath 字段以筛选原始状态输入的效果。下图将每个 ASL 定义字段映射到 inspectionData 对象中的相应字段：

inspectionData 对象字段与 ASL 字段的映射。

有关使用 TestState API 调试输入和输出处理的示例，请参阅以下内容：