分散式負載測試 API - AWS 上的分散式負載測試
GET /stack-infoGET /案例POST/情境選項/案例GET /scenarios/{testId}POST /scenarios/{testId}DELETE /scenarios/{testId}OPTIONS /scenarios/{testId}GET /scenarios/{testId}/testrunsGET /scenarios/{testId}/testruns/{testRunId}DELETE /scenarios/{testId}/testruns/{testRunId}GET /scenarios/{testId}/baselinePUT /scenarios/{testId}/baselineDELETE /scenarios/{testId}/baselineGET /任務選項/任務GET/區域選項/區域

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

分散式負載測試 API

此負載測試解決方案可協助您以安全的方式公開測試結果資料。API 做為「前門」，用於存取存放在 Amazon DynamoDB 中的測試資料。您也可以使用 APIs來存取您建置到解決方案中的任何延伸功能。

此解決方案使用與 Amazon API Gateway 整合的 Amazon Cognito 使用者集區來識別和授權。 Amazon API Gateway 當使用者集區與 API 搭配使用時，用戶端只能在提供有效的身分字符之後呼叫使用者集區啟用的方法。

如需直接透過 API 執行測試的詳細資訊，請參閱 Amazon API Gateway REST API 參考文件中的簽署請求。

下列操作可在解決方案的 API 中使用。

注意

如需 testScenario 和其他參數的詳細資訊，請參閱 GitHub 儲存庫中的案例和承載範例。

堆疊資訊

案例

測試執行

基準

工作

區域

GET /stack-info

說明

GET /stack-info 操作會擷取已部署堆疊的相關資訊，包括建立時間、區域和版本。前端會使用此端點。

回應

200 - 成功

名稱 描述

created_time

建立堆疊時的 ISO 8601 時間戳記 （例如 2025-09-09T19:40:22Z)

region

部署堆疊的 AWS 區域 （例如 us-east-1)

version

部署解決方案的版本 （例如 v4.0.0)

錯誤回應

  • 403 - 禁止：存取堆疊資訊的許可不足

  • 404 - 找不到：堆疊資訊無法使用

  • 500 - 內部伺服器錯誤

GET /案例

說明

GET /scenarios 操作可讓您擷取測試案例的清單。

回應

名稱 描述

data

案例清單，包括每個測試的 ID、名稱、描述、狀態、執行時間、標籤、總執行次數和上次執行次數

POST/情境

說明

POST /scenarios 操作可讓您建立或排程測試案例。

請求內文

名稱 描述

testName

測試的名稱

testDescription

測試的描述

testTaskConfigs

指定 concurrency（平行執行的數目）、 taskCount（執行測試所需的任務數目） 以及 案例region的物件

testScenario

測試定義，包括測試的並行、測試時間、主機和方法

testType

測試類型 （例如，simple、jmeter)

fileType

上傳檔案類型 （例如 、nonescript、zip)

tags

用於分類測試的字串陣列。長度上限為 5 的選用欄位 （例如 ["blue", "3.0", "critical"])

scheduleDate

執行測試的日期。僅在排程測試時提供 （例如，2021-02-28)

scheduleTime

執行測試的時間。僅在排程測試時提供 （例如，21:07)

scheduleStep

排程程序中的步驟。僅在排程週期性測試時提供。（可用的步驟包括 create和 start)

cronvalue

自訂週期性排程的 Cron 值。如果使用，請省略 scheduleDate 和 scheduleTime。

cronExpiryDate

必要日期，讓 Cron 過期且不會無限期執行。

recurrence

排程測試的週期。僅在排程重複測試時提供 （例如，、biweekly、 daily weekly或 monthly)

回應

名稱 描述

testId

測試的唯一 ID

testName

測試的名稱

status

測試的狀態

選項/案例

說明

OPTIONS /scenarios 操作為具有正確 CORS 回應標頭的請求提供回應。

回應

名稱 描述

testId

測試的唯一 ID

testName

測試的名稱

