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(英語)

• ゲストユーザーとしてサーバーへのアクセスを使用する場合 （有効な場合）、/app/rest 部分の前に guestAuth が含まれます （例：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バージョンから別のバージョンに進化するにつれて、プロトコルに互換性のない変更が生じる可能性があります。

Under the http://teamcity:8111/app/rest/(英語) or http://teamcity:8111/app/rest/latest(英語) URL the latest version is available.

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パラメータがサポートされています。

ロギング

エラーおよびRESTリクエスト処理の詳細は、logs\teamcity-rest.log サーバーログで取得できます。

要求に応えてエラーを受け取り、その理由を調査したい場合は、休息関連サーバーログを調べましょう。

処理された各リクエストの詳細を取得するには、デバッグログをオンにします（たとえば、管理/診断ページでLogging Presetを debug-rest に設定するか、Log4J jetbrains.buildServer.server.rest カテゴリを変更します）。

CORSのサポート

rest.cors.origins 内部プロパティを使用してクロスオリジン要求(英語)を許可するようにTeamCity REST APIを構成できます。

特定のドメインから読み込まれたページからのリクエストを許可するには、ページアドレス（ プロトコルとポートを含む、ワイルドカードはサポートされていません）をカンマ区切りの内部プロパティ rest.cors.originsに追加します。例： rest.cors.origins=http://myinternalwebpage.org.com:8080,https://myinternalwebpage.org.com。

プリフライトOPTIONSリクエスト(英語)のサポートを有効にするには：

1. rest.cors.optionsRequest.allowUnauthorized=true 内部プロパティを追加します。

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を頻繁にクエリしないで、リクエストされたデータを必要なものだけに制限してください（期限ロケーターを使用し、必要なフィールドを指定します）。あなたの要求から負荷でサーバーの動作を確認してください。要求の処理に時間がかかる場合は、要求を頻繁に繰り返さないようにしてください。

完全および部分的な回答

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

大部分のリクエストでは、XMLおよびJSONレスポンスに対して返される一連のフィールドを変更することができます。これは、レスポンスで返すトップレベルのエンティティとサブエンティティのフィールドを記述するfieldsリクエストパラメータを供給することによって行われます。このパラメーターの構文の例は field,field2(field2_subfield1,field2_subfield1)です。これは基本的に「最上位エンティティの field と field2 を含み、field2 の場合は field2_subfield1 と field2_subfield1 フィールドを含む」という意味です。フィールド指定の順序は関係ありません。

例:

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

プロジェクトとビルド構成/テンプレートリスト

プロジェクト設定

プロジェクトの特徴

プロジェクト機能（課題追跡、バージョン管理設定、カスタムチャート、共有リソース、サードパーティのレポートタブなど）は、"プロジェクト"ノードのエントリとして、専用のリクエストを介して公開されます。

VCSのルート

TeamCity 10.0以降 :

バージョン管理リポジトリのコミットフックでの使用専用の2つのエンドポイントがあります。POST http://teamcity:8111/app/rest/vcs-root-instances/checkingForChangesQueue?locator=<vcsRootInstancesLocator>(英語)

