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