TeamCity RESTAPI について

一般的な使用箇所

ブラウザーで http://<TeamCity Server host>:<port>/app/rest/server URL を開くと、REST API の操作を開始できます。このページには、API を探索するためのいくつかのポインタがあります。

サポートされている要求の完全なリストとパラメーターの名前は、http://<TeamCity Server host>:<port>/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 Server host>:<port>/app/rest/builds

• 基本 HTTP 認証を使用します（特定の認証では遅くなる可能性があります。以下を参照してください）。リクエストに有効な TeamCity ユーザー名とパスワードを入力してください。 /app/rest 部分の前に httpAuth を含めることで、基本認証を強制できます。 http://<TeamCity Server host>:<port>/httpAuth/app/rest/builds

• ゲストユーザーとしてサーバーへのアクセスを使用する場合（有効な場合）、/app/rest 部分の前に guestAuth を含めます（例: http://<TeamCity Server host>:<port>/guestAuth/app/rest/builds）。

• ブラウザー内から REST GET リクエストをチェックしていて、ブラウザーで TeamCity にログインしている場合は、/app/rest URL を使用できます。 http://<TeamCity Server host>:<port>/app/rest/builds

組み込みモジュールを使用しない基本 HTTP 認証を使用すると、認証が遅くなる可能性があります。トークンベースの認証ではなく基本 HTTP 認証を使用する場合は、セッション再利用アプローチ(英語)を適用して、順次要求間で認証を再利用することを検討してください。

TeamCity ビルド内からリクエストを実行する場合、（アーティファクトのダウンロードなどの）ビルド関連操作の限られたセットに対して、 teamcity.auth.userId/teamcity.auth.password システムプロパティの値を基本認証情報として使用できます（TeamCity 設定内では、%system.teamcity.auth.userId% および %system.teamcity.auth.password% として参照できます）。

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

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

スーパーユーザーアカウントは RESTAPI で使用できます。ユーザー名を入力せず、生成されたパスワードをサーバーログに記録するだけです。

REST API のバージョン

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

http://<TeamCity Server host>:<port>/app/rest/ または http://<TeamCity Server host>:<port>/app/rest/latest URL で、最新バージョンが利用可能です。

以前のバージョンは、http://<TeamCity Server host>:<port>/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://<TeamCity Server host>:<port>/<authType>/app/rest/<apiVersion>/<restApiPath>?<parameters> です

where

• TeamCity URL と port は、TeamCity が使用するサーバー名とポートを定義します。

• <authType> （オプション）は、使用する認証タイプです。これは、一般的な TeamCity 機能です。

• app/rest は TeamCity REST API のルートパスです

• <apiVersion> （オプション）は、REST API の特定のバージョンへの参照です。

• <restApiPath>?<parameters> は、URL の RESTAPI 部分です。
  複数のアイテムを取得する一般的な方法は、.../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 のサポート

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

特定のドメインからロードされたページからの要求を許可するには、ページアドレス（プロトコルとポートを含み、ワイルドカードはサポートされていません）をコンマ区切りの内部プロパティ 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 を頻繁にクエリせず、リクエストされたデータを必要なデータのみに制限してください（適切なロケーターを使用し、必要なフィールドを指定します）。リクエストからの負荷がかかった状態でのサーバーの動作を確認してください。リクエストの処理に時間がかかる場合は、リクエストを頻繁に繰り返さないようにしてください。

応答フォーマット

TeamCity REST API は、HTTP の「Accept」に従って、次の形式で HTTP レスポンスを返します。ヘッダー:

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

このドキュメントは進行中の作業です。その開発に関するアイデアやリクエストがあれば、便利なフィードバックチャネル(英語)を介して共有できます。

次の計画:

• 説明を改善し、詳細を追加する

• ロケーター寸法の使用例を追加

• ユースケースの例をさらに説明する

• メソッドの使用例を追加する