TeamCity RESTAPI について
TeamCity provides a REST API for integrating external applications and creating script interactions with the TeamCity server. It allows accessing resources (entities) via URL paths. To use the REST API, an external application makes an HTTP request to the TeamCity server and parses the response.
This documentation comprises general descriptions of TeamCity REST API and autogenerated sections Models, Locators, and Methods, which reflect the state of the current REST API version. This article gives a quick overview of the REST API principles.
REST API は、TeamCity 5.0 以降にバンドルされているオープンソースプラグイン(英語)です。
一般的な使用箇所
You can start working with the REST API by opening http://<TeamCity URL>:<port>/app/rest/server
URL in your browser: this page gives several pointers to explore the API.
The full list of supported requests and names of parameters is exposed in the Swagger(英語) format via the http://<TeamCity URL>:<port>/app/rest/swagger.json
endpoint.
エラーレスポンスに含まれるサポートされているロケーターディメンションのリストについては、$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 URL>:<port>/app/rest/buildsUsing basic HTTP authentication (it can be slow with certain authentications, see below). Provide a valid TeamCity username and password with the request. You can force basic auth by including
httpAuth
before the/app/rest
part, e.g.http://<TeamCity URL>:<port>/httpAuth/app/rest/builds
.Using access to the server as a guest user (if enabled) include
guestAuth
before the/app/rest
part, e.g.http://<TeamCity URL>:<port>/guestAuth/app/rest/builds
.If you are checking REST
GET
requests from within a browser, and you are logged in to TeamCity in the browser, you can just use/app/rest
URL, e.g.http://<TeamCity URL>:<port>/app/rest/builds
.
組み込みモジュールを使用しない基本 HTTP 認証を使用すると、認証が遅くなる可能性があります。トークンベースの認証ではなく基本 HTTP 認証を使用する場合は、セッション再利用アプローチ(英語)を適用して、順次要求間で認証を再利用(英語)することを検討してください。
TeamCity ビルド内からリクエストを実行する場合、(アーティファクトのダウンロードなどの)ビルド関連操作の限られたセットに対して、 teamcity.auth.userId/teamcity.auth.password
システムプロパティの値を基本認証情報として使用できます(TeamCity 設定内では、%system.teamcity.auth.userId%
および %system.teamcity.auth.password%
として参照できます)。
ビルド内では、現在のビルド詳細の要求は次のようになります。
スーパーユーザーアクセス
You can use the super user account with REST API: just provide no username and the generated password logged into the server log.
REST API のバージョン
REST API がある TeamCity バージョンから別のバージョンに進化するにつれて、プロトコルに互換性のない変更が生じる可能性があります。
Under the http://<TeamCity URL>:<port>/app/rest/
or http://<TeamCity URL>:<port>/app/rest/latest
URL the latest version is available.
Earlier versions might be available under the http://<TeamCity URL>:<port>/app/rest/<version>
URL. Our general policy is to supply TeamCity with at least one previous version. The REST API protocol version is the TeamCity version where this protocol was first introduced.
The latest legacy version of the protocol is 2018.1: use 2018.1
instead of <version>
to access it. Other bundled versions are: 2017.2
, 2017.1
, 10.0
, 9.1
, 9.0
, 8.1
, 8.0
.
API の重大な変更点は、関連するアップグレードノートセクションに記載されています。返されるオブジェクトへの追加(新しい XML 属性や要素など)は大きな変更とは見なされず、プロトコルバージョンが増加することもありません。また、application.wadl
で Experimental
コメントでマークされたエンドポイントは、将来のバージョンで特別な通知なしに変更される可能性があります。
URL の構造
The general structure of the URL in the TeamCity API is http://<TeamCity URL>:<port>/<authType>/app/rest/<apiVersion>/<restApiPath>?<parameters>
where
TeamCity URL
andport
define the server name and the port used by TeamCity.<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 パラメーターがサポートされています。
ロケーター
多くの場所で、リクエストでフィルタリング / 影響を与えるエンティティを定義するフィルター文字列を指定できます。この文字列表現は、TeamCity RESTAPI のスコープではロケーターと呼ばれます。
ロケーターの形式は次のとおりです。
単一値: 次の記号のないテキスト:
,:-( )
dimension allowing you to filter entities using multiple criteria:
<dimension1>:<value1>,<dimension2>:<value2>,<dimension3>:(<dimension3.1>:<value3.1>,<dimension3.2>:<value3.2>)
Note that nested locators should be enclosed in parentheses. See the 一般的な使用例 section for the most popular locator descriptions. If in doubt what a specific locator supports, send a request with$help
as the locator value. In the response, you will get a textual description of what the locator supports. If a request with invalid locators is sent, the error messages often hint at the error and list the supported locator dimensions as well.
例:
Use
http://<TeamCity URL>:<port>/app/rest/projects
to get the list of projects.Use
http://<TeamCity URL>:<port>/app/rest/projects/<projectsLocator>
, for examplehttp://<TeamCity URL>:<port>/app/rest/projects/id:RESTAPIPlugin
(example ID is used) to get the full data for the REST API Plugin project.Use
http://<TeamCity URL>:<port>/app/rest/buildTypes/id:bt284/builds?locator=<buildLocator>
, for examplehttp://<TeamCity URL>:<port>/app/rest/buildTypes/id:bt284/builds?locator=status:SUCCESS,tag:EAP
(example IDs are used) to get builds.Use
http://<TeamCity URL>:<port>/app/rest/builds/?locator=<buildLocator>
to get builds by build locator.
サポートされている 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 のデータを削除します
ログ関連
You can get details on errors and REST request processing in the logs\teamcity-rest.log
server log.
要求に応えてエラーを受け取り、その理由を調査したい場合は、休息関連サーバーログを調べましょう。
処理された各リクエストの詳細を取得するには、デバッグログをオンにします(たとえば、管理 / 診断ページで Logging Preset を debug-rest
に設定するか、Log4J jetbrains.buildServer.server.rest
カテゴリを変更します)。
CORS のサポート
The TeamCity REST API can be configured to allow クロスオリジン要求 (英語) using the rest.cors.origins
internal property.
To allow requests from a page loaded from a specific domain, add the page address (including the protocol and port, wildcards are not supported) to the comma-separated internal property rest.cors.origins
. For example, rest.cors.origins=http://myinternalwebpage.org.com:8080,https://myinternalwebpage.org.com
.
プリフライト OPTIONS リクエスト(英語)のサポートを有効にするには:
Add the
rest.cors.optionsRequest.allowUnauthorized=true
internal property.再起動 TeamCity サーバー。
リクエストには
/app/rest/latest
URL を使用します。/app/rest
を使用しないでください。httpAuth
プレフィックスを使用しないでください。それでも問題が解決しない場合は、デバッグログを有効にし、関連するメッセージを探します。ない場合は、ブラウザーのトラフィックとメッセージをキャプチャーして、ケースを調査します。
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
フィールドを含める」ことを意味します。フィールド仕様の順序は関係ありません。
例:
現時点では、応答には特に要求されていないフィールド / 要素が含まれることがあります。これは将来のバージョンでは変更される可能性があるため、クライアントが使用するすべてのフィールド / 要素を指定することをお勧めします。
ロードマップとフィードバック
This documentation is a work in progress. If you have any ideas or requests concerning its development, you are welcome to share it via any convenient feedback channel(英語).
Our next plans:
Improve descriptions and add more details
Add usage examples for locator dimensions
Describe more example use cases
Add usage examples for methods