ツイートシェアはてブ LINE Pocket

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

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

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

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

REST APIでスーパーユーザーアカウントを使用できます。ユーザー名と生成されたパスワードをサーバーログに記録しないでください。

REST APIのバージョン

REST APIがあるTeamCityバージョンから別のバージョンに進化するにつれて、プロトコルに互換性のない変更が生じる可能性があります。

http://teamcity:8111/app/rest/ (英語)または http://teamcity:8111/app/rest/latest (英語) URLで、最新バージョンを入手できます。

Earlier versions might be available under the http://teamcity:8111/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の構造

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>)
ネストされたロケーターは括弧で囲む必要があることに注意してください。最も一般的なロケーターの説明については、以下の各エンティティの説明を参照してください。特定のロケーターが何をサポートしているか疑わしい場合は、ロケーター値として「$ 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リクエスト(英語)のサポートを有効にするには：

rest.cors.optionsRequest.allowUnauthorized=true 内部プロパティを追加します。
再開 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

完全および部分的な回答

デフォルトでは、エンティティのリストが要求されると、基本フィールドのみが応答に含まれます。単一のエントリが要求されると、すべてのフィールドが返されます。複雑なフィールド値は、特定のエンティティに応じて、完全形式または基本形式で返すことができます。

It is possible to change the set of fields returned for XML and JSON responses for the majority of requests.This is done by supplying the fields request parameter describing the fields of the top-level entity and sub-entities to return in the response. An example syntax of the parameter is: field,field2(field2_subfield1,field2_subfield1) . This basically means "include field and field2 of the top-level entity and for field2 include field2_subfield1 and field2_subfield1 fields". The order of the fields specification plays no role.

例:

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)
 

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

最終更新日: 2020年7月29日

TeamCity 2020.1ヘルプ