Menggunakan TestState API untuk menguji status di Step Functions

The TestStateAPImenerima definisi dari satu negara dan mengeksekusinya. Anda dapat menguji status tanpa membuat mesin status atau memperbarui mesin status yang ada.

Dengan menggunakan TestState API, Anda dapat menguji yang berikut:

Untuk menguji status, Anda juga dapat menggunakan Step Functions konsol, AWS Command Line Interface (AWS CLI), atauSDK.

TestStateAPIMengasumsikan IAM peran yang harus mengandung yang diperlukan IAM izin untuk sumber daya yang diakses negara Anda. Untuk informasi tentang izin yang mungkin diperlukan oleh negara bagian, lihatIAM izin untuk menggunakan TestState API.

Pertimbangan tentang menggunakan TestState API

Dengan menggunakan TestStateAPI, Anda hanya dapat menguji satu status pada satu waktu. Status yang dapat Anda uji meliputi yang berikut:

Saat menggunakan TestStateAPI, perlu diingat pertimbangan berikut.

Menggunakan tingkat inspeksi di TestState API

Untuk menguji status menggunakan TestStateAPI, Anda memberikan definisi status itu. Tes kemudian mengembalikan output. Untuk setiap status, Anda dapat menentukan jumlah detail yang ingin Anda lihat dalam hasil tes. Detail ini memberikan informasi tambahan tentang status yang Anda uji. Misalnya, jika Anda telah menggunakan filter pemrosesan data input dan output, seperti InputPathatau ResultPathdalam keadaan, Anda dapat melihat hasil pemrosesan data antara dan akhir.

Step Functions menyediakan level berikut untuk menentukan detail yang ingin Anda lihat:

Semua level ini juga mengembalikan status dan nextState bidang. statusmenunjukkan status eksekusi negara. Misalnya,SUCCEEDED, FAILEDRETRIABLE, danCAUGHT_ERROR. nextStatemenunjukkan nama negara bagian berikutnya untuk transisi ke. Jika Anda belum menentukan status berikutnya dalam definisi Anda, bidang ini mengembalikan nilai kosong.

Untuk informasi tentang pengujian keadaan menggunakan tingkat inspeksi ini di Step Functions konsol dan AWS CLI, lihat Menguji status (Konsol) danMenguji status menggunakan AWS CLI.

INFO inspectionLevel

Jika tes berhasil, level ini menunjukkan output status. Jika tes gagal, level ini menunjukkan output kesalahan. Secara default, Step Functions menetapkan tingkat Inspeksi INFOjika Anda tidak menentukan level.

Gambar berikut menunjukkan tes untuk status Lulus yang berhasil. Tingkat Inspeksi untuk status ini diatur ke INFOdan output untuk status muncul di tab Output.

Gambar berikut menunjukkan pengujian yang gagal untuk status Tugas saat tingkat Inspeksi disetel ke INFO. Tab Output menunjukkan output kesalahan yang mencakup nama kesalahan dan penjelasan rinci tentang penyebab kesalahan itu.

DEBUG inspectionLevel

Jika tes berhasil, level ini menunjukkan output status dan hasil pemrosesan data input dan output.

Jika tes gagal, level ini menunjukkan output kesalahan. Tingkat ini menunjukkan hasil pemrosesan data menengah hingga titik kegagalan. Misalnya, katakan bahwa Anda menguji status Tugas yang memanggil Lambda fungsi. Bayangkan Anda telah menerapkanInputPath,Parameter,Menentukan output status menggunakan alur kerja ResultPath Step Functions, dan Memfilter output status menggunakan alur kerja OutputPath Step Functions filter ke status Tugas. Katakan bahwa doa gagal. Dalam hal ini, DEBUG level menunjukkan hasil pemrosesan data berdasarkan penerapan filter dalam urutan sebagai berikut:

Informasi diagnostik yang tersedia di level ini dapat membantu Anda memecahkan masalah yang terkait dengan integrasi layanan atau aliran pemrosesan data input dan output yang mungkin telah Anda tentukan.

Gambar berikut menunjukkan tes untuk status Lulus yang berhasil. Tingkat Inspeksi untuk status ini diatur ke DEBUG. Tab pemrosesan input/output pada gambar berikut menunjukkan hasil penerapan Parameterspada input yang disediakan untuk keadaan ini.

