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

# 分散式負載測試 API
<a name="distributed-load-testing-api"></a>

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

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

如需直接透過 API 執行測試的詳細資訊，請參閱 Amazon API Gateway REST API 參考文件中的[簽署請求](https://docs.aws.amazon.com/apigateway/api-reference/signing-requests/)。

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

**注意**  
如需 `testScenario` 和其他參數的詳細資訊，請參閱 GitHub 儲存庫中的[案例](https://github.com/aws-solutions/distributed-load-testing-on-aws/blob/main/source/api-services/lib/scenarios/index.js#L267)和[承載範例](https://github.com/aws-solutions/distributed-load-testing-on-aws/blob/main/source/webui/src/pages/scenarios/CreateTestScenarioPage.tsx#L281-L388)。

 **堆疊資訊** 
+  [GET /stack-info](#get-stack-info) 

 **案例** 
+  [GET /案例](#get-scenarios) 
+  [POST/案例](#post-scenarios) 
+  [OPTIONS/案例](#options-scenarios) 
+  [GET /scenarios/\$1testId\$1](#get-scenarios-testid) 
+  [POST /scenarios/\$1testId\$1](#post-scenarios-testid) 
+  [DELETE /scenarios/\$1testId\$1](#delete-scenarios-testid) 
+  [OPTIONS /scenarios/\$1testId\$1](#options-scenarios-testid) 

 **測試執行** 
+  [GET /scenarios/\$1testId\$1/testruns](#get-scenarios-testid-testruns) 
+  [GET /scenarios/\$1testId\$1/testruns/\$1testRunId\$1](#get-scenarios-testid-testruns-testrunid) 
+  [DELETE /scenarios/\$1testId\$1/testruns/\$1testRunId\$1](#delete-scenarios-testid-testruns-testrunid) 

 **基準** 
+  [GET /scenarios/\$1testId\$1/baseline](#get-scenarios-testid-baseline) 
+  [PUT /scenarios/\$1testId\$1/baseline](#put-scenarios-testid-baseline) 
+  [DELETE /scenarios/\$1testId\$1/baseline](#delete-scenarios-testid-baseline) 

 **工作** 
+  [GET /任務](#get-tasks) 
+  [選項/任務](#options-tasks) 

 **區域** 
+  [GET/區域](#get-regions) 
+  [選項/區域](#options-regions) 

## GET /stack-info
<a name="get-stack-info"></a>

### Description
<a name="get-stack-info-description"></a>

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

### 回應
<a name="get-stack-info-response"></a>

 **200 - 成功** 


| 名稱 | 描述 | 
| --- | --- | 
|   `created_time`   |  建立堆疊時的 ISO 8601 時間戳記 （例如 `2025-09-09T19:40:22Z`)  | 
|   `region`   |  部署堆疊的 AWS 區域 （例如 `us-east-1`)  | 
|   `version`   |  部署解決方案的版本 （例如 `v4.0.0`)  | 

 **錯誤回應** 
+  `403` - 禁止：存取堆疊資訊的許可不足
+  `404` - 找不到：堆疊資訊無法使用
+  `500` - 內部伺服器錯誤

## GET/案例
<a name="get-scenarios"></a>

### Description
<a name="get-scenarios-description"></a>

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

### 回應
<a name="get-scenarios-response"></a>


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

## POST/案例
<a name="post-scenarios"></a>

### Description
<a name="post-scenarios-description"></a>

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

### 請求內文
<a name="post-scenarios-request"></a>


| 名稱 | 描述 | 
| --- | --- | 
|   `testName`   |  測試的名稱  | 
|   `testDescription`   |  測試的描述  | 
|   `testTaskConfigs`   |  指定 `concurrency`（平行執行的數目）、 `taskCount`（執行測試所需的任務數目） 以及 案例`region`的物件  | 
|   `testScenario`   |  測試定義，包括測試的並行、測試時間、主機和方法  | 
|   `testType`   |  測試類型 （例如，`simple`、`jmeter`)  | 
|   `fileType`   |  上傳檔案類型 （例如 、`none``script`、`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`)  | 

### 回應
<a name="post-scenarios-response"></a>


| 名稱 | 描述 | 
| --- | --- | 
|   `testId`   |  測試的唯一 ID  | 
|   `testName`   |  測試的名稱  | 
|   `status`   |  測試的狀態  | 

## OPTIONS/案例
<a name="options-scenarios"></a>

### Description
<a name="options-scenarios-description"></a>

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

### 回應
<a name="options-scenarios-response"></a>


| 名稱 | 描述 | 
| --- | --- | 
|   `testId`   |  測試的唯一 ID  | 
|   `testName`   |  測試的名稱  | 
|   `status`   |  測試的狀態  | 

## GET /scenarios/\$1testId\$1
<a name="get-scenarios-testid"></a>

### Description
<a name="get-scenarios-testid-description"></a>

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

### 請求參數
<a name="get-scenarios-testid-request"></a>

 `testId`   
+ 測試的唯一 ID

  類型：字串

  必要：是

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

  類型：布林值

  必要：否

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

  類型：布林值

  必要：否

### 回應
<a name="get-scenarios-testid-response"></a>


| 名稱 | 描述 | 
| --- | --- | 
|   `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`   |  測試的週期 （例如`daily`，、`weekly`、`biweekly`、`monthly`)  | 

## POST /scenarios/\$1testId\$1
<a name="post-scenarios-testid"></a>

### Description
<a name="post-scenarios-testid-description"></a>

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

### 請求參數
<a name="post-scenarios-testid-request"></a>

 `testId`   
+ 測試的唯一 ID

  類型：字串

  必要：是

### 回應
<a name="post-scenarios-testid-response"></a>


| 名稱 | 描述 | 
| --- | --- | 
|   `status`   |  測試的狀態  | 

## DELETE /scenarios/\$1testId\$1
<a name="delete-scenarios-testid"></a>

### Description
<a name="delete-scenarios-testid-description"></a>

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

### 請求參數
<a name="delete-scenarios-testid-request"></a>

 `testId`   
+ 測試的唯一 ID

  類型：字串

  必要：是

### 回應
<a name="delete-scenarios-testid-response"></a>


| 名稱 | 描述 | 
| --- | --- | 
|   `status`   |  測試的狀態  | 

## OPTIONS /scenarios/\$1testId\$1
<a name="options-scenarios-testid"></a>

### Description
<a name="options-scenarios-testid-description"></a>

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

### 回應
<a name="options-scenarios-testid-response"></a>


| 名稱 | 描述 | 
| --- | --- | 
|   `testId`   |  測試的唯一 ID  | 
|   `testName`   |  測試的名稱  | 
|   `testDescription`   |  測試的描述  | 
|   `testType`   |  執行的測試類型 （例如 `simple`、`jmeter`)  | 
|   `fileType`   |  上傳的檔案類型 （例如 `none`、`script`、`zip`)  | 
|   `status`   |  測試的狀態  | 
|   `startTime`   |  上次測試開始的時間和日期  | 
|   `endTime`   |  上次測試結束的時間和日期  | 
|   `testScenario`   |  測試定義，包括測試的並行、測試時間、主機和方法  | 
|   `taskCount`   |  執行測試所需的任務數量  | 
|   `taskIds`   |  執行測試的任務 IDs 清單  | 
|   `results`   |  測試的最終結果  | 
|   `history`   |  過去測試的最終結果清單  | 
|   `errorReason`   |  發生錯誤時產生的錯誤訊息  | 

## GET /scenarios/\$1testId\$1/testruns
<a name="get-scenarios-testid-testruns"></a>

### Description
<a name="get-scenarios-testid-testruns-description"></a>

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

### 請求參數
<a name="get-scenarios-testid-testruns-request"></a>

 `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`   
+ 上一個回應的分頁字符以取得下一頁

  類型：字串

  必要：否

### 回應
<a name="get-scenarios-testid-testruns-response"></a>

 **200 - 成功** 


| 名稱 | 描述 | 
| --- | --- | 
|   `testRuns`   |  測試執行物件陣列，每個都包含 `testRunId`（字串） 和 `startTime`(ISO 8601 日期時間）  | 
|   `pagination`   |  物件包含 `limit`（整數） 和 `next_token`（字串或 null)。如果沒有更多結果，字符為 null  | 

 **錯誤回應** 
+  `400` - 無效的時間戳記格式或參數
+  `404` - 找不到測試案例
+  `500` - 內部伺服器錯誤

### 範例使用方式
<a name="get-scenarios-testid-testruns-examples"></a>
+ 僅限最新測試執行： `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/\$1testId\$1/testruns/\$1testRunId\$1
<a name="get-scenarios-testid-testruns-testrunid"></a>

### Description
<a name="get-scenarios-testid-testruns-testrunid-description"></a>

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

### 請求參數
<a name="get-scenarios-testid-testruns-testrunid-request"></a>

 `testId`   
+ 測試案例 ID

  類型：字串

  必要：是

 `testRunId`   
+ 特定的測試執行 ID

  類型：字串

  必要：是

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

  類型：布林值

  預設：`true`

  必要：否

### 回應
<a name="get-scenarios-testid-testruns-testrunid-response"></a>

 **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_0``p95_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/\$1testId\$1/testruns/\$1testRunId\$1
<a name="delete-scenarios-testid-testruns-testrunid"></a>

### Description
<a name="delete-scenarios-testid-testruns-testrunid-description"></a>

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

### 請求參數
<a name="delete-scenarios-testid-testruns-testrunid-request"></a>

 `testId`   
+ 測試案例 ID

  類型：字串

  必要：是

 `testRunId`   
+ 要刪除的特定測試執行 ID

  類型：字串

  必要：是

### 回應
<a name="delete-scenarios-testid-testruns-testrunid-response"></a>

 **204 - 成功** 

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

 **錯誤回應** 
+  `400` - 無效的 testId 或 testRunId
+  `403` - 禁止：刪除測試執行的許可不足
+  `404` - 找不到測試執行
+  `409` - 衝突：測試執行目前正在執行，無法刪除
+  `500` - 內部伺服器錯誤

## GET /scenarios/\$1testId\$1/baseline
<a name="get-scenarios-testid-baseline"></a>

### Description
<a name="get-scenarios-testid-baseline-description"></a>

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

### 請求參數
<a name="get-scenarios-testid-baseline-request"></a>

 `testId`   
+ 測試案例 ID

  類型：字串

  必要：是

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

  類型：布林值

  預設：`false`

  必要：否

### 回應
<a name="get-scenarios-testid-baseline-response"></a>

 **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/\$1testId\$1/baseline
<a name="put-scenarios-testid-baseline"></a>

### Description
<a name="put-scenarios-testid-baseline-description"></a>

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

### 請求參數
<a name="put-scenarios-testid-baseline-request"></a>

 `testId`   
+ 測試案例 ID

  類型：字串

  必要：是

### 請求內文
<a name="put-scenarios-testid-baseline-request-body"></a>


| 名稱 | 描述 | 
| --- | --- | 
|   `testRunId`   |  要設定為基準的測試執行 ID （例如，`2DEwHItEne`)  | 

### 回應
<a name="put-scenarios-testid-baseline-response"></a>

 **200 - 成功** 


| 名稱 | 描述 | 
| --- | --- | 
|   `message`   |  確認訊息 （例如 `Baseline set successfully`)  | 
|   `testId`   |  測試案例 ID （例如 `seQUy12LKL`)  | 
|   `baselineTestRunId`   |  設定的基準測試執行 ID （例如 `2DEwHItEne`)  | 

 **錯誤回應** 
+  `400` - 無效的 testId 或 testRunId
+  `404` - 找不到測試案例或測試執行
+  `409` - 衝突：測試執行無法設定為基準 （例如，測試失敗）
+  `500` - 內部伺服器錯誤

## DELETE /scenarios/\$1testId\$1/baseline
<a name="delete-scenarios-testid-baseline"></a>

### Description
<a name="delete-scenarios-testid-baseline-description"></a>

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

### 請求參數
<a name="delete-scenarios-testid-baseline-request"></a>

 `testId`   
+ 測試案例 ID

  類型：字串

  必要：是

### 回應
<a name="delete-scenarios-testid-baseline-response"></a>

 **204 - 成功** 

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

 **錯誤回應** 
+  `400` - 無效的 testId
+  `500` - 內部伺服器錯誤

## GET /任務
<a name="get-tasks"></a>

### Description
<a name="get-tasks-description"></a>

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

### 回應
<a name="get-tasks-response"></a>


| 名稱 | 描述 | 
| --- | --- | 
|   `tasks`   |  執行測試的任務 IDs 清單  | 

## 選項/任務
<a name="options-tasks"></a>

### Description
<a name="options-tasks-description"></a>

`OPTIONS /tasks` 任務操作會使用正確的 CORS 回應標頭為請求提供回應。

### 回應
<a name="options-tasks-response"></a>


| 名稱 | 描述 | 
| --- | --- | 
|   `taskIds`   |  執行測試的任務 IDs 清單  | 

## GET/區域
<a name="get-regions"></a>

### Description
<a name="get-regions-description"></a>

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

### 回應
<a name="get-regions-response"></a>


| 名稱 | 描述 | 
| --- | --- | 
|   `testId`   |  區域 ID  | 
|   `ecsCloudWatchLogGroup`   |  區域中 Amazon Fargate 任務的 Amazon CloudWatch 日誌群組名稱  | 
|   `region`   |  資料表中資源存在的區域  | 
|   `subnetA`   |  區域中其中一個子網路的 ID  | 
|   `subnetB`   |  區域中其中一個子網路的 ID  | 
|   `taskCluster`   |  區域中 AWS Fargate 叢集的名稱  | 
|   `taskDefinition`   |  區域中任務定義的 ARN  | 
|   `taskImage`   |  區域中任務映像的名稱  | 
|   `taskSecurityGroup`   |  區域中安全群組的 ID  | 

## 選項/區域
<a name="options-regions"></a>

### Description
<a name="options-regions-description"></a>

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

### 回應
<a name="options-regions-response"></a>


| 名稱 | 描述 | 
| --- | --- | 
|   `testId`   |  區域 ID  | 
|   `ecsCloudWatchLogGroup`   |  區域中 Amazon Fargate 任務的 Amazon CloudWatch 日誌群組名稱  | 
|   `region`   |  資料表中資源存在的區域  | 
|   `subnetA`   |  區域中其中一個子網路的 ID  | 
|   `subnetB`   |  區域中其中一個子網路的 ID  | 
|   `taskCluster`   |  區域中 AWS Fargate 叢集的名稱  | 
|   `taskDefinition`   |  區域中任務定義的 ARN  | 
|   `taskImage`   |  區域中任務映像的名稱  | 
|   `taskSecurityGroup`   |  區域中安全群組的 ID  |