分散負荷テスト API - AWS での分散負荷テストソリューション
GET /stack-infoGET /scenariosPOST /scenariosOPTIONS /scenariosGET /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 /tasksOPTIONS /tasksGET /regionsOPTIONS /regions

分散負荷テスト API

この負荷テストソリューションは、テスト結果データを安全な方法で公開するのに役立ちます。API は、Amazon DynamoDB に保存されているテストデータにアクセスするための「フロントドア」として機能します。また、API を使用して、ソリューションに独自に拡張機能を組み込むことも可能です。

このソリューションでは、Amazon API Gateway と統合された Amazon Cognito ユーザープールを使用して、識別と認可を行います。API でユーザープールを使用する場合、クライアントは有効な ID トークンを提供した後にのみ、ユーザープールでアクティブ化されたメソッドを呼び出すことができます。

API 経由でテストを直接実行する方法の詳細については、Amazon API Gateway REST API リファレンスドキュメントの「リクエストの署名」を参照してください。

ソリューションの API では、以下のオペレーションが利用可能です。

注記

testScenario やその他のパラメータの詳細については、GitHub リポジトリにあるシナリオとペイロードの例を参照してください。

スタック情報

シナリオ

テスト実行

BASELINE

タスク

リージョン

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 /scenarios

説明

GET /scenarios の操作を使用すると、テストシナリオの一覧を取得できます。

応答

名前 説明

data

各テストの ID、名前、説明、ステータス、実行時間、タグ、合計実行数、最後の実行を含むシナリオのリスト

POST /scenarios

説明

POST /scenarios の操作では、テストシナリオを作成またはスケジューリングできます。

リクエスト本文

名前 説明

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)

応答

名前 説明

testId

テストの一意の ID

testName

テストの名前

status

テストのステータス

OPTIONS /scenarios

説明

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

テストを実行するためのタスク ID の一覧

results

テストの最終結果

history

過去のテストの最終結果の一覧 (history=false の場合、除外されます)

totalRuns

このシナリオのテスト実行の合計数

lastRun

最後のテスト実行のタイムスタンプ

errorReason

エラーが発生したときに生成されるエラーメッセージ

nextRun

次にスケジューリングされている実行 (例: 2017-04-22 17:18:00)

scheduleRecurrence

テストの繰り返し (例: daily、weekly、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

テストを実行するためのタスク ID の一覧

results

テストの最終結果

history

過去のテストの最終結果の一覧

errorReason

エラーが発生したときに生成されるエラーメッセージ

GET /scenarios/{testId}/testruns

説明

GET /scenarios/{testId}/testruns オペレーションは、特定のテストシナリオのテスト実行 ID を取得し、オプションで時間範囲でフィルタリングします。latest=true の場合、最新のテスト実行を 1 つだけ返します。

パラメータのリクエスト

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、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 - 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 オペレーションは、パフォーマンスの比較のベースラインとして特定のテスト実行を指定します。シナリオごとに設定できるベースラインは 1 つだけです。

パラメータのリクエスト

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 /tasks

説明

GET /tasks の操作を使用すると、実行中の Amazon Elastic Container Service (Amazon ECS) タスクの一覧を取得できます。

応答

名前 説明

tasks

テストを実行するためのタスク ID の一覧

OPTIONS /tasks

説明

OPTIONS /tasks のタスク操作では、正しい CORS レスポンスヘッダーを持つリクエストのレスポンスを提供します。

応答

名前 説明

taskIds

テストを実行するためのタスク ID の一覧

GET /regions

説明

GET /regions の操作では、そのリージョンでテストを実行するために必要なリージョン別のリソース情報を取得できます。

応答

名前 説明

testId

リージョン ID

ecsCloudWatchLogGroup

リージョン内の Amazon Fargate タスク用の Amazon CloudWatch ロググループの名前

region

テーブル内のリソースが存在するリージョン

subnetA

リージョン内のいずれかのサブネットの ID

subnetB

リージョン内のいずれかのサブネットの ID

taskCluster

リージョン内の AWS Fargate クラスターの名前

taskDefinition

リージョン内のタスク定義の ARN

taskImage

リージョン内のタスクイメージの名前

taskSecurityGroup

リージョン内のセキュリティグループの ID

OPTIONS /regions

説明

OPTIONS /regions の操作は、正しい CORS レスポンスヘッダーを持つリクエストのレスポンスを提供します。

応答

名前 説明

testId

リージョン ID

ecsCloudWatchLogGroup

リージョン内の Amazon Fargate タスク用の Amazon CloudWatch ロググループの名前

region

テーブル内のリソースが存在するリージョン

subnetA

リージョン内のいずれかのサブネットの ID

subnetB

リージョン内のいずれかのサブネットの ID

taskCluster

リージョン内の AWS Fargate クラスターの名前

taskDefinition

リージョン内のタスク定義の ARN

taskImage

リージョン内のタスクイメージの名前

taskSecurityGroup

リージョン内のセキュリティグループの ID