Gambar berikut menunjukkan pengujian yang gagal untuk status Tugas saat tingkat Inspeksi disetel ke DEBUG. Tab pemrosesan input/output pada gambar berikut menunjukkan hasil pemrosesan data input dan output untuk status hingga titik kegagalannya.

TRACE inspectionLevel

Step Functions menyediakan TRACEtingkat untuk menguji HTTPTugas. Tingkat ini mengembalikan informasi tentang HTTP permintaan yang Step Functions membuat dan menanggapi bahwa pihak ketiga API kembali. Respons mungkin berisi informasi, seperti header dan badan permintaan. Selain itu, Anda dapat melihat output status dan hasil pemrosesan data input dan output di level ini.

Jika tes gagal, level ini menunjukkan output kesalahan.

Level ini hanya berlaku untuk HTTP Tugas. Step Functions melempar kesalahan jika Anda menggunakan level ini untuk tipe status lainnya.

Saat Anda mengatur level Inspeksi TRACE, Anda juga dapat melihat rahasia yang disertakan dalam EventBridge koneksi. Untuk melakukan ini, Anda harus mengatur revealSecrets parameter ke true dalam TestStateAPI. Selain itu, Anda harus memastikan bahwa IAM pengguna yang memanggil TestState API memiliki izin untuk states:RevealSecrets tindakan tersebut. Sebagai contoh dari IAM kebijakan yang menetapkan states:RevealSecrets izin, lihatIAM izin untuk menggunakan TestState API. Tanpa izin ini, Step Functions melempar kesalahan akses ditolak.

Jika Anda mengatur revealSecrets parameter kefalse, Step Functions menghilangkan semua rahasia dalam data HTTP permintaan dan respons.

Gambar berikut menunjukkan tes untuk HTTP Tugas yang berhasil. Tingkat Inspeksi untuk status ini diatur ke TRACE. Tab HTTPpermintaan & respons pada gambar berikut menunjukkan hasil API panggilan pihak ketiga.

IAM izin untuk menggunakan TestState API

Bagian IAM pengguna yang memanggil TestState API harus memiliki izin untuk melakukan states:TestState dan iam:PassRole tindakan. Selain itu, jika Anda mengatur revealSecretsparameter ketrue, Anda harus memastikan bahwa IAM pengguna memiliki izin untuk melakukan states:RevealSecrets tindakan. Tanpa izin ini, Step Functions melempar kesalahan akses ditolak.

Anda juga harus memastikan bahwa peran eksekusi Anda berisi yang diperlukan IAM izin untuk sumber daya yang diakses negara Anda. Untuk informasi tentang izin yang mungkin diperlukan oleh negara bagian, lihat Mengelola peran eksekusi.

Berikut ini IAM contoh kebijakan menetapkan states:RevealSecrets izin states:TestStateiam:PassRole,, dan.

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

Menguji status (Konsol)

Anda dapat menguji status di konsol dan memeriksa output status atau aliran pemrosesan data input dan output. Untuk HTTPTugas, Anda dapat menguji HTTP permintaan dan respons mentah.

Menguji status menggunakan AWS CLI

Anda dapat menguji status yang didukung menggunakan TestStateAPIdi AWS CLI. Ini API menerima definisi negara dan mengeksekusinya.

Untuk setiap status, Anda dapat menentukan jumlah detail yang ingin Anda lihat dalam hasil tes. Rincian ini memberikan informasi tambahan tentang eksekusi negara, termasuk hasil pemrosesan data input dan output serta informasi HTTP permintaan dan respons. Contoh berikut menampilkan berbagai tingkat inspeksi yang dapat Anda tentukan untuk. TestState API Ingatlah untuk mengganti italicized teks dengan informasi spesifik sumber daya Anda.

Bagian ini berisi contoh-contoh berikut yang menjelaskan bagaimana Anda dapat menggunakan tingkat inspeksi yang berbeda Step Functions menyediakan di AWS CLI:

Contoh 1: Menggunakan INFO inspectionLevel untuk menguji status Pilihan

Untuk menguji status menggunakan INFO inspectionLevelin AWS CLI, jalankan test-state perintah seperti yang ditunjukkan pada contoh berikut.

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}'

Contoh ini menggunakan status Pilihan untuk menentukan jalur eksekusi untuk status berdasarkan input numerik yang Anda berikan. Secara default, Step Functions menetapkan inspectionLevel ke INFO jika Anda tidak menetapkan level.

Step Functions mengembalikan output berikut.

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

Contoh 2: Menggunakan DEBUG inspectionLevel untuk men-debug pemrosesan data input dan output dalam status Pass