status

測試的狀態

GET /scenarios/{testId}

說明

GET /scenarios/{testId} 操作可讓您擷取特定測試案例的詳細資訊。

請求參數

testId

  • 測試的唯一 ID

    類型：字串

    必要：是

latest

  • 僅傳回最新測試執行的查詢參數。預設值為 true

    類型：布林值

    必要：否

history

  • 查詢參數以在回應中包含測試執行歷史記錄。預設值為 true。設定為 false以排除歷史記錄

    類型：布林值

    必要：否

回應

名稱 描述

testId

測試的唯一 ID

testName

測試的名稱

testDescription

測試的描述

testType

執行的測試類型 （例如，simple、jmeter)

fileType

上傳的檔案類型 （例如 none、script、zip)

tags

用於分類測試的字串陣列

status

測試的狀態

startTime

上次測試開始的時間和日期

endTime

上次測試結束的時間和日期

testScenario

測試定義，包括測試的並行、測試時間、主機和方法

taskCount

執行測試所需的任務數量

taskIds

執行測試的任務 IDs 清單

results

測試的最終結果

history

過去測試的最終結果清單 （當 時除外history=false)

totalRuns

此案例的測試執行總數

lastRun

上次測試執行的時間戳記

errorReason

發生錯誤時產生的錯誤訊息

nextRun

下一個排定的執行 （例如 2017-04-22 17:18:00)

scheduleRecurrence

測試的週期 （例如，、dailyweekly、biweekly、monthly)

POST /scenarios/{testId}

說明

POST /scenarios/{testId} 操作可讓您取消特定測試案例。

請求參數

testId

  • 測試的唯一 ID

    類型：字串

    必要：是

回應

名稱 描述

status

測試的狀態

DELETE /scenarios/{testId}

說明

DELETE /scenarios/{testId} 此操作可讓您刪除與特定測試案例相關的所有資料。

請求參數

testId

  • 測試的唯一 ID

    類型：字串

    必要：是

回應

名稱 描述

status

測試的狀態

OPTIONS /scenarios/{testId}

說明

OPTIONS /scenarios/{testId} 操作為具有正確 CORS 回應標頭的請求提供回應。

回應

名稱 描述

testId

測試的唯一 ID

testName

測試的名稱

testDescription

測試的描述

testType

執行的測試類型 （例如，simple、jmeter)

fileType

上傳的檔案類型 （例如 none、script、zip)

status

測試的狀態

startTime

上次測試開始的時間和日期

endTime

上次測試結束的時間和日期

testScenario

測試定義，包括測試的並行、測試時間、主機和方法

taskCount

執行測試所需的任務數量

taskIds

執行測試的任務 IDs 清單

results

測試的最終結果

history

過去測試的最終結果清單

errorReason

發生錯誤時產生的錯誤訊息

GET /scenarios/{testId}/testruns

說明

GET /scenarios/{testId}/testruns 操作會擷取特定測試案例的測試執行 IDs，選擇性地依時間範圍篩選。當 時latest=true， 只會傳回最新的單一測試執行。

請求參數

testId

  • 測試案例 ID

    類型：字串

    必要：是

latest

  • 僅傳回最新的測試執行 ID

    類型：布林值

    預設：false

    必要：否

start_timestamp

  • ISO 8601 時間戳記，用於篩選從 （包含） 執行的測試。例如 2024-01-01T00:00:00Z

    類型：字串 （日期時間格式）

    必要：否

end_timestamp

  • 篩選測試執行的 ISO 8601 時間戳記，直到 （包含）。例如 2024-12-31T23:59:59Z

    類型：字串 （日期時間格式）

    必要：否

limit

  • 要傳回的測試執行數目上限 （當 時忽略latest=true)

    類型：整數 （最小值：1，最大值：100)

    預設：20

    必要：否

next_token

  • 上一個回應的分頁字符以取得下一頁

    類型：字串

    必要：否

回應

200 - 成功

名稱 描述

