使用 TestState API 來測試狀態 - AWS Step Functions

本文為英文版的機器翻譯版本,如內容有任何歧義或不一致之處,概以英文版為準。

使用 TestState API 來測試狀態

TestStateAPI 接受單一狀態的定義並執行它。您可以在不建立狀態機或更新現有狀態機的情況下測試狀態。

使用 TestState API,您可以測試以下內容:

若要測試狀態,您也可以使用Step Functions主控台或 SDK。AWS Command Line Interface (AWS CLI)

TestStateAPI 採用 IAM 角色,該角色必須包含狀態IAM存取資源的必要許可。如需狀態可能需要的權限的資訊,請參閱IAM使用 TestState API 的權限

關於使用 TestState API 的注意事項

使用 TestStateAPI,您一次只能測試一個狀態。您可以測試的狀態包括下列各項:

使用 TestState API 時,請記住以下注意事項。

  • 該 TestState API 不包括對以下內容的支持:

  • 一個測試最多可以運行五分鐘。如果測試超過此持續時間,則會失敗並顯示States.Timeout錯誤。

在 TestState API 中使用檢驗層級

若要使用 TestStateAPI 測試狀態,請提供該狀態的定義。然後測試返回一個輸出。對於每個狀態,您可以指定要在測試結果中檢視的詳細資訊量。這些詳細資料提供有關您正在測試的狀態的其他資訊。例如,如果您已使用任何輸入和輸出資料處理篩選器 (例如InputPathResultPath狀態),則可以檢視中繼和最終資料處理結果。

Step Functions提供下列層次,以指定您要檢視的詳細資訊:

所有這些層級也會傳回statusnextState欄位。 status指示狀態執行的狀態。例如,SUCCEEDEDFAILEDRETRIABLE、和CAUGHT_ERRORnextState指示要轉換至的下一個狀態的名稱。如果您尚未在定義中定義下一個狀態,則此欄位會傳回空值。

如需有關在Step Functions主控台中使用這些檢驗層級測試狀態的資訊AWS CLI,請參閱測試狀態(控制台)使用測試狀態 AWS CLI

資訊檢驗層級

如果測試成功,則此級別顯示狀態輸出。如果測試失敗,這個級別顯示錯誤輸出。依預Step Functions設,如果您未指定圖層,請將「檢驗層級」設定為 INFO

下圖顯示成功的「通過」狀態的測試。此狀態的 [檢驗層級] 設定為 [INFO],且狀態的輸出會顯示在 [輸出] 索引標籤中。


                            選取狀態的輸出,該狀態會成功測試 INFO 層級。

下圖顯示當 [檢驗層級] 設定為 INFO 時,[工作] 狀態的測試失敗。「輸出」索引標籤會顯示錯誤輸出,其中包含錯誤名稱以及該錯誤原因的詳細說明。


                            選取狀態的輸出,該狀態會成功測試 INFO 層級。

偵錯檢測層級

如果測試成功,則此級別顯示狀態輸出以及輸入和輸出數據處理的結果。

如果測試失敗,這個級別顯示錯誤輸出。此層級會顯示直到失敗點為止的中繼資料處理結果。例如,假設您測試了調用Lambda函數的 Task 狀態。假設您已將InputPath參數ResultPath、和OutputPath篩選器套用至「工作」狀態。說調用失敗了。在此情況下,DEBUG層級會依照下列順序顯示根據篩選器應用程式的資料處理結果:

  • input— 原始狀態輸入

  • afterInputPath— Step Functions 應用InputPath過濾器後的輸入。

  • afterParameters— Step Functions 應用Parameters過濾器後的有效輸入。

此層級中可用的診斷資訊可協助您疑難排解與您可能已定義的服務整合輸入和輸出資料處理流程相關的問題。

下圖顯示成功的「通過」狀態的測試。此狀態的 [檢驗層級] 設定為 [偵錯]。下圖中的輸入/輸出處理選項卡顯示了針對此狀態提供的輸入Parameters上的應用程序的結果。


                            選定狀態的輸出,該狀態會成功測試「除錯」層級。

下圖顯示當 [檢驗層級] 設定為 DE BUG 時,[工作] 狀態的測試失敗。下圖中的輸入/輸出處理選項卡顯示了直到其故障點的狀態的輸入和輸出數據處理結果。


                            未通過調試級別測試的狀態的輸出。