一致したVCSルートインスタンスの変更のチェックをスケジュールし、一致したVCSルートインスタンスのリストを返します。( GET と同じhttp://teamcity:8111/app/rest/vcs-root-instances?locator=<vcsRootInstancesLocator>(英語) ): POST http://teamcity:8111/app/rest/vcs-root-instances/commitHookNotification?locator=<vcsRootInstancesLocator>(英語)

一致したVCSルートインスタンスの変更のチェックをスケジュールし、実行されたアクションに関する平文の判読可能なメッセージ、操作が成功した場合はHTTPレスポンス202を返します。

どちらも「変更の確認」プロセスのためにキューに対して同じアクション（ <locator>によって一致したVCSルートインスタンスを配置）を実行し、それらが生成する応答のみが異なります。

一致したVCSルートインスタンスは ../app/rest/vcs-root-instances?locator=<locator> 要求の場合と同じであり、デフォルトでは最初の100個だけが一致するとそれ以外は無視されることに注意してください。この制限に達した場合は、より少ないインスタンスに一致するように <locator> を微調整するか（推奨）、またはロケーターに ,count:1000 を追加するなどして制限を増やすことを検討してください。

クラウドプロファイル

TeamCity REST APIは、TeamCity UIで提供されるものと同じクラウド統合の詳細を公開します。

ビルド構成とテンプレート設定

ビルドリクエスト

テストと構築の問題

サポートされているロケーター :

• build:(<build locator>) - ビルドでテスト実行

• build:(<build locator>),muted:true - ビルドでミュートされたテストに失敗しました。

• currentlyFailing:true,affectedProject:<project_locator> - 指定されたプロジェクトで現在失敗しているテスト（再帰的）。

• currentlyMuted:true,affectedProject:<project_locator> –指定されたプロジェクトで現在再帰的にミュートされているテスト。プロジェクトのミュート問題タブも参照してください。

サンプル :

サポートされているテストロケータ :

• テスト履歴ページのURLの一部として利用可能なid:<internal test id>

• name:<full test name>

TeamCity 10以降、単一のテスト呼び出し/実行を公開するための実験的サポートがあります。

調査

エージェント

ユーザー

ユーザーに対する POST および PUT 要求の場合、対応するGET要求によって取得された形式でデータをポストします。次の属性/要素のみがサポートされています： name , username , email , password , roles , groups , properties。

ユーザーグループ

ユーザーアクセストークン

監査記録

ユーザ、システムの動作、ビルドタイプなどでレコードをフィルタすることができます（利用可能なすべてのフィルタを確認するには GET http://teamcity:8111/app/rest/audit?locator=$help(英語)を使用してください）。

データバックアップ

型付きパラメータの指定

TeamCity 9.1以降、パラメータの部分的な更新が可能です（現在実験的な状態です）。

• 名前: GET からhttp://teamcity:8111/app/rest/buildTypes/<locator>/parameters/NAME(英語)に返されるのと同じXMLまたはJSON PUT

• タイプ: GET からURL http://teamcity:8111/app/rest/buildTypes/<locator>/parameters/NAME/type(英語)に返されたXMLおよびJSONを受け入れる GET/PUT

• 型のrawValue: プレーンテキストを受け入れる GET/PUT http://teamcity:8111/app/rest/buildTypes/<locator>/parameters/NAME/type/rawValue(英語)

ビルド状況アイコン

ビルドステータスを表すアイコン：

リクエスト例 :

PROJECT_ID IDを持つプロジェクトの場合：

BUILD_CONF_ID IDを持つビルド構成内のすべてのアクティブブランチの場合

要求 /app/rest/builds/aggregated/<build locator> の場合、状況はビルドのリスト app/rest/builds?locator=<build locator>によって計算されます。これにより、単純な img タグを使用して、ビルドステータスアイコンを任意のHTMLページに埋め込むことができます。

BUILD_CONF_ID IDを使用したビルド構成の場合：

最後のビルドの状況

myTag タグでタグ付けされた最後のビルドの状況：

他のすべてのビルドロケーターがサポートされています。

例：次のマークダウンマークアップを使用して、IDが TeamCityPluginsByJetBrains_TeamcityGoogleTagManagerPlugin_Build のビルド構成およびゲスト認証が有効なサーバーhttps://teamcity.jetbrains.com(英語)のGitHubリポジトリのビルドステータスを追加できます。

返されたイメージに「データを取得する権限がありません」というテキスト（）が含まれている場合は、次のいずれかが当てはまることを確認してください。

• サーバーでguestユーザーアクセスが有効になっており、guestユーザーが参照されているビルド構成にアクセスするためのアクセス許可を持っています。

• 参照されているビルド構成には、「状況ウィジェットを有効にする」 オプション ONがあります。

• 同じブラウザでTeamCityサーバーにログインしており、参照しているビルド構成を表示する権限があります。GitHubはサーバー側からイメージを取得するため、これはGitHubページの埋め込みイメージには役に立ちません。

TeamCityライセンス情報の要求

TeamCity 10以降 :

CCTray

CCTray互換のXMLはhttp://teamcity:8111/app/rest/cctray/projects.xml(英語)から入手できます。

認証なし（ゲストユーザーが利用できるビルド構成のみ）：http://teamcity:8111/guestAuth/app/rest/cctray/projects.xml(英語)。

CCTrayフォーマットのXMLには、デフォルトで一時停止ビルド構成は含まれていません。URLは、標準のビルド構成ロケーターではなく locator パラメーターを受け入れます。

新しいプロジェクトを作成する

カールツールを使用する：

ユーザーをシステム管理者にする

1. スーパーユーザートークンを取得します。

2. 要求を出します。

3. curl(英語)コマンドラインツールを取得し、コマンドラインを使用します。

SUPERUSER_TOKEN は、各サーバー起動に固有のスーパーユーザートークンです。 teamcity:8111 - TeamCityサーバーのURL。 USERNAME - システム管理者になるユーザーのユーザー名