testRuns

測試執行物件陣列，每個都包含 testRunId（字串） 和 startTime(ISO 8601 日期時間）

pagination

物件包含 limit（整數） 和 next_token（字串或 null)。如果沒有更多結果，字符為 null

錯誤回應

  • 400 - 無效的時間戳記格式或參數

  • 404 - 找不到測試案例

  • 500 - 內部伺服器錯誤

範例使用方式

  • 僅限最新測試執行： GET /scenarios/test123/testruns?latest=true

  • 時間範圍內的最新時間： GET /scenarios/test123/testruns?latest=true&start_timestamp=2024-01-01T00:00:00Z

  • 下一頁請求： GET /scenarios/test123/testruns?limit=20&next_token=eyJ0ZXN0SWQiOiJzZVFVeTEyTEtMIiwic3RhcnRUaW1lIjoiMjAyNC0wMS0xM1QxNjo0NTowMFoifQ==

GET /scenarios/{testId}/testruns/{testRunId}

說明

GET /scenarios/{testId}/testruns/{testRunId} 操作會擷取特定測試執行的完整結果和指標。選擇性地使用 省略歷史記錄結果history=false，以加快回應速度。

請求參數

testId

  • 測試案例 ID

    類型：字串

    必要：是

testRunId

  • 特定的測試執行 ID

    類型：字串

    必要：是

history

  • 在回應中包含歷史記錄陣列。設定為 false可省略歷史記錄以加快回應速度

    類型：布林值

    預設：true

    必要：否

回應

200 - 成功

名稱 描述

testId

測試的唯一 ID （例如 seQUy12LKL)

testRunId

特定的測試執行 ID （例如 2DEwHItEne)

testDescription

負載測試的描述

testType

測試類型 （例如，simple、jmeter)

status

測試執行的狀態：complete、failed、 running或 cancelled

startTime

測試開始的時間和日期 （例如 2025-09-09 21:01:00)

endTime

測試結束的時間和日期 （例如 2025-09-09 21:18:29)

succPercent

成功百分比 （例如 100.00)

testTaskConfigs

包含 region、 taskCount和 的任務組態物件陣列 concurrency

completeTasks

物件映射區域到已完成的任務計數

results

包含詳細指標的物件，包括 avg_lt（平均延遲）、百分位數 (p0_0、p50_0、p90_0p95_0、、p99_9、p100_0、)p99_0、 avg_rt （平均回應時間）、 avg_ct （平均連線時間）、 stdev_rt （標準差回應時間）concurrency、、throughput、 succ（成功計數）、 fail （失敗計數）bytes、、testDuration、metricS3Location、 rc（回應代碼陣列） 和 labels陣列

testScenario

物件包含具有 execution、 reporting和 scenarios 屬性的測試組態

history

歷史測試結果陣列 （當 時排除history=false)

錯誤回應

  • 400 - 無效的 testId 或 testRunId

  • 404 - 找不到測試執行

  • 500 - 內部伺服器錯誤

DELETE /scenarios/{testId}/testruns/{testRunId}

說明

DELETE /scenarios/{testId}/testruns/{testRunId} 操作會刪除與特定測試執行相關的所有資料和成品。測試執行資料會從 DynamoDB 中移除，而 S3 中的實際測試資料保持不變。

請求參數

testId

  • 測試案例 ID

    類型：字串

    必要：是

testRunId

  • 要刪除的特定測試執行 ID

    類型：字串

    必要：是

回應

204 - 成功

測試執行已成功刪除 （未傳回內容）

錯誤回應

  • 400 - 無效的 testId 或 testRunId

  • 403 - 禁止：刪除測試執行的許可不足

  • 404 - 找不到測試執行

  • 409 - 衝突：測試執行目前正在執行，無法刪除

  • 500 - 內部伺服器錯誤

GET /scenarios/{testId}/baseline

說明

GET /scenarios/{testId}/baseline 操作會擷取案例的指定基準測試結果。根據 data 參數傳回基準測試執行 ID 或完整基準結果。