追蹤檢測層級

Step Functions提供跟踪級別來測試 HTTP 任務。此層級會傳回第三方 API 傳回的 Step Functions HTTP 要求和回應的相關資訊。回應可能包含資訊,例如標頭和要求主體。此外,您可以檢視此層級中輸入和輸出資料處理的狀態輸出和結果。

如果測試失敗,這個級別顯示錯誤輸出。

此層級僅適用於 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 工作的測試。此狀態的 [檢驗層級] 設定為 [TRACE]。下圖中的 HTTP 要求與回應索引標籤會顯示第三方 API 呼叫的結果。


                            選取狀態的輸出,該狀態會成功測試 TRACE 層級。

IAM使用 TestState API 的權限

呼叫 TestState API 的IAM使用者必須擁有執行states:TestStateiam:PassRole動作的權限。此外,如果您將 revealSecret 參數設定為true,則必須確定IAM使用者具有執行動作的權限。states:RevealSecrets如果沒有此權限,則Step Functions會擲回拒絕存取錯誤。

您還必須確保您的執行角色包含狀態正在訪問的資源所需的IAM權限。如需狀態可能需要之權限的相關資訊,請參閱管理執行角色

下列IAM原則範例會設定states:TestStateiam: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. 在工作流程工作室中,選擇您要測試設計模式的狀態。

  4. 在工作流程工作室的Inspector面板中選擇測試狀態

  5. 在「測試狀態」對話方塊中,執行下列操作:

    1. 對於執行角色,請選擇要測試狀態的執行角色。請確定您具有要測試之狀態的必要IAM權限

    2. (選擇性) 提供測試所選狀態所需的任何 JSON 輸入。

    3. 針對「檢驗層次」,根據您要檢視的值選取下列其中一個選項:

      • 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 指定的不同檢驗層級。請記住將斜體文本替換為特定於資源的信息。

本節包含下列範例,說明如何使用中Step Functions提供的不同檢驗層級AWS CLI:

範例 1:使用 INFO 檢查層級來測試「選擇」狀態

若要使用中的INFO檢查層級來測試狀態 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設,INFO如果您未設定樓層,則inspectionLevel將設定為。

Step Functions返回以下輸出。

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

範例 2:使用 DEBUG 檢查層級在「通過」狀態下偵錯輸入和輸出資料處理

若要使用中的DEBUG檢查層級來測試狀態 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

此範例使用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:使用追蹤檢查層級和顯示機密來檢查傳送至協力廠商 API 的 HTTP 要求

若要使用TRACE檢查層級以及中的顯示秘密參數來測試 HTTP 工作,請執行test-state命令 AWS CLI,如下列範例所示。

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及其安裝說明,敬請參閱(詳見)。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、、ResultPath、和OutputPath。每個欄位的 Sup port 會因州而異。在執行階段,會以特定順序Step Functions套用每個欄位。下圖顯示將這些欄位套用至「工作」狀態內資料的順序:


                     OutputPath 將輸入和輸出資料處理篩選器Step Functions套用的順序: InputPath ResultSelector、參數 ResultPath 和狀態。

下面的列表描述了圖中顯示的輸入和輸出處理字段的應用的順序。

  1. 狀態輸入是從先前狀態傳遞到當前狀態的 JSON 數據。

  2. InputPath過濾原始狀態輸入的一部分。

  3. 參數配置要傳遞給任務的一組值。

  4. 工作會執行工作並傳回結果。

  5. ResultSelector從工作結果中選取一組要保留的值。

  6. ResultPath結果與原始狀態輸入結合,或用它替換結果。

  7. OutputPath篩選輸出的一部分,以傳遞至下一個狀態。

  8. 狀態輸出是從當前狀態傳遞到下一個狀態的 JSON 數據。

這些輸入和輸出處理字段是可選的。如果您在狀態定義中未使用任何這些欄位,工作會使用原始狀態輸入,並將工作結果傳回為狀態輸出。

用 TestState 於檢查輸入和輸出處理

當您呼叫 TestState API 並將inspectionLevel參數設定為時DEBUG,API 回應會包含名為的物件inspectionData。此物件包含欄位,可協助您檢查資料在執行時如何在狀態內篩選或操作。下列範例顯示「工作」狀態的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 偵錯輸入和輸出處理的範例,請參閱下列內容: