本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

# 分布式负载测试 API
<a name="distributed-load-testing-api"></a>

此负载测试解决方案可帮助您以安全的方式公开测试结果数据。该 API 充当访问存储在 Amazon DynamoDB 中的测试数据的 “前门”。您还可以使用 APIs 访问您在解决方案中内置的任何扩展功能。

该解决方案使用与 Amazon API Gateway 集成的 Amazon Cognito 用户池进行识别和授权。当用户池与 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)。

 **堆栈信息** 
+  [获取 /stack-info](#get-stack-info) 

 **场景** 
+  [获取 /场景](#get-scenarios) 
+  [帖子/场景](#post-scenarios) 
+  [选项/场景](#options-scenarios) 
+  [获取 /scenarios/ {testID}](#get-scenarios-testid) 
+  [POST /scenarios/ {testID}](#post-scenarios-testid) 
+  [删除 /scenarios/ {testID}](#delete-scenarios-testid) 
+  [选项 /scenarios/ {testID}](#options-scenarios-testid) 

 **测试运行** 
+  [GET /scenarios/ {testID} /testruns](#get-scenarios-testid-testruns) 
+  [GET /scenarios/ {testID} /testruns/ {} testRunId](#get-scenarios-testid-testruns-testrunid) 
+  [删除 /scenarios/ {testID} /testruns/ {} testRunId](#delete-scenarios-testid-testruns-testrunid) 

 **基准** 
+  [GET /scenarios/ {testID} /baseline](#get-scenarios-testid-baseline) 
+  [PUT /scenarios/ {testID} /baseline](#put-scenarios-testid-baseline) 
+  [删除 /scenarios/ {testID} /baseline](#delete-scenarios-testid-baseline) 

 **任务** 
+  [获取 /tasks](#get-tasks) 
+  [选项 /任务](#options-tasks) 

 **区域** 
+  [获取 /区域](#get-regions) 
+  [选项 /区域](#options-regions) 

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

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

该`GET /stack-info`操作检索有关已部署堆栈的信息，包括创建时间、区域和版本。此端点由前端使用。

### 响应
<a name="get-stack-info-response"></a>

 **200-成功** 


| Name | 说明 | 
| --- | --- | 
|  `created_time`  | 创建堆栈时的 ISO 8601 时间戳（例如，）`2025-09-09T19:40:22Z` | 
|  `region`  | 部署堆栈的 AWS 区域（例如，`us-east-1`） | 
|  `version`  | 已部署解决方案的版本（例如，`v4.0.0`） | 

 **错误响应** 
+  `403`-禁止：访问堆栈信息的权限不足
+  `404`-未找到：堆栈信息不可用
+  `500`-服务器内部错误

## 获取 /场景
<a name="get-scenarios"></a>

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

该`GET /scenarios`操作允许您检索测试场景列表。

### 响应
<a name="get-scenarios-response"></a>


| Name | 说明 | 
| --- | --- | 
|  `data`  | 场景列表，包括每项测试的 ID、名称、描述、状态、运行时间、标签、总运行次数和上次运行时间 | 

## 帖子/场景
<a name="post-scenarios"></a>

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

该`POST /scenarios`操作允许您创建或安排测试场景。

### 请求正文
<a name="post-scenarios-request"></a>


| Name | 说明 | 
| --- | --- | 
|  `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`  | 预定测试的重复性。仅在安排重复测试（例如、`daily``weekly``biweekly`、或`monthly`）时提供 | 

### 响应
<a name="post-scenarios-response"></a>


| Name | 说明 | 
| --- | --- | 
|  `testId`  | 测试的唯一 ID | 
|  `testName`  | 测试的名称 | 
|  `status`  | 测试的状态 | 

## 选项/场景
<a name="options-scenarios"></a>

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

该`OPTIONS /scenarios`操作使用正确的 CORS 响应标头为请求提供响应。

### 响应
<a name="options-scenarios-response"></a>


| Name | 说明 | 
| --- | --- | 
|  `testId`  | 测试的唯一 ID | 
|  `testName`  | 测试的名称 | 
|  `status`  | 测试的状态 | 

## 获取 /scenarios/ {testID}
<a name="get-scenarios-testid"></a>

### 说明
<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>


| Name | 说明 | 
| --- | --- | 
|  `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/ {testID}
<a name="post-scenarios-testid"></a>

### 说明
<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>


| Name | 说明 | 
| --- | --- | 
|  `status`  | 测试的状态 | 

## 删除 /scenarios/ {testID}
<a name="delete-scenarios-testid"></a>

### 说明
<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>


| Name | 说明 | 
| --- | --- | 
|  `status`  | 测试的状态 | 

## 选项 /scenarios/ {testID}
<a name="options-scenarios-testid"></a>

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

该`OPTIONS /scenarios/{testId}`操作使用正确的 CORS 响应标头为请求提供响应。

### 响应
<a name="options-scenarios-testid-response"></a>


| Name | 说明 | 
| --- | --- | 
|  `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
<a name="get-scenarios-testid-testruns"></a>

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

该`GET /scenarios/{testId}/testruns`操作会检索特定测试场景 IDs 的测试运行，可以选择按时间范围进行筛选。W `latest=true` hen，仅返回最近的单个测试运行。

### 请求参数
<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-成功** 


| Name | 说明 | 
| --- | --- | 
|  `testRuns`  | 测试运行对象数组，每个对象包含`testRunId`（字符串）和`startTime`（ISO 8601 日期时间） | 
|  `pagination`  | 包含`limit`（整数）和`next_token`（字符串或空）的对象。如果没有更多结果，则令牌为空 | 

 **错误响应** 
+  `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/ {testID} /testruns/ {} testRunId
<a name="get-scenarios-testid-testruns-testrunid"></a>

### 说明
<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-成功** 


| Name | 说明 | 
| --- | --- | 
|  `testId`  | 测试的唯一 ID（例如，`seQUy12LKL`） | 
|  `testRunId`  | 特定的测试运行 ID（例如，`2DEwHItEne`） | 
|  `testDescription`  | 负载测试的描述 | 
|  `testType`  | 测试的类型（例如，`simple`，`jmeter`） | 
|  `status`  | 测试运行的状态：`complete`、`running``failed`、或 `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_0`、`p99_9`、、、`p100_0`）、`avg_rt`（平均响应时间）、`avg_ct`（平均连接时间）、`stdev_rt`（标准差响应时间）、`concurrency``throughput`、`succ`（成功计数）、`fail`（失败计数）、`bytes`、`testDuration``metricS3Location`、`rc`（响应代码数组）和`labels`数组 | 
|  `testScenario`  | 包含带有`execution``reporting`、和`scenarios`属性的测试配置的对象 | 
|  `history`  | 历史测试结果数组（不包括何时`history=false`） | 

 **错误响应** 
+  `400`-测试编号无效或 testRunId
+  `404`-未找到测试运行
+  `500`-服务器内部错误

## 删除 /scenarios/ {testID} /testruns/ {} testRunId
<a name="delete-scenarios-testid-testruns-testrunid"></a>

### 说明
<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`-测试编号无效或 testRunId
+  `403`-禁止：权限不足，无法删除测试运行
+  `404`-未找到测试运行
+  `409`-冲突：测试运行当前正在运行，无法删除
+  `500`-服务器内部错误

## GET /scenarios/ {testID} /baseline
<a name="get-scenarios-testid-baseline"></a>

### 说明
<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`（默认）：


| Name | 说明 | 
| --- | --- | 
|  `testId`  | 测试场景 ID（例如，`seQUy12LKL`） | 
|  `baselineTestRunId`  | 基准测试运行 ID（例如，`2DEwHItEne`） | 

什么时候`data=true`：


| Name | 说明 | 
| --- | --- | 
|  `testId`  | 测试场景 ID（例如，`seQUy12LKL`） | 
|  `baselineTestRunId`  | 基准测试运行 ID（例如，`2DEwHItEne`） | 
|  `baselineData`  | 完成测试运行结果对象（结构与`GET /scenarios/{testId}/testruns/{testRunId}`） | 

 **错误响应** 
+  `400`-无效的 testID 参数
+  `404`-未找到测试场景或未设置基准
+  `500`-服务器内部错误

## PUT /scenarios/ {testID} /baseline
<a name="put-scenarios-testid-baseline"></a>

### 说明
<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>


| Name | 说明 | 
| --- | --- | 
|  `testRunId`  | 要设置为基准的测试运行 ID（例如，`2DEwHItEne`） | 

### 响应
<a name="put-scenarios-testid-baseline-response"></a>

 **200-成功** 


| Name | 说明 | 
| --- | --- | 
|  `message`  | 确认消息（例如，`Baseline set successfully`） | 
|  `testId`  | 测试场景 ID（例如，`seQUy12LKL`） | 
|  `baselineTestRunId`  | 设置的基准测试运行 ID（例如，`2DEwHItEne`） | 

 **错误响应** 
+  `400`-测试编号无效或 testRunId
+  `404`-未找到测试场景或测试运行
+  `409`-冲突：无法将测试运行设置为基准（例如，测试失败）
+  `500`-服务器内部错误

## 删除 /scenarios/ {testID} /baseline
<a name="delete-scenarios-testid-baseline"></a>

### 说明
<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`-无效的测试 ID
+  `500`-服务器内部错误

## 获取 /tasks
<a name="get-tasks"></a>

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

该`GET /tasks`操作允许您检索正在运行的亚马逊弹性容器服务 (Amazon ECS) 任务列表。

### 响应
<a name="get-tasks-response"></a>


| Name | 说明 | 
| --- | --- | 
|  `tasks`  | 运行测试 IDs 的任务列表 | 

## 选项 /任务
<a name="options-tasks"></a>

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

`OPTIONS /tasks`任务操作使用正确的 CORS 响应标头为请求提供响应。

### 响应
<a name="options-tasks-response"></a>


| Name | 说明 | 
| --- | --- | 
|  `taskIds`  | 运行测试 IDs 的任务列表 | 

## 获取 /区域
<a name="get-regions"></a>

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

该`GET /regions`操作允许您检索在该区域运行测试所需的区域资源信息。

### 响应
<a name="get-regions-response"></a>


| Name | 说明 | 
| --- | --- | 
|  `testId`  | 区域 ID | 
|  `ecsCloudWatchLogGroup`  | 该地区的 Amazon Fargate 任务的亚马逊 CloudWatch 日志组的名称 | 
|  `region`  | 表中资源所在的区域 | 
|  `subnetA`  | 该区域中一个子网的 ID | 
|  `subnetB`  | 该区域中一个子网的 ID | 
|  `taskCluster`  | 该地区的 AWS Fargate 集群的名称 | 
|  `taskDefinition`  | 该区域中任务定义的 ARN | 
|  `taskImage`  | 区域中任务镜像的名称 | 
|  `taskSecurityGroup`  | 该区域中安全组的 ID | 

## 选项 /区域
<a name="options-regions"></a>

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

该`OPTIONS /regions`操作使用正确的 CORS 响应标头为请求提供响应。

### 响应
<a name="options-regions-response"></a>


| Name | 说明 | 
| --- | --- | 
|  `testId`  | 区域 ID | 
|  `ecsCloudWatchLogGroup`  | 该地区的 Amazon Fargate 任务的亚马逊 CloudWatch 日志组的名称 | 
|  `region`  | 表中资源所在的区域 | 
|  `subnetA`  | 该区域中一个子网的 ID | 
|  `subnetB`  | 该区域中一个子网的 ID | 
|  `taskCluster`  | 该地区的 AWS Fargate 集群的名称 | 
|  `taskDefinition`  | 该区域中任务定义的 ARN | 
|  `taskImage`  | 区域中任务镜像的名称 | 
|  `taskSecurityGroup`  | 该区域中安全组的 ID |