請求參數

testId

  • 測試案例 ID

    類型：字串

    必要：是

data

  • 如果 傳回完整的基準測試執行資料true，否則僅傳回 testRunId

    類型：布林值

    預設：false

    必要：否

回應

200 - 成功

時間 data=false（預設）：

名稱 描述

testId

測試案例 ID （例如 seQUy12LKL)

baselineTestRunId

基準測試執行 ID （例如 2DEwHItEne)

當 data=true時：

名稱 描述

testId

測試案例 ID （例如 seQUy12LKL)

baselineTestRunId

基準測試執行 ID （例如 2DEwHItEne)

baselineData

完成測試執行結果物件 （與 的結構相同GET /scenarios/{testId}/testruns/{testRunId})

錯誤回應

  • 400 - 無效的 testId 參數

  • 404 - 找不到測試案例或未設定基準

  • 500 - 內部伺服器錯誤

PUT /scenarios/{testId}/baseline

說明

PUT /scenarios/{testId}/baseline 操作會指定特定測試執行做為效能比較的基準。每個案例只能設定一個基準。

請求參數

testId

  • 測試案例 ID

    類型：字串

    必要：是

請求內文

名稱 描述

testRunId

要設定為基準的測試執行 ID （例如，2DEwHItEne)

回應

200 - 成功

名稱 描述

message

確認訊息 （例如 Baseline set successfully)

testId

測試案例 ID （例如 seQUy12LKL)

baselineTestRunId

設定的基準測試執行 ID （例如 2DEwHItEne)

錯誤回應

  • 400 - 無效的 testId 或 testRunId

  • 404 - 找不到測試案例或測試執行

  • 409 - 衝突：測試執行無法設定為基準 （例如，測試失敗）

  • 500 - 內部伺服器錯誤

DELETE /scenarios/{testId}/baseline

說明

DELETE /scenarios/{testId}/baseline 操作會將其設定為空字串，以清除案例的基準值。

請求參數

testId

  • 測試案例 ID

    類型：字串

    必要：是

回應

204 - 成功

基準已成功清除 （未傳回內容）

錯誤回應

  • 400 - 無效的 testId

  • 500 - 內部伺服器錯誤

GET /任務

說明

GET /tasks 此操作可讓您擷取執行中 Amazon Elastic Container Service (Amazon ECS) 任務的清單。

回應

名稱 描述

tasks

執行測試的任務 IDs 清單

選項/任務

說明

OPTIONS /tasks 任務操作為具有正確 CORS 回應標頭的請求提供回應。

回應

名稱 描述

taskIds

執行測試的任務 IDs 清單

GET/區域

說明

GET /regions 操作可讓您擷取在該區域中執行測試所需的區域資源資訊。

回應

名稱 描述

testId

區域 ID

ecsCloudWatchLogGroup

區域中 Amazon Fargate 任務的 Amazon CloudWatch 日誌群組名稱

region

資料表中資源存在的區域

subnetA

區域中其中一個子網路的 ID

subnetB

區域中其中一個子網路的 ID

taskCluster

區域中 AWS Fargate 叢集的名稱

taskDefinition

區域中任務定義的 ARN

taskImage

區域中任務映像的名稱

taskSecurityGroup

區域中安全群組的 ID

選項/區域

說明

OPTIONS /regions 操作為具有正確 CORS 回應標頭的請求提供回應。

回應

名稱 描述

testId

區域 ID

ecsCloudWatchLogGroup

區域中 Amazon Fargate 任務的 Amazon CloudWatch 日誌群組名稱

region

資料表中資源存在的區域

subnetA

區域中其中一個子網路的 ID

subnetB

區域中其中一個子網路的 ID

taskCluster

區域中 AWS Fargate 叢集的名稱

taskDefinition

區域中任務定義的 ARN

taskImage

區域中任務映像的名稱

taskSecurityGroup

區域中安全群組的 ID