本文為英文版的機器翻譯版本,如內容有任何歧義或不一致之處,概以英文版為準。
用 TestState API來測試 Step Functions 中的狀態
接TestStateAPI受單一狀態的定義並執行它。您可以在不建立狀態機或更新現有狀態機的情況下測試狀態。
使用 TestState API,您可以測試下列項目:
-
狀態的輸入和輸出處理數據流。
-
AWS 服務 與其他 AWS 服務 請求和響應的集成
-
HTTP任務請求和響應
若要測試狀態,您也可以使用Step Functions主控台AWS Command Line Interface (AWS 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主控台中使用這些檢驗層級測試狀態的資訊AWS CLI,請參閱測試狀態(控制台)和使用測試狀態 AWS CLI。
INFO inspectionLevel
如果測試成功,則此級別顯示狀態輸出。如果測試失敗,這個級別顯示錯誤輸出。依預Step Functions設,如果未指定樓層,INFO則將「檢驗層級」設定為。
下圖顯示成功的「通過」狀態的測試。此狀態的 [檢驗層級] 設定為,INFO且狀態的輸出會顯示在 [輸出] 索引標籤中。
![通過測試的INFO級別輸出屏幕截圖。](images/test-state-info-success.png)
下圖顯示當「檢驗層級」設定為時,「工作」狀態的測試失敗INFO。「輸出」索引標籤會顯示錯誤輸出,其中包含錯誤名稱以及該錯誤原因的詳細說明。
![失敗測試的INFO級別輸出屏幕截圖。](images/test-state-info-failed.png)
DEBUG inspectionLevel
如果測試成功,則此級別顯示狀態輸出以及輸入和輸出數據處理的結果。
如果測試失敗,這個級別顯示錯誤輸出。此層級會顯示直到失敗點為止的中繼資料處理結果。例如,假設您測試了調用Lambda函數的 Task 狀態。假設您已將InputPath、參數使用 ResultPath 「Step Functions」工作流程中指定狀態、和 OutputPath 在 Step Functions 工作流程中篩選狀態輸出篩選器套用至「工作」狀態。說調用失敗了。在此情況下,DEBUG
層級會依照下列順序顯示根據篩選器應用程式的資料處理結果:
-
input
— 原始狀態輸入 -
afterInputPath
— Step Functions 應用InputPath
過濾器後的輸入。 -
afterParameters
— Step Functions 應用Parameters
過濾器後的有效輸入。
此層級中可用的診斷資訊可協助您疑難排解與您可能已定義的服務整合或輸入和輸出資料處理流程相關的問題。
下圖顯示成功的「通過」狀態的測試。此狀態的 [檢驗層級] 設定為DEBUG。下圖中的輸入/輸出處理選項卡顯示了針對此狀態提供的輸入Parameters上的應用程序的結果。
![通過測試的DEBUG級別輸出屏幕截圖。](images/test-state-debug-success.png)
下圖顯示當「檢驗層級」設定為時,「工作」狀態的測試失敗DEBUG。下圖中的輸入/輸出處理選項卡顯示了直到其故障點的狀態的輸入和輸出數據處理結果。
![失敗測試的DEBUG級別輸出屏幕截圖。](images/test-state-debug-failed.png)
TRACE inspectionLevel
Step Functions提供測試HTTP工作的TRACE層級。此層級會傳回第三方API傳回之HTTPStep Functions要求的相關資訊。回應可能包含資訊,例如標頭和要求主體。此外,您可以檢視此層級中輸入和輸出資料處理的狀態輸出和結果。
如果測試失敗,這個級別顯示錯誤輸出。
此層級僅適用於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級別輸出屏幕截圖。](images/test-state-trace-success.png)
IAM使用權限 TestState API
呼叫的IAM使用者TestState
API必須具有執行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請求和響應。
若要測試狀態
-
選擇 [建立狀態機] 以開始建立狀態機,或選擇現有的狀態機。
-
在工作流程工作室中,選擇您要測試設計模式的狀態。
-
在工作流程工作室的Inspector 面板面板中選擇測試狀態。
-
在「測試狀態」對話方塊中,執行下列操作:
-
對於執行角色,請選擇要測試狀態的執行角色。請確定您具有要測試之狀態的必要IAM權限。
-
(選擇性) 提供您選取的狀態需要進行測試的任何JSON輸入。
-
針對「檢驗層次」,根據您要檢視的值選取下列其中一個選項:
-
INFO— 如果測試成功,則在「輸出」索引標籤中顯示狀態輸出。如果測試失敗,會INFO顯示錯誤輸出,其中包括錯誤名稱和該錯誤原因的詳細說明。依預Step Functions設,如果未選取圖層,INFO則將「檢驗層級」設定為。
-
DEBUG— 如果測試成功,則顯示狀態輸出以及輸入和輸出資料處理的結果。如果測試失敗,會DEBUG顯示錯誤輸出,其中包括錯誤名稱和該錯誤原因的詳細說明。
-
TRACE— 顯示原始HTTP要求和回應,對於驗證標頭、查詢參數和其他API特定詳細資訊非常有用。此選項僅適用於「工HTTP作」。
或者,您可以選擇選取 [顯示密碼]。結合使用TRACE此設定可讓您查看EventBridge連線插入的敏感資料,例如API按鍵。您用來存取主控台的使用IAM者身分必須具有執行
states:RevealSecrets
動作的權限。如果沒有此權限,則會在您啟動測試時Step Functions擲回拒絕存取錯誤。如需設定states:RevealSecrets
權限的IAM原則範例,請參閱IAM使用權限 TestState API。
-
-
選擇 [開始測試]。
-
使用測試狀態 AWS CLI
您可以使用中的來測試支援TestStateAPI的狀態AWS CLI。這API接受狀態的定義並執行它。
對於每個狀態,您可以指定要在測試結果中檢視的詳細資訊量。這些詳細資料提供有關狀態執行的其他資訊,包括其輸入和輸出資料處理結果以及HTTP要求和回應資訊。以下範例展示了您可以為的指定的不同檢驗層級 TestState API。記得更換 italicized
包含資源特定資訊的文字。
本節包含下列範例,說明如何使用中Step Functions提供的不同檢驗層級AWS CLI:
範例 1:用INFO inspectionLevel 來測試選擇狀態
若要使用INFO
inspectionLevel中的測試狀態 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 inspectionLevel 來偵錯「通過」狀態下的輸入和輸出資料處理
若要使用DEBUG
inspectionLevel中的測試狀態 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
此範例使用「傳遞」工作流狀態來展示Step Functions篩選器如何使用輸入和輸出JSON資料處理篩選器來操作輸入資料。此範例使用下列篩選器:InputPath
參數
使用 ResultPath 「Step Functions」工作流程中指定狀態
、、和 OutputPath 在 Step Functions 工作流程中篩選狀態輸出
。
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
若要使用以TRACE
inspectionLevel及中的revealSecrets參數來測試 HTTPTask AWS 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 Task 是否呼叫指定的協力廠商APIhttps://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 「Step Functions」工作流程中指定狀態、和 OutputPath 在 Step Functions 工作流程中篩選狀態輸出。每個欄位的 Sup port 會因州
![篩選器的順序: InputPath、參數 ResultSelector ResultPath、、和 OutputPath。](images/input-output-processing.png)
下面的列表描述了圖中顯示的輸入和輸出處理字段的應用的順序。
-
State 輸入是從先前狀態傳JSON遞到當前狀態的數據。
-
InputPath過濾原始狀態輸入的一部分。
-
工作會執行工作並傳回結果。
-
ResultSelector從工作結果中選取一組要保留的值。
-
使用 ResultPath 「Step Functions」工作流程中指定狀態結果與原始狀態輸入結合,或用它替換結果。
-
OutputPath 在 Step Functions 工作流程中篩選狀態輸出篩選輸出的一部分,以傳遞至下一個狀態。
-
狀態輸出是從當前狀態傳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
物件中對應的欄位:
![顯示ASL字段的映射到的圖表inspectionData。](images/inspection-data-after-fields.png)
如需使用偵錯輸入和輸出處理的範例,請參閱下列內容: TestState API