TestState API用于测试 Step Functions 中的状态 - AWS Step Functions
有关使用注意事项 TestState API在中使用检查级别 TestState APIIAM使用权限 TestState API测试状态（控制台）使用 AWS CLI 测试状态测试和调试输入和输出数据流

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

TestState API用于测试 Step Functions 中的状态

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

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

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

IAM扮演的角色必须包含您所在州访问的资源所需的IAM权限。TestState API有关状态可能需要的权限的信息，请参阅IAM使用权限 TestState API。

有关使用注意事项 TestState API

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

使用时 TestStateAPI，请记住以下注意事项。

在中使用检查级别 TestState API

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

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

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

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

INFO inspectionLevel

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

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

通过测试的INFO关卡输出屏幕截图。

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

失败测试的INFO关卡输出屏幕截图。

DEBUG inspectionLevel

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

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

  • input：原始状态输入

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

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

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

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

通过测试的DEBUG关卡输出屏幕截图。

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

失败测试的DEBUG关卡输出屏幕截图。

TRACE inspectionLevel

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

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

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

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

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

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

通过测试的TRACE关卡输出屏幕截图。

IAM使用权限 TestState API

调用的IAM用户TestStateAPI必须具有执行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 的 “检查器” 面板 面板中选择测试状态。

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

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

    2. （可选）提供所选州测试所需的任何JSON输入。

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

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

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

      • TRACE— 显示原始HTTP请求和响应，可用于验证标头、查询参数和其他API特定详细信息。此选项仅适用于HTTP任务。

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

    4. 选择开始测试。

使用 AWS CLI 测试状态

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

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

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

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

要使用INFOinspectionLevel中的测试状态 AWS 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 调试在 “通过” 状态下的输入和输出数据处理

要使用DEBUGinspectionLevel中的测试状态 AWS 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

此示例使用传递工作流程状态状态来展示如何使用输入和输出JSON数据处理Step Functions过滤器筛选和操作输入数据。此示例使用以下筛选器：InputPath、参数、在 Step Functions 工作流程 ResultPath 中使用指定状态输出 和 在 Step Functions 工作流程 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 检查发送给第三方的HTTP请求 API

要使用和中的revealSecrets参数测试HTTP任务 AWS CLI，请TRACEinspectionLevel按以下示例所示运行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数据。以下AWS 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) 中的所有状态类型（任务、并行、地图、通过、等待、选择、成功和失败）共享一组公共字段，用于筛选和操作通过它们JSON的数据。这些字段包括：InputPath、参数、ResultSelector、在 Step Functions 工作流程 ResultPath 中使用指定状态输出 和 在 Step Functions 工作流程 OutputPath 中使用筛选状态输出。对每个字段的支持因状态而异。在运行时，Step Functions 按特定顺序应用每个字段。下图显示了在 Task 状态内这些字段应用于数据的顺序：

筛选器顺序： InputPath、参数 ResultSelector、 ResultPath、和 OutputPath。

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

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

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

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

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

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

  6. 在 Step Functions 工作流程 ResultPath 中使用指定状态输出 将结果与原始状态输入合并，或者用它替换结果。

  7. 在 Step Functions 工作流程 OutputPath 中使用筛选状态输出 筛选输出的一部分以传递到下一状态。

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

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

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

当您调用TestStateAPI并将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对象中的相应字段：

该图显示了ASL字段与的映射inspectionData。

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