マイルストーンに関する情報を取得したり、マイルストーンを作成または変更するには、次の API メソッドを使用します。
get_milestone
既存のマイルストーンを返します。
GET index.php?/api/v2/get_milestone/{milestone_id}
パラメーター
| 名前 | タイプ | 必須 | 説明 |
|---|---|---|---|
| milestone_id | integer | true | マイルストーンの ID |
レスポンスの内容
典型的なレスポンスについては、下記を参照してください。
{
"completed_on": 1389968184,
"description": "...",
"due_on": 1391968184,
"id": 1,
"is_completed": true,
"name": "Release 1.5",
"project_id": 1,
"refs": "RF-1, RF-2",
"url": "http:///testrail/index.php?/milestones/view/1"
}
レスポンスには次のフィールドが含まれています。
| 名前 | タイプ | 説明 |
|---|---|---|
| completed_on | timestamp | マイルストーンが完了とマークされた日時 (UNIX タイムスタンプ) |
| description | string | マイルストーンの説明 |
| due_on | timestamp | マイルストーンの期日 (UNIX タイムスタンプ) |
| id | integer | マイルストーンの一意の ID |
| is_completed | boolean | マイルストーンが完了としてマークされている場合は true、そうでない場合は false |
| is_started | boolean | マイルストーンが開始済みとしてマークされている場合は true、そうでない場合は false (TestRail 5.3 以降で利用可能) |
| milestones | array | マイルストーンに所属するサブマイルストーン (存在する場合)。get_milestone でだけ利用可能 (TestRail 5.3 以降で利用可能) |
| name | string | マイルストーンの名前 |
| parent_id | integer | マイルストーンが所属する親マイルストーンの ID (存在する場合) (TestRail 5.3 以降で使用可能) |
| project_id | integer | マイルストーンが所属するプロジェクトの ID |
| refs | string | 参照/要件のカンマ区切りリスト (TestRail 6.4 以降が必要) |
| start_on | timestamp | マイルストーンの開始予定日時 (UNIXタイムスタンプ) (TestRail 5.3以降で利用可能) |
| started_on | timestamp | マイルストーンの開始日時 (UNIXタイムスタンプ) (TestRail 5.3以降で利用可能) |
| url | string | ユーザー インターフェイスに表示されるマイルストーンのアドレス/URL |
レスポンス コード
| ステータス コード | 説明 |
|---|---|
| 200 | 成功。マイルストーンがレスポンスの一部として返されます |
| 400 | 無効または不明なマイルストーンです |
| 403 | プロジェクトにアクセスできない |
| 429 | TestRail Cloud のみ – リクエストが多すぎます |
get_milestones
プロジェクトのマイルストーンのリストを返します。
GET index.php?/api/v2/get_milestones/{project_id}
パラメーター
| 名前 | タイプ | 必須 | 説明 |
|---|---|---|---|
| project_id | integer | true | プロジェクトの ID |
リクエスト フィルター
リクエスト URL の query パラメーターとして、以下のフィルターを適用できます。
| 名前 | タイプ | 説明 |
|---|---|---|
| is_completed | boolean | 1 を指定すると完了したマイルストーンだけを返します。0 を指定すると、オープン中の (アクティブな/今後開始される) マイルストーンだけを返します。 |
| is_started | boolean | 1 を指定すると開始済みのマイルストーンだけを返します。0 を指定すると、今後開始されるマイルストーンだけを返します (TestRail 5.3以降で使用可能)。 |
| limit | integer | レスポンスが返すマイルストーンの数 (デフォルトのレスポンスのサイズは 250) (TestRail 6.7 以降が必要) |
| offset | integer | マイルストーンのカウントを開始する位置 (オフセット) (TestRail 6.7 以降が必要) |
# All active milestones for project with ID 1 GET index.php?/api/v2/get_milestones/1&is_completed=0
レスポンスの内容
レスポンスにはマイルストーンの配列が含まれます。リスト内の各マイルストーンの形式は、get_milestone と同じです。
{
"offset": 0,
"limit": 250,
"size": 5,
"_links": {
"next": null,
"prev": null,
},
"milestones": [
{ "id": 1, "name": "Release 1.5", .. },
{ "id": 2, "name": "Release 1.6", .. },
..
]
}
レスポンス コード
| ステータス コード | 説明 |
|---|---|
| 200 | 成功。マイルストーンがレスポンスの一部として返されます |
| 400 | 無効または不明なプロジェクトです |
| 403 | プロジェクトにアクセスできない |
| 429 | TestRail Cloud のみ – リクエストが多すぎます |
add_milestone
新規マイルストーンを作成します。
POST index.php?/api/v2/add_milestone/{project_id}
パラメーター
| 名前 | タイプ | 必須 | 説明 |
|---|---|---|---|
| project_id | integer | true | マイルストーンを追加するプロジェクトの ID |
リクエスト フィルター
リクエスト URL の query パラメーターとして、以下のフィルターを適用できます。
| 名前 | タイプ | 必須 | 説明 |
|---|---|---|---|
| name | string | true | マイルストーンの名前 |
| description | string | false | マイルストーンの説明 |
| due_on | timestamp | false | マイルストーンの期日 (UNIX タイムスタンプ) |
| parent_id | integer | false | 存在する場合、親マイルストーンの ID (サブマイルストーンの場合) (TestRail 5.3 以降で使用可能) |
| refs | string | false | 参照/要件のカンマ区切りリスト (TestRail 6.4 以降が必要) |
| start_on | timestamp | false | マイルストーンの開始予定日 (UNIXタイムスタンプ) (TestRail 5.3以降で利用可能) |
リクエストの例
期限を指定した新しい空のマイルストーンを作成する方法を示す例については下記を参照してください。
{
"name": "Release 2.0",
"due_on": 1394596385
}
レスポンスの内容
成功した場合、このメソッドは get_milestone と同じレスポンス形式を使用して新しいマイルストーンを返します。
レスポンス コード
| ステータス コード | 説明 |
|---|---|
| 200 | 成功。マイルストーンが作成され、レスポンスの一部として返されます |
| 400 | 無効または不明なプロジェクトです |
| 403 | マイルストーンを追加する権限、またはプロジェクトへのアクセス権がありません |
| 429 | TestRail Cloud のみ – リクエストが多すぎます |
update_milestone
既存のマイルストーンを更新します (部分的な更新がサポートされています。つまり、特定のフィールドのみを送信して更新できます)。
POST index.php?/api/v2/update_milestone/{milestone_id}
パラメーター
| 名前 | タイプ | 必須 | 説明 |
|---|---|---|---|
| milestone_id | integer | true | マイルストーンの ID |
リクエスト ボディ
リクエスト ボディで以下のフィルターを適用できます。
| 名前 | タイプ | 説明 |
|---|---|---|
| is_completed | boolean | マイルストーンが完了と見なされる場合は true、そうでない場合は false |
| is_started | boolean | マイルストーンが開始済みと見なされる場合は true、そうでない場合は false |
| parent_id | integer | 存在する場合、親マイルストーンの ID (サブマイルストーンの場合) (TestRail 5.3 以降で使用可能) |
| start_on | timestamp | マイルストーンの開始予定日 (UNIXタイムスタンプ) (TestRail 5.3以降で利用可能) |
リクエストの例
マイルストーンを完了としてマークする方法を示す例については下記を参照してください。
{
"is_completed": true
}
レスポンスの内容
成功した場合、このメソッドは get_milestone と同じレスポンス形式を使用して更新されたマイルストーンを返します。
レスポンス コード
| ステータス コード | 説明 |
|---|---|
| 200 | 成功。マイルストーンが更新され、レスポンスの一部として返されます |
| 400 | 無効または不明なマイルストーンです |
| 403 | マイルストーンを更新する権限、またはプロジェクトへのアクセス権がありません |
| 429 | TestRail Cloud のみ – リクエストが多すぎます |
delete_milestone
削除したマイルストーンを元に戻すことはできません。 既存のマイルストーンを削除します。POST index.php?/api/v2/delete_milestone/{milestone_id}
パラメーター
名前
タイプ
必須
説明
milestone_id
integer
true
マイルストーンの ID
レスポンス コード
ステータス コード
説明
200
成功。マイルストーンは削除されました
400
無効または不明なマイルストーンです
403
マイルストーンを削除する権限、またはプロジェクトへのアクセス権がありません
429
TestRail Cloud のみ – リクエストが多すぎます