REST API
TeamCity は、外部アプリケーションを統合し、TeamCity サーバーとのスクリプト相互作用を作成するための REST API を提供します。
REST API は、TeamCity 5.0 以降にバンドルされているオープンソースプラグイン(英語)です。
TeamCity の REST API では、URL パスを介してリソース(エンティティ)にアクセスできます。REST API を使用するには、外部アプリケーションが TeamCity サーバーに HTTP リクエストを送信し、そのレスポンスを解析します。
このページでは、REST API 認証の原理、リクエストの構造、サポートされる HTTP メソッドについて説明します。
最も使用されているデータエンティティリクエストのリストについては、REST API リファレンスページを参照してください。
リクエストの例も参照してください。
一般的な使用箇所
このドキュメントは完全なガイドではなく、API の操作に役立ついくつかの初期知識のみを提供します。
このページの URL の例では、TeamCity サーバーの Web UI に http://teamcity:8111
(英語) の URL からアクセスできると仮定しています。
ブラウザーで http://teamcity:8111/app/rest/server
(英語) URL を開くことから始めることができます:このページはあなたに API を探索するためのいくつかのポインタを与えるでしょう。
http://teamcity:8111/app/rest/application.wadl
(英語) を使用して、サポートされているリクエストとパラメーターの名前の完全なリストを取得します。これは、サポートされている要求とそのパラメーターの検出の主要なソースです。同じデータは、 http://teamcity:8111/app/rest/swagger.json
(英語) エンドポイントを介して Swagger(英語) 形式でも公開されます。
エラーレスポンスに含まれるサポートされているロケーターディメンションのリストについては、$help
ロケーターを使用してください。
返されたエラーメッセージを実験して参照してください。ほとんどの場合、それらは正しい要求にあなたを導くはずです。
エージェントの詳細を調べ、( /app/rest/server
応答で) /app/rest/agents
URL があることを確認したいとします。
/app/rest/agents/
要求を試してください。許可されたエージェントのリストを参照し、エージェントの要素のhref
属性からエージェントにリンクするdefault
の方法を取得します。/app/rest/agents/id:10
URL(前の要求の要素の 1 つについてはhref
から取得)を介して個々のエージェントの詳細を取得します。/app/rest/agents/$help
または/app/rest/agents/aaa:bbb
(サポートされていないロケーターディメンションを提供)にリクエストを送信すると、エージェントのロケーターを介してエージェントを見つけるためにサポートされているディメンションのリストが表示されます。返されるエージェントデータ(
name
,connected
,authorized
)の属性のほとんどは、app/rest/agents/<agentLocator>/<field_name>
要求で<field_name>
として使用できます。さらに、app/rest/agents/id:10/test
URL にリクエストを発行すると、サポートされているフィールドのリストがエラーメッセージに表示されます。
REST 認証
REST API では、次の方法で認証できます。
REST API にアクセスする推奨する方法は、トークンベースの HTTP 認証を使用することです。HTTP ヘッダー
Authorization: Bearer <token-value>
の設定とツール | アクセストークンで生成された個人用 TeamCity アクセストークンを提供します。例:curl --header "Authorization: Bearer <token-value>" http://teamcity:8111/app/rest/builds基本的な HTTP 認証を使用します(特定の認証では遅くなることがあります。下記参照)。リクエストに有効な TeamCity ユーザー名とパスワードを入力してください。
/app/rest
の前にhttpAuth
を含めることで基本認証を強制できます。http://teamcity:8111/httpAuth/app/rest/builds
(英語)ゲストユーザーとしてサーバーへのアクセスを使用する場合(有効な場合)、
guestAuth
を/app/rest
部分の前に含めます (例:http://teamcity:8111/guestAuth/app/rest/builds
(英語))。ブラウザー内から REST
GET
リクエストを確認していて、ブラウザーで TeamCity にログインしている場合は、/app/rest
URL を使用できます。http://teamcity:8111/app/rest/builds
(英語)。
組み込みモジュールを使用しない基本 HTTP 認証を使用すると、認証が遅くなる可能性があります。トークンベースの認証ではなく基本 HTTP 認証を使用する場合は、セッション再利用アプローチ(英語)を適用して、順次要求間で認証を再利用(英語)することを検討してください。
TeamCity ビルド内からリクエストを実行する場合、(アーティファクトのダウンロードなどの)ビルド関連操作の限られたセットに対して、 teamcity.auth.userId/teamcity.auth.password
システムプロパティの値を基本認証情報として使用できます(TeamCity 設定内では、%system.teamcity.auth.userId%
および %system.teamcity.auth.password%
として参照できます)。
ビルド内では、現在のビルド詳細の要求は次のようになります。
スーパーユーザーアクセス
REST API でスーパーユーザーアカウントを使用できます。ユーザー名と生成されたパスワードをサーバーログに記録しないでください。
REST API のバージョン
REST API がある TeamCity バージョンから別のバージョンに進化するにつれて、プロトコルに互換性のない変更が生じる可能性があります。
http://teamcity:8111/app/rest/
(英語) または http://teamcity:8111/app/rest/latest
(英語) URL で、最新バージョンを入手できます。
以前のバージョンは、 http://teamcity:8111/app/rest/<version>
(英語) URL で入手できる場合があります。私たちの一般的なポリシーは、TeamCity に少なくとも 1 つの以前のバージョンを提供することです。REST API プロトコルバージョンは、このプロトコルが最初に導入された TeamCity バージョンです。
プロトコルの最新のレガシーバージョンは 2018.1 です。アクセスするには、<version>
の代わりに 2018.1
を使用してください。その他のバンドルバージョンは、2017.2
, 2017.1
, 10.0
, 9.1
, 9.0
, 8.1
, 8.0
です。
API の重大な変更点は、関連するアップグレードノートセクションに記載されています。返されるオブジェクトへの追加(新しい XML 属性や要素など)は大きな変更とは見なされず、プロトコルバージョンが増加することもありません。また、application.wadl
で Experimental
コメントでマークされたエンドポイントは、将来のバージョンで特別な通知なしに変更される可能性があります。
URL の構造
TeamCity API の URL の一般的な構造は http://teamcityserver:port/<authType>/app/rest/<apiVersion>/<restApiPath>?<parameters>
(英語) です
where
teamcityserver
とport
は、TeamCity が使用するサーバー名とポートを定義します。このページは URL の例としてhttp://teamcity:8111/
(英語) を使用しています。<authType>
(オプション)は、使用する認証タイプです。これは、一般的な TeamCity 機能です。app/rest
は TeamCity REST API のルートパスです<apiVersion>
(オプション)は、REST API の特定のバージョンへの参照です。<restApiPath>?<parameters>
は、URL の REST API 部分です。
複数のアイテムを取得する一般的な方法は、.../app/rest/<items>
の形式で<restApiPath>
を使用することです(たとえば、.../app/rest/builds
)。これらの URL は、返されるアイテムをフィルタリングできるロケーターパラメーターを定期的に受け入れます。個々のアイテムは、.../app/rest/<items>/<item_locator>
の形式の URL で定期的にアドレス指定できます。この URL は常に単一のアイテムを返します。<item_locator>
ロケーターが複数のアイテムと一致する場合、最初のアイテムが返されます。複数アイテムと単一アイテムの両方のリクエストで、定期的に fields パラメーターがサポートされています。
ロケーター
In a number of places, you can specify a filter string which defines what entities to filter/affect in the request. This string representation is referred to as locator in the scope of the TeamCity REST API.
ロケーターの形式は次のとおりです。
単一値: 次の記号のないテキスト:
,:-( )
複数の基準を使用してエンティティをフィルタリングできるディメンション:
<dimension1>:<value1>,<dimension2>:<value2>,<dimension3>:(<dimension3.1>:<value3.1>,<dimension3.2>:<value3.2>)
ネストされたロケーターは括弧で囲む必要があることに注意してください。最も一般的なロケーターの説明については、REST API リファレンスのエンティティの説明を参照してください。特定のロケーターが何をサポートしているかわからない場合は、ロケーター値として「$help」を使用してリクエストを送信してください。応答では、ロケーターがサポートする内容のテキストによる説明が表示されます。無効なロケーターを含むリクエストが送信された場合、エラーメッセージはエラーを提案し、サポートされているロケーターのディメンションも一覧表示することがよくあります。
例:
プロジェクトのリストを取得するには
http://teamcity:8111/app/rest/projects
(英語) を使用してください。REST API プラグインプロジェクトの全データを取得するには、
http://teamcity:8111/app/rest/projects/<projectsLocator>
(英語)、たとえばhttp://teamcity:8111/app/rest/projects/id:RESTAPIPlugin
(英語)(サンプル ID を使用)を使用します。ビルドを取得するには、
http://teamcity:8111/app/rest/buildTypes/id:bt284/builds?locator=status:SUCCESS,tag:EAP
(英語)(例の ID が使用されている)などのhttp://teamcity:8111/app/rest/buildTypes/id:bt284/builds?locator=<buildLocator>
(英語) を使用します。ビルドロケーターによるビルドを取得するには
http://teamcity:8111/app/rest/builds/?locator=<buildLocator>
(英語) を使用してください。
サポートされている HTTP メソッド
GET
: 要求されたデータを取得します。例:.../app/rest/entities
は通常エンティティのリストを取得し、.../app/rest/entities/<entity locator>
は単一のエンティティを取得しますPOST
: 送信されたペイロードからエンティティを作成します。新しいエンティティを作成するには、定期的に単一のエンティティデータ(つまり、GET を介して取得されたもの)を.../app/rest/entities
URL に投稿する必要があります。XML を投稿するときは、必ずContent-Type: application/xml
HTTP ヘッダーを指定してください。PUT
: 送信されたペイロードからデータを更新します。同じ URL への GET リクエストで取得したものと同じデータ形式を受け入れます。.../app/rest/entities/<entity locator>
などの URL の一部のエンティティでサポートDELETE
:.../app/rest/entities/<entity locator>
などの URL のデータを削除します
ログ関連
エラーおよび REST リクエスト処理の詳細は、logs\teamcity-rest.log
サーバーログで取得できます。
要求に応えてエラーを受け取り、その理由を調査したい場合は、休息関連サーバーログを調べましょう。
処理された各リクエストの詳細を取得するには、デバッグログをオンにします(たとえば、管理 / 診断ページで Logging Preset を debug-rest
に設定するか、Log4J jetbrains.buildServer.server.rest
カテゴリを変更します)。
CORS のサポート
TeamCity REST API は、rest.cors.origins
内部プロパティを使用してクロスオリジン要求(英語)を許可するように構成できます。
特定のドメインから読み込まれたページからのリクエストを許可するには、ページアドレス(プロトコルとポートを含む、ワイルドカードはサポートされていません)をコンマ区切りの内部プロパティ rest.cors.origins
に追加します。例: rest.cors.origins=http://myinternalwebpage.org.com:8080,https://myinternalwebpage.org.com
プリフライト OPTIONS リクエスト(英語)のサポートを有効にするには:
API クライアントの推奨事項
REST API を使用してクライアントを開発するときは、以下の推奨事項を考慮してください。
ルート REST API URL を構成可能にします(たとえば、URL の
app/rest/<version>
部分の代替を指定できるようにします)。これにより、必要に応じてクライアントを別のバージョンの API に誘導できます。クライアントに知られていないアイテムの属性とサブアイテムを無視します(エラーにしないでください)。新しいサブアイテムはバージョンを変更せずに API に追加されることがあります。これにより、クライアントは変更による影響を受けません。
大きなリクエストタイムアウトを設定します(そして設定可能にします)。特に大規模なサーバーでは、API 呼び出しによっては数分かかることがあります。
HTTP セッションを使用して連続したリクエストを作成します(常に生の資格情報を提供するのではなく、最初の認証済み応答から返される
TCSESSIONID
Cookie を使用します)。これにより、外部認証プロバイダーにとって重要な認証の時間を節約できます。アイテムのリストをリクエストするときは、部分的な回答に注意してください。一部のリクエストはデフォルトでページングされます。応答の
count
属性の値は、現在のページのアイテム数を示し、さらに多くのページが利用できる場合があります。さらに(またはすべての)アイテムを処理する必要がある場合は、アイテムコレクションの応答エンティティのnextHref
属性を読み取って処理します。この属性が存在する場合は、提供された URL でクエリを実行すると、さらに項目が存在する可能性があることを意味します。関連するロケーターの次元は、count
(ページ制限)およびlookupLimit
(検索の深さ)です。返されたcount
が 0 であっても、「nextHref」が存在する場合、それ以上のアイテムがないという意味ではありません。属性が存在します。考え直さずにロケーターの
lookupLimit
値を大きくしないでください。これを実行すると、サーバーへの負荷が増えるという直接的な影響があり、CPU とメモリの使用量が増加する可能性があります。デフォルトの制限を増やす人は、サーバーのパフォーマンスへの悪影響を理解していると考えられます。TeamCity API の自動リクエストを実行する機能を悪用しないでください。API を頻繁にクエリしないで、リクエストされたデータを必要なものだけに制限してください(期限ロケーターを使用し、必要なフィールドを指定します)。あなたの要求から負荷でサーバーの動作を確認してください。要求の処理に時間がかかる場合は、要求を頻繁に繰り返さないようにしてください。
応答フォーマット
TeamCity REST API は、HTTP の「Accept」に従って、次の形式で HTTP レスポンスを返します。ヘッダ:
フォーマット | レスポンスタイプ | HTTP "承認" ヘッダー値 |
---|---|---|
プレーンテキスト | 単一値応答 | テキスト / プレーン |
XML | 複素数値応答 | application / xml |
JSON | 複素数値応答 | アプリケーション / JSON |
完全および部分的な回答
デフォルトでは、エンティティのリストが要求されると、基本フィールドのみが応答に含まれます。単一のエントリが要求されると、すべてのフィールドが返されます。複雑なフィールド値は、特定のエンティティに応じて、完全形式または基本形式で返すことができます。
ほとんどのリクエストで、XML および JSON 応答に対して返されるフィールドのセットを変更することが可能です。これは、応答で返す最上位エンティティとサブエンティティのフィールドを説明する fields リクエストパラメーターを指定することで行われます。パラメーターの構文の例は、field,field2(field2_subfield1,field2_subfield1)
です。これは基本的に、「最上位エンティティの field
および field2
を含め、field2
の場合は field2_subfield1
および field2_subfield1
フィールドを含める」ことを意味します。フィールド仕様の順序は関係ありません。
例:
現時点では、応答には特に要求されていないフィールド / 要素が含まれることがあります。これは将来のバージョンでは変更される可能性があるため、クライアントが使用するすべてのフィールド / 要素を指定することをお勧めします。