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

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

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

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

REST API のバージョン

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

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

以前のバージョンは、 http://teamcity:8111/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://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 のサポート

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 レスポンスを返します。ヘッダ：