TeamCity 2020.2 ヘルプ

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

  • Using 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% として参照できます）。

ビルド内では、現在のビルド詳細の要求は次のようになります。

curl -u "%system.teamcity.auth.userId%:%system.teamcity.auth.password%" "%teamcity.serverUrl%/httpAuth/app/rest/builds/id:%teamcity.build.id%"

スーパーユーザーアクセス

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 and port 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 example http://<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 example http://<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 リクエスト(英語)のサポートを有効にするには：

  1. Add the rest.cors.optionsRequest.allowUnauthorized=true internal property.

  2. 再起動 TeamCity サーバー。

  3. リクエストには /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 フィールドを含める」ことを意味します。フィールド仕様の順序は関係ありません。

例:

http://teamcity.jetbrains.com/app/rest/buildTypes?locator=affectedProject:(id:TeamCityPluginsByJetBrains)&fields=buildType(id,name,project)
http://teamcity.jetbrains.com/app/rest/builds?locator=buildType:(id:bt345),count:10&fields=count,build(number,status,statusText,agent,lastChange,tags,pinned)

現時点では、応答には特に要求されていないフィールド / 要素が含まれることがあります。これは将来のバージョンでは変更される可能性があるため、クライアントが使用するすべてのフィールド / 要素を指定することをお勧めします。

ロードマップとフィードバック

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

RESTAPI クイックスタート