Untuk menguji status menggunakan DEBUG inspectionLevelin AWS CLI, jalankan test-state perintah seperti yang ditunjukkan pada contoh berikut.

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

Contoh ini menggunakan Lulus status alur kerja status untuk menampilkan caranya Step Functions menyaring dan memanipulasi JSON data input menggunakan filter pemrosesan data input dan output. Contoh ini menggunakan filter ini:InputPath,Parameter,Menentukan output status menggunakan alur kerja ResultPath Step Functions, danMemfilter output status menggunakan alur kerja OutputPath Step Functions.

Step Functions mengembalikan output berikut.

{
    "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"
}

Contoh 3: Menggunakan TRACE inspectionLevel dan revealSecrets memeriksa HTTP permintaan yang dikirim ke pihak ketiga API

Untuk menguji HTTPTugas menggunakan TRACE inspectionLevelbersama dengan revealSecretsparameter di AWS CLI, jalankan test-state perintah seperti yang ditunjukkan pada contoh berikut.

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

Contoh ini menguji apakah HTTP Tugas memanggil pihak ketiga yang ditentukanAPI,https://httpbin.org/. Ini juga menunjukkan data HTTP permintaan dan respons untuk API panggilan tersebut.

{
    "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"
}

Contoh 4: Menggunakan utilitas jq untuk memfilter dan mencetak respons yang kembali TestState API

TestState APIMengembalikan JSON data sebagai string yang lolos dalam responsnya. Berikut ini AWS CLI contoh memperluas Contoh 3 dan menggunakan jq utilitas untuk memfilter dan mencetak HTTP respons yang TestState API dikembalikan dalam format yang dapat dibaca manusia. Untuk informasi tentang jq dan petunjuk pemasangannya, lihat 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'

Contoh berikut menunjukkan output yang dikembalikan dalam format yang dapat dibaca manusia.

{
  "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"
}

Menguji dan men-debug aliran data input dan output

TestStateAPIIni sangat membantu untuk menguji dan men-debug data yang mengalir melalui alur kerja Anda. Bagian ini memberikan beberapa konsep kunci dan menjelaskan cara menggunakan TestState untuk tujuan ini.

Konsep utama

Masuk Step Functions, proses penyaringan dan manipulasi JSON data saat melewati status di mesin negara Anda disebut pemrosesan input dan output. Untuk informasi tentang cara kerjanya, lihatMemproses input dan output di Step Functions.

Semua jenis status di Amazon States Language (ASL) (Tugas, Paralel, Peta, Lulus, Tunggu, Pilihan, Sukses, dan Gagal) berbagi satu set bidang umum untuk memfilter dan memanipulasi JSON data yang melewati mereka. Bidang-bidang ini adalah: InputPathParameter,ResultSelector,,Menentukan output status menggunakan alur kerja ResultPath Step Functions, danMemfilter output status menggunakan alur kerja OutputPath Step Functions. Support untuk setiap bidang bervariasi di seluruh negara bagian. Saat runtime, Step Functions menerapkan setiap bidang dalam urutan tertentu. Diagram berikut menunjukkan urutan di mana bidang ini diterapkan ke data di dalam status Tugas:

Daftar berikut menjelaskan urutan penerapan bidang pemrosesan input dan output yang ditunjukkan pada diagram.

Bidang pemrosesan input dan output ini bersifat opsional. Jika Anda tidak menggunakan salah satu bidang ini dalam definisi status Anda, tugas akan menggunakan input status mentah, dan mengembalikan hasil tugas sebagai output status.

Menggunakan TestState untuk memeriksa pemrosesan input dan output

Ketika Anda memanggil TestState API dan mengatur inspectionLevel parameter keDEBUG, API respon termasuk objek yang dipanggilinspectionData. Objek ini berisi bidang untuk membantu Anda memeriksa bagaimana data disaring atau dimanipulasi dalam status saat dijalankan. Contoh berikut menunjukkan inspectionData objek untuk status Tugas.

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

Dalam contoh ini, setiap bidang yang berisi after awalan, menunjukkan data setelah bidang tertentu diterapkan. Misalnya, afterInputPath menunjukkan efek penerapan InputPath bidang untuk memfilter input status mentah. Diagram berikut memetakan setiap bidang ASLdefinisi ke bidang yang sesuai dalam inspectionData objek:

Untuk contoh penggunaan TestState API untuk men-debug input dan output processing, lihat berikut ini: