API: API へのアクセス
TestRail の API は HTTP ベースであり、単純な HTTP リクエストを使用して対話できます。すべての書き込みリクエストは HTTP POST メソッドを使用し、すべての読み取りリクエストは HTTP GET メソッドを使用する必要があります。データは UTF-8 エンコーディングの JSON 形式で転送されます。
認証
TestRail は、API の認証情報が標準的な HTTP ベーシック認証によって指定されると期待します。TestRail で API リクエストを認証する方法は2つあります。
ユーザー名とパスワード
標準の TestRail ユーザー名 (通常は電子メールアドレス) と TestRail パスワードを TestRail に渡して API 認証を行うことができます。これは HTTP のベーシック認証で送信する必要があります。
TestRail 認証の設定によっては、パスワードが通常の Active Directory または LDAP のパスワードである場合もあります (TestRail の設定によって異なります。詳細はこちらを参照してください)。TestRail でどのオプションが使用されているかわからない場合は、TestRail 管理者にお問い合わせください。
ユーザー名と API キー
別の方法として、TestRail は API キーもサポートします。API キーは TestRail の [個人設定] で生成できます。API キーを使用する場合も、HTTP のベーシック認証を使用して TestRail のユーザー名 (メールアドレスなど) を送信します。パスワードを任意の生成された/アクティブな API キーで置き換えます。複数の API キーを生成してシステムまたはサードパーティ製ツールごとに使い分け、 [個人設定] で API キーを削除することで、いつでもアクセスを取り消すことができます。
API を使用するには TestRail のユーザー名とパスワードを送信する必要があるため、自組織のサーバー上で TestRail インスタンスを管理している場合、TestRail の HTTPS を有効にすることをお勧めします。Gurock によって管理されている TestRail Hosted アカウントの場合、すべてのアカウントが自動的に HTTPS を使用します。
API スクリプト リポジトリ
パブリックな GitHub リポジトリにサンプル API スクリプトがあります。そのままで、あるいは簡単な変更だけでお客様のニーズに合うスクリプトが見つかるかもしれません。リポジトリはこちらにあります。
このリポジトリには、他のユーザーの役に立つ可能性がある自作のスクリプトをサブミットできます。
GET リクエストの例
次の例は、テスト ケースを読み取る単純なリクエストを示しています。この例では cURL コマンドラインツールを使用してリクエストを送信していますが、どの HTTP ツールまたはライブラリでも機能します。すべてのユーザー名、パスワード、および URL はサンプルです。
$ curl -H "Content-Type: application/json" -u "user@example.com:<some-password>" "https://example.testrail.com/index.php?/api/v2/get_case/1"
リクエストの各部分の詳細：
| 部分 | 説明 |
|---|---|
| “Content-Type: application/json” | 必須ヘッダー |
| https://example.testrail.com/ | サーバー アドレス |
| index.php?/api/v2/ | TestRail API のパス |
| get_case | 呼び出される API メソッド |
| /1 | API メソッドへの引数 |
実際の HTTP リクエストとレスポンスは次のようになります (簡略化されています)。
GET /index.php?/api/v2/get_case/1 HTTP/1.1 Host: example.testrail.com Content-Type: application/json
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"id":1,
"title":"An example test case"
..
}POST リクエストの例
次の例は、テスト結果を送信する単純な書き込みリクエストを示しています。
$ curl -H "Content-Type: application/json"
-u "user@example.com:<some-password>"
-d '{ "status_id": 1 }'
"https://example.testrail.com//index.php?/api/v2/add_result/1"リクエストとレスポンスは次のようになります (簡略化されています)。
POST /index.php?/api/v2/add_result/1 HTTP/1.1
Host: example.testrail.com
Content-Type: application/json
{ "status_id": 1 }HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"id":1,
"test_id":1,
"status_id":1
..
}添付ファイル アップロードの例
次の例は、テスト結果に添付ファイルを追加する単純な書き込みリクエストを示しています。
$ curl -H "Content-Type: multipart/form-data" \ -u "user@example.com:<some-password>" \ -F "attachment=@C:\\image.jpg" \ "https://example.testrail.io/index.php?/api/v2/add_attachment_to_result/1"
リクエストとレスポンスは次のようになります (簡略化されています)。
POST /index.php?/api/v2/add_attachment_to_result/1 HTTP/1.1 Host: example.testrail.io Content-Type: multipart/form-data <File contents>
{"attachment_id":11}