TeamCity RESTAPI について

一般的な使用箇所

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

サポートされている要求の完全なリストとパラメーターの名前は、/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>" /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 を使用できます。/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 バージョンから別のバージョンに進化するにつれて、プロトコルに互換性のない変更が生じる可能性があります。

/app/rest/ または /app/rest/latest URL で、最新バージョンが利用可能です。

以前のバージョンは、/app/rest/<version> URL で利用できる場合があります。当社の一般的なポリシーでは、TeamCity には少なくとも 1 つの以前のバージョンが提供されます。REST API プロトコルバージョンは、このプロトコルが最初に導入された TeamCity バージョンです。
プロトコルの最新のレガシーバージョンは 2018.1 です。アクセスするには、<version> ではなく 2018.1 を使用してください。

API の重大な変更点は、関連するアップグレードノートセクションに記載されています。返されるオブジェクトへの追加（新しい XML 属性や要素など）は大きな変更とは見なされず、プロトコルバージョンが増加することもありません。また、application.wadl で Experimental コメントでマークされたエンドポイントは、将来のバージョンで特別な通知なしに変更される可能性があります。

URL の構造

TeamCity API の URL の一般的な構造は /app/rest/<apiVersion>/<restApiPath>?<parameters> です

where

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

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

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

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

• <restApiPath>?<parameters> は URL の REST API 部分です。
  複数のアイテムを取得する一般的な方法は、.../app/rest/<items> の形式で <restApiPath> を使用することです (例: .../app/rest/builds)。これらの URL は、返されるアイテムをフィルターできる locator パラメーターを通常受け入れます。個々のアイテムは、通常、.../app/rest/<items>/<item_locator> の形式の URL でアドレス指定できます。この URL は常に 1 つのアイテムを返します。<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 レスポンスを返します。

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

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

次の計画:

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

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

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

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