TeamCity 2020.2 ヘルプ

TeamCity RESTAPI について

TeamCity は、外部アプリケーションを統合し、TeamCity サーバーとのスクリプトの相互作用を作成するための RESTAPI を提供します。URL パスを介してリソース(エンティティ)にアクセスできます。REST API を使用するために、外部アプリケーションは TeamCity サーバーに HTTP リクエストを行い、応答を解析します。

このドキュメントは、TeamCity REST API の一般的な説明と、現在の REST API バージョンの状態を反映する自動生成されたセクション ModelsLocators、および Methods で構成されています。この記事では、RESTAPI の原則の概要を説明します。

REST API は、TeamCity 5.0 以降にバンドルされているオープンソースプラグイン(英語)です。

一般的な使用箇所

ブラウザーで 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 (サポートされていないロケーターディメンションを提供)にリクエストを送信すると、エージェントのロケーターを介してエージェントを見つけるためにサポートされているディメンションのリストが表示されます。

  • 返されるエージェントデータ(nameconnectedauthorized)の属性のほとんどは、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% として参照できます)。

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

curl -u "%system.teamcity.auth.userId%:%system.teamcity.auth.password%" "%teamcity.serverUrl%/httpAuth/app/rest/builds/id:%teamcity.build.id%"

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

スーパーユーザーアカウントは 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.22017.110.09.19.08.18.0 です。

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

URL の構造

TeamCity API の URL の一般的な構造は http://<TeamCity Server host>:<port>/<authType>/app/rest/<apiVersion>/<restApiPath>?<parameters> です

where

  • TeamCity URLport は、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 パラメーターを定期的にサポートしています。

ロケーター

多くの場所で、リクエストでフィルタリング / 影響を与えるエンティティを定義するフィルター文字列を指定できます。この文字列表現は、TeamCity RESTAPI のスコープではロケーターと呼ばれます。

ロケーターの形式は次のとおりです。

  • 単一値: ,:-( ) のような記号のない英数字テキスト

  • 複数の基準を使用してエンティティをフィルタリングできるディメンション: <dimension1>:<value1>,<dimension2>:<value2>,<dimension3>:(<dimension3.1>:<value3.1>,<dimension3.2>:<value3.2>)
    ネストされたロケーターは括弧で囲む必要があることに注意してください。最も一般的なロケーターの説明については、一般的な使用例セクションを参照してください。特定のロケーターが何をサポートしているか疑問がある場合は、ロケーター値として $help を使用して要求を送信してください。応答では、ロケーターがサポートする内容のテキストによる説明が表示されます。無効なロケーターを含むリクエストが送信された場合、エラーメッセージはエラーを提案し、サポートされているロケーターのディメンションも一覧表示することがよくあります。

例:

  • http://<TeamCity Server host>:<port>/app/rest/projects を使用して、プロジェクトのリストを取得します。

  • http://<TeamCity Server host>:<port>/app/rest/projects/<projectsLocator>、たとえば http://<TeamCity Server host>:<port>/app/rest/projects/id:RESTAPIPlugin (例 ID が使用されます)を使用して、RESTAPI プラグインプロジェクトの完全なデータを取得します。

  • ビルドを取得するには、http://<TeamCity Server host>:<port>/app/rest/buildTypes/id:bt284/builds?locator=<buildLocator> を使用します(例: http://<TeamCity Server host>:<port>/app/rest/buildTypes/id:bt284/builds?locator=status:SUCCESS,tag:EAP (例 ID が使用されます))。

  • http://<TeamCity Server host>:<port>/app/rest/builds/?locator=<buildLocator> を使用して、ビルドロケーターごとにビルドを取得します。

サポートされている HTTP メソッド

  • GET : 要求されたデータを取得します。例: .../app/rest/entities は通常エンティティのリストを取得し、.../app/rest/entities/<entity locator> は単一のエンティティを取得します

  • POST : 送信されたペイロードからエンティティを作成します。新しいエンティティを作成するには、定期的に単一のエンティティデータ(つまり、GET を介して取得されたもの)を .../app/rest/entities URL に投稿する必要があります。XML を投稿するときは、必ず Content-Type: application/xml HTTP ヘッダーを指定してください。

  • PUT : 送信されたペイロードからデータを更新します。同じ URL への GET リクエストで取得したものと同じデータ形式を受け入れます。 .../app/rest/entities/<entity locator> などの URL の一部のエンティティでサポート

  • DELETE : .../app/rest/entities/<entity locator> などの URL のデータを削除します

ロギング

エラーと 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 レスポンスを返します。ヘッダー:

フォーマット

レスポンスタイプ

HTTP "承認" ヘッダー値

プレーンテキスト

単一値応答

テキスト / プレーン

XML

複素数値応答

application/xml

JSON 複素数値応答 アプリケーション /JSON

完全および部分的な回答

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

ほとんどのリクエストで、XML および JSON 応答に対して返されるフィールドのセットを変更することが可能です。これは、応答で返す最上位エンティティとサブエンティティのフィールドを説明する fields リクエストパラメーターを指定することで行われます。パラメーターの構文の例は、field,field2(field2_subfield1,field2_subfield1) です。これは基本的に、「最上位エンティティの field および field2 を含め、field2 の場合は field2_subfield1 および field2_subfield1 フィールドを含める」ことを意味します。フィールド仕様の順序は関係ありません。

例:

http://teamcity.jetbrains.com/app/rest/buildTypes?locator=affectedProject:(id:TeamCityPluginsByJetBrains)&fields=buildType(id,name,project)
http://teamcity.jetbrains.com/app/rest/builds?locator=buildType:(id:bt345),count:10&fields=count,build(number,status,statusText,agent,lastChange,tags,pinned)

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

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

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

次の計画:

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

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

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

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