TeamCity 2020.1ヘルプ

REST API

TeamCityは、外部アプリケーションを統合し、TeamCityサーバーとのスクリプト相互作用を作成するためのREST APIを提供します。

このページは3つのメインセクションで構成されています。

  • 一般情報は、REST API認証の原理、リクエストの構造、サポートされるHTTPメソッドについて説明しています。

  • 応答フォーマットは、REST APIを介して受信した応答を解釈する方法を説明しています。

  • REST APIリファレンスは、最も使用されているデータエンティティリクエストをリストします。

リクエストの例も参照してください。

一般情報

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

TeamCityのREST APIでは、URLパスを介してリソース(エンティティ)にアクセスできます。REST APIを使用するには、外部アプリケーションがTeamCityサーバーにHTTPリクエストを送信し、そのレスポンスを解析します。

一般的な使用箇所

このドキュメントは完全なガイドではなく、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(英語)

  • ゲストユーザーとしてサーバーへのアクセスを使用する場合 (有効な場合)、/app/rest 部分の前に guestAuth が含まれます (例: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%として参照できます)。

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

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

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

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

REST APIのバージョン

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

Under the http://teamcity:8111/app/rest/(英語) or http://teamcity:8111/app/rest/latest(英語) URL the latest version is available.

Earlier versions might be available under the http://teamcity:8111/app/rest/<version>(英語) URL. Our general policy is to supply TeamCity with at least one previous version. The REST API protocol version is the TeamCity version where this protocol was first introduced.
The latest legacy version of the protocol is 2018.1: use 2018.1 instead of <version> to access it. Other bundled versions are: 2017.2 , 2017.1 , 10.0 , 9.1 , 9.0 , 8.1 , 8.0 .

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

URLの構造

TeamCity APIのURLの一般的な構造はhttp://teamcityserver:port/<authType>/app/rest/<apiVersion>/<restApiPath>?<parameters>(英語)です

where

  • teamcityserverport は、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パラメータがサポートされています。

ロケーター

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

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

  • 単一値: 次の記号のないテキスト: ,:-( )

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

例:

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

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

  • POST : 送信されたペイロードからエンティティを作成します。新しいエンティティを作成するには、.../app/rest/entities URLに単一のエンティティデータ(つまり、GETを介して取得したもの)を定期的に投稿する必要があります。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のサポート

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

特定のドメインから読み込まれたページからのリクエストを許可するには、ページアドレス( プロトコルとポートを含む、ワイルドカードはサポートされていません)をカンマ区切りの内部プロパティ 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の "Accept" ヘッダー値

プレーン・テキスト

単一値応答

テキスト/プレーン

XML

複素数値応答

application / xml

JSON

複素数値応答

アプリケーション/ JSON

完全および部分的な回答

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

大部分のリクエストでは、XMLおよびJSONレスポンスに対して返される一連のフィールドを変更することができます。これは、レスポンスで返すトップレベルのエンティティとサブエンティティのフィールドを記述するfieldsリクエストパラメータを供給することによって行われます。このパラメーターの構文の例は field,field2(field2_subfield1,field2_subfield1)です。これは基本的に「最上位エンティティの fieldfield2 を含み、field2 の場合は field2_subfield1field2_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)

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

REST APIリファレンス

プロジェクトとビルド構成/テンプレートリスト

プロジェクト一覧

GET http://teamcity:8111/app/rest/projects

プロジェクトの詳細

GET http://teamcity:8111/app/rest/projects/<projectLocator>

ここで、<projectLocator>id:<internal_project_id> または name:<project%20name>です。

ビルド構成のリスト

GET http://teamcity:8111/app/rest/buildTypes

プロジェクトのビルド構成のリスト

GET http://teamcity:8111/app/rest/projects/<projectLocator>buildTypes

概要ページで指定されたユーザーが構成したサブプロジェクトのビルド構成データとその順序でプロジェクトを取得する

GET http://teamcity:8111/app/rest/projects?locator=selectedByUser:current&fields=count,project(id,parentProjectId,projects(count,project(id),$locator(selectedByUser:current)),buildTypes(count,buildType(id),$locator(selectedByUser:current)))

特定のプロジェクトのテンプレートのリスト

GET http://teamcity:8111/app/rest/projects/<projectLocator>/templates

サーバー上のすべてのテンプレートのリスト

GET http://teamcity:8111/app/rest/buildTypes?locator=templateFlag:true

プロジェクト設定

プロジェクトの詳細を取得する

GET http://teamcity:8111/app/rest/projects/<projectLocator>

プロジェクトを削除する

DELETE http://teamcity:8111/app/rest/projects/<projectLocator>

新しい空のプロジェクトを作成する

POST plain text (name) to http://teamcity:8111/app/rest/projects/

プロジェクトを作成(またはコピー)する

POST XML <newProjectDescription name='New Project Name' id='newProjectId' copyAllAssociatedSettings='true'><parentProject locator='id:project1'/><sourceProject locator='id:project2'/></newProjectDescription>

http://teamcity:8111/app/rest/projects

も参照してください。

プロジェクトパラメータを編集する

GET/DELETE/PUT http://teamcity:8111/app/rest/projects/<projectLocator>/parameters/<parameter_name>

プレーンテキスト、XMLおよびJSONを受け入れます。「Accept」ヘッダーに応じて、XML、JSON、プレーンテキストを生成します。

サポートされるリクエスト: .../parameters/<parameter_name>/name および .../parameters/<parameter_name>/value

プロジェクト名/説明/アーカイブされたステータス

GET/PUT http://teamcity:8111/app/rest/projects/<projectLocator>/<field_name>

ここで、<field_name>name , description , archivedの1つです。

テキスト/プレーンを受け入れる/生成します。

プロジェクトの親プロジェクト

GET/PUT XML http://teamcity:8111/app/rest/projects/<projectLocator>/parentProject

プロジェクトの特徴

プロジェクト機能(課題追跡、バージョン管理設定、カスタムチャート、共有リソース、サードパーティのレポートタブなど)は、"プロジェクト"ノードのエントリとして、専用のリクエストを介して公開されます。

プロジェクト機能のリスト

http://teamcity:8111/app/rest/projects/<projectLocator>/projectFeatures

機能をフィルタするには、?locator=<projectFeaturesLocator> をURLに追加します。たとえば、GitHubタイプのすべての課題追跡機能を見つけるには、ロケーター type:IssueTracker,property(name:type,value:GithubIssues)を使用します。

フィーチャーを作成する

POST/projects/<projectLocator>/projectFeatures

フィーチャーの編集

GET/DELETE/PUT http://teamcity:8111/app/rest/projects/<projectLocator>/projectFeatures/<featureId>

VCSのルート

すべてのVCSルートを一覧表示する

GET http://teamcity:8111/app/rest/vcs-roots

一致したVCSルートのみをリストするには、locator=<vcsRootLocator> パラメータを追加します。

VCSルートの詳細を取得/ VCSルートを削除

GET/DELETE http://teamcity:8111/app/rest/vcs-roots/<vcsRootLocator>

ここで、<vcsRootLocator>id:<internal VCS root id> または他のVCSルートロケータです。

新しいVCSルートを作成する

POST VCS root XML (VCSルート詳細のGETリクエストで取得したものと同様)からhttp://teamcity:8111/app/rest/vcs-roots(英語)へ。

また支えられる:

ここで、<field_name>id , name , project です(プロジェクトロケーターを project にポストして、VCSルートを特定のプロジェクトに関連付けます)。

VCSルートインスタンスのリスト*

GET http://teamcity:8111/app/rest/vcs-root-instances?locator=<vcsRootInstancesLocator>

TeamCity 10.0以降 :

バージョン管理リポジトリのコミットフックでの使用専用の2つのエンドポイントがあります。POST http://teamcity:8111/app/rest/vcs-root-instances/checkingForChangesQueue?locator=<vcsRootInstancesLocator>(英語)

一致したVCSルートインスタンスの変更のチェックをスケジュールし、一致したVCSルートインスタンスのリストを返します。( GET と同じhttp://teamcity:8111/app/rest/vcs-root-instances?locator=<vcsRootInstancesLocator>(英語) ): POST http://teamcity:8111/app/rest/vcs-root-instances/commitHookNotification?locator=<vcsRootInstancesLocator>(英語)

一致したVCSルートインスタンスの変更のチェックをスケジュールし、実行されたアクションに関する平文の判読可能なメッセージ、操作が成功した場合はHTTPレスポンス202を返します。

どちらも「変更の確認」プロセスのためにキューに対して同じアクション( <locator>によって一致したVCSルートインスタンスを配置)を実行し、それらが生成する応答のみが異なります。

一致したVCSルートインスタンスは ../app/rest/vcs-root-instances?locator=<locator> 要求の場合と同じであり、デフォルトでは最初の100個だけが一致するとそれ以外は無視されることに注意してください。この制限に達した場合は、より少ないインスタンスに一致するように <locator> を微調整するか(推奨)、またはロケーターに ,count:1000 を追加するなどして制限を増やすことを検討してください。

VCSルートインスタンスロケータ

上から <vcsRootInstancesLocator> をサポートしているものがあります。

  • type:<VCS root type> –指定されたバージョン管理のVCSルートインスタンス(たとえば、jetbrains.git , mercurial , svn)。

  • vcsRoot:(<vcsRootLocator>) - <vcsRootLocator>によって一致したVCSルートに対応するVCSルートインスタンス。

  • buildType:(<buildTypeLocator>) - 一致するビルド構成にアタッチされたVCSルートインスタンス。

  • property:(name:<name>,value:<value>,matchType:<matching>) - 名前 <name> のプロパティと値 <value>による値一致条件 <matchType> (たとえば、equals、contains)を持つVCSルートインスタンス。

クラウドプロファイル

TeamCity REST APIは、TeamCity UIで提供されるものと同じクラウド統合の詳細を公開します。

すべてのクラウドプロファイルを一覧表示する

GET http://teamcity:8111/app/rest/cloud/profiles

すべてのクラウドイメージを一覧表示します

GET http://teamcity:8111/app/rest/cloud/images

すべてのクラウドインスタンスを一覧表示する

GET http://teamcity:8111/app/rest/cloud/instances

新しいインスタンスを開始する

POST http://teamcity:8111/app/rest/cloud/instances

The posted XML/JSON contents are the same as received via GET for one instance.

実行中のインスタンスを停止する

DELETE http://teamcity:8111/app/rest/cloud/instances/<instanceLocator>

ビルド構成とテンプレート設定

ビルド構成/テンプレートの詳細を取得する

GET http://teamcity:8111/app/rest/buildTypes/<buildConfigurationLocator>

ビルド構成ロケーターの詳細を参照してください。

TeamCityでの設定編集のサポートなど、トランザクションがないため、REST APIを介して変更されたすべての設定は一度に考慮されます。これにより、半構成のビルドがトリガされるなどの課題が発生する可能性があります。この点があなたのケースにとって重要であるなら、その設定を変更する前にビルド設定を一時停止することを確認してください。

複数のビルド構成の集計ステータスを取得するには、ビルド状況アイコンセクションを参照してください。

一時停止したビルド構成状態を取得/設定する

GET/PUT http://teamcity:8111/app/rest/buildTypes/<buildTypeLocator>/paused

true または false テキストをtext / plainとして配置します。

ビルド構成設定

GET/DELETE/PUT http://teamcity:8111/app/rest/buildTypes/<buildTypeLocator>/settings/<setting_name>

ビルド構成パラメーター

GET/DELETE/PUT http://teamcity:8111/app/rest/buildTypes/<buildTypeLocator>/parameters/<parameter_name>

Accept ヘッダーに応じてXML、JSON、プレーンテキストを生成し、プレーンテキスト、XML、JSONを受け入れます。 .../parameters/<parameter_name>/name および .../parameters/<parameter_name>/value リクエストもサポートされています。

ビルド構成手順

GET/DELETE http://teamcity:8111/app/rest/buildTypes/<buildTypeLocator>/steps/<step_id>

ビルド構成ステップの作成

POST http://teamcity:8111/app/rest/buildTypes/<buildTypeLocator>/steps

ポストされたXML / JSONは、パスワードなどの安全な設定を除いて、.../steps/<step_id> へのGETリクエストで取得したものと同じです。これらは応答に含まれず、POSTする前に提供する必要があります。

機能、トリガー、エージェントの要件、アーティファクト、およびスナップショットの依存関係は、それぞれのURLを使用した手順(上記)と同じパターンに従います

http://teamcity:8111/app/rest/buildTypes/<buildTypeLocator>/features/<id> http://teamcity:8111/app/rest/buildTypes/<buildTypeLocator>/triggers/<id> http://teamcity:8111/app/rest/buildTypes/<buildTypeLocator>/agent-requirements/ http://teamcity:8111/app/rest/buildTypes/<buildTypeLocator>/artifact-dependencies/<id> http://teamcity:8111/app/rest/buildTypes/<buildTypeLocator>/snapshot-dependencies/<id>

TeamCity 10以降、成果物の依存関係およびエージェントの要件を無効化/有効化することが可能です。

アーティファクト依存関係を無効/有効にする

PUT http://teamcity:8111/app/rest/buildTypes/<buildTypeLocator>/artifact-dependencies/<id>/disabled

true または false テキストをtext / plainとして配置します。

ビルドVCSルート

GET/DELETE http://teamcity:8111/app/rest/buildTypes/<buildTypeLocator>/vcs-root-entries/<id>

VCSルートをビルド構成にアタッチする

POST http://teamcity:8111/app/rest/buildTypes/<buildTypeLocator>/vcs-root-entries

ポストされるXML / JSONは、パスワードのような安全な設定を除いて、http://teamcity:8111/app/rest/buildTypes/<buildTypeLocator>/vcs-root-entries/<id>(英語)へのGETリクエストによって取得されるものと同じです。これらはレスポンスに含まれず、POSTを返す前に提供されるべきです。

すべての設定で新しいビルド構成を作成する

POST http://teamcity:8111/app/rest/buildTypes

投稿されたXML / JSONは、GETリクエストによって取得されたものと同じです。 /app/rest/project/XXX/buildTypes はまだ以前のバージョンの表記法を使用しており、別のエンティティを受け入れます。

新しい空のビルド構成を作成する

POST プレーンテキスト(名前)からhttp://teamcity:8111/app/rest/projects/<projectLocator>/buildTypes(英語)へ。

ビルド構成をコピーする

POST XML <newBuildTypeDescription name='Conf Name' sourceBuildTypeLocator='id:XXX' copyAllAssociatedSettings='true' shareVCSRoots='false'/>

http://teamcity:8111/app/rest/projects/<projectLocator>/buildTypes(英語)

テンプレートとの間でビルド構成を読み取り、接続解除、接続する

TeamCity 2017.2以降 :

GET/DELETE/POST/PUT http://teamcity:8111/app/rest/buildTypes/<buildTypeLocator>/templates

TeamCity 2017.2の前 :

GET/DELETE/POST/PUT http://teamcity:8111/app/rest/buildTypes/<buildTypeLocator>/template

Putは、text/plain Content-Typeを持つテンプレートロケーターを受け入れます。

ビルド番号カウンターを設定する

curl -v --basic --user <username>:<password> --request PUT http://<teamcity.url>/app/rest/buildTypes/<buildTypeLocator>/settings/buildNumberCounter --data <new number> --header "Content-Type: text/plain"

ビルド番号の形式を設定する

curl -v --basic --user <username>:<password> --request PUT http://<teamcity.url>/app/rest/buildTypes/<buildTypeLocator>/settings/buildNumberPattern --data <new format> --header "Content-Type: text/plain"

ビルド構成ロケーター

<buildTypeLocator> に最も頻繁に使用される値は id:<buildConfigurationOrTemplate_id>name:<Build%20Configuration%20name>です。

TeamCity 2017.2以降実験 タイプのロケーターは、値 regular , compositeまたは deploymentのいずれかでサポートされます。

他にサポートされている寸法は以下のとおりです(これらは実験的な状態です)。

  • internalId - ビルド構成の内部ID

  • project - ビルド構成を単一のプロジェクトに属するものに限定する <projectLocator>

  • affectedProject - 単一プロジェクト下のビルド構成を(再帰的に)制限する <projectLocator>

  • template - テンプレートを使用したビルド構成のみをリストするテンプレートの <buildTypeLocator>

  • templateFlag - テンプレートのみまたは非テンプレートのみを取得するためのブール値。

  • paused - 一時停止/一時停止していないビルド構成をフィルタリングするためのブール値。

ビルドリクエスト

ビルドの一覧表示

GET http://teamcity:8111/app/rest/builds/?locator=<buildLocator>

特定のビルドの詳細を取得する

GET http://teamcity:8111/app/rest/builds/<buildLocator>

ビルドを削除するために DELETE もサポートします。

各ビルド構成で最後に完了したビルドのステータスを含むプロジェクトのビルド構成のリストを取得する

GET http://teamcity:8111/app/rest/buildTypes?locator=affectedProject:(id:ProjectId)&fields=buildType(id,name,builds($locator(running:false,canceled:false,count:1),build(number,status,statusText)))

ビルドロケーター

ビルド関連のリクエストでロケーターを使用すると、ビルド関連のリクエストで返されるビルドをフィルタリングできます。REST APIのスコープでは、ビルドロケーターと呼ばれます。

一部の要求では、デフォルトのフィルタリングが適用されます。ただし、これらのタイプの場合を除いて、「通常の」ビルド(キャンセルされず、開始に失敗せず、個人用ではない)、デフォルトのブランチのみが返されます。ビルドはロケータを介して明確に要求されます。このデフォルトのフィルタを無効にしてすべてのビルドを処理するには、defaultFilter:false ディメンションをビルドロケータに追加します。デフォルトのフィルタリングは、指定されたロケーターの寸法によって異なります。例: agent または user 寸法が存在する場合、個人用、キャンセル済み、およびビルドの開始に失敗したことが結果に含まれます。

サポートされているビルドロケータの例:

  • id:<internal build id> - 特定のビルドを参照する必要があるときは、内部ビルドIDを使用してください。

  • number:<build number> - ビルド構成がすでに指定されている場合、ビルド番号でビルドを検索します。

  • <dimension1>:<value1>,<dimension2>:<value2> - 複数の基準でビルドを見つけます。

サポートされているビルドロケーターの寸法のリスト:

  • project:<project locator> - リストを指定されたプロジェクトのビルド(プロジェクトの直下にある任意のビルドタイプに属する)に限定します。

  • affectedProject:<project locator> - リストを指定されたプロジェクトのビルドに限定する (プロジェクトで直接的または間接的に任意のビルドタイプに属する)

  • buildType:(<buildTypeLocator>),defaultFilter:false - 指定されたビルド構成のすべてのビルド

  • tag:<tag>TeamCity 10以降、タグ付きビルドを取得します。 tag:<tag1> , tag:<tag2>などのタグのリストが指定されている場合、指定されたすべてのタグを含むビルドのみが返されます。互換性のために、レガシー tags:<tags> ロケーターがサポートされています。

  • status:<SUCCESS/FAILURE/UNKNOWN> - リストは指定された状況でのみ作成されます。

  • user:(<userLocator>) - 制限は、指定されたユーザーによって引き起こされたものだけに構築されます。

  • personal:<true/false/any> - 個人旗による建造制限。デフォルトでは、個人用ビルドは含まれていません。

  • canceled:<true/false/any> - 制限は取り消されたフラグによって構築されます。デフォルトでは、キャンセルされたビルドは含まれません。

  • failedToStart:<true/false/any> - 開始に失敗したフラグによる制限の構築。デフォルトでは、キャンセルされたビルドは含まれません。

  • state:<queued/running/finished> - 制限は指定された状態で構築されます。

  • running:<true/false/any> - 実行フラグによるビルド制限。デフォルトでは、実行中のビルドは含まれていません。

  • state:running,hanging:true - ぶら下がっているビルドを取得します(TeamCity 10.0以降)。

  • pinned:<true/false/any> - 制限はピン留めされたフラグによって構築されます。

  • branch:<branch locator> - ブランチによるビルドを制限します。 <branch locator> は、UIに表示されるブランチ名、または (name:<name>,default:<true/false/any>,unspecified:<true/false/any>,branched:<true/false/any>です。デフォルトでは、デフォルトのブランチからのビルドのみが返されます。すべてのビルドを取得するには、次の locator: branch:default:anyを追加してください。全体のパスは /app/rest/builds/?locator=buildType:One_Git,branch:default:anyのようになります。

  • revision:<REVISION> - リビジョンごとにビルドを検索します。たとえば、指定されたビルド構成のリビジョン /app/rest/builds?locator=revision:(REVISION),buildType:(id:BUILD_TYPE_ID)のすべてのビルドを検索します。より多くの情報を参照してください以下を。

  • agentName:<name> - ビルドのみを返すエージェント名が、指定された名前のエージェントで実行されました。

  • sinceBuild:(<buildLocator>) - 指定されたビルドの後のものだけにビルドのリストを制限する

  • sinceDate:<date> - 指定された日付以降に開始されたものだけにビルドのリストを制限します。日付は、REST APIによって返される日付と同じ形式でなければなりません(たとえば、20130305T170030+0400)。

  • queuedDate/startDate/finishDate:(date:<time-date>,build:<build locator>,condition:<before/after>) - ビルドロケーターで指定された時間に基づいてビルドをフィルター処理します。たとえば、11月以降に終了したビルドは23, 2017, 20:34:46、GMT + 1はタイムゾーン使用: finishDate:(date:20171123T203446%2B0100,condition:after)

  • count:<number> - 指定された数のビルドだけを提供します。

  • start:<number> - 指定された位置から始まるリストからビルドをリストします(ゼロから始まる)。

  • lookupLimit:<number> - 処理を最新のN個のビルドのみに制限します(デフォルトは5000です。最新のN個のビルドがいずれもビルドロケータの他の指定基準に一致しない場合、単一ビルド要求に対して404応答、複数ビルド要求に対して空のコレクションが返されます。上記のセクションに注意してください。

キュービルド

ビルドキューを取得する

GET http://teamcity:8111/app/rest/buildQueue

サポートされているロケータ

  • project:<locator>
  • buildType:<locator>

キューに入れられたビルドの詳細を取得する

GET http://teamcity:8111/app/rest/buildQueue/id:XXX

スナップショット依存関係を持つキュービルドの場合、リビジョンが修正されていれば、キュービルドノードの revisions 要素でそのリビジョンを利用できます(スナップショット依存関係のない通常のビルドではそうではありません)。

キューに入れられたビルドの互換性のあるエージェントを入手する (「エージェントなし」で実行するビルドに役立ちます)

GET http://teamcity:8111/app/rest/buildQueue/id:XXX/compatibleAgents

サンプル :

プロジェクトごとにキューに入れられたビルドを一覧表示する

GET http://teamcity:8111/app/rest/buildQueue?locator=project:<locator>

ビルド構成ごとにキューに入れられたビルドを一覧表示する

GET http://teamcity:8111/app/rest/buildQueue?locator=buildType:<locator>

ビルドを開始する

ビルドを開始するには、"build" ノード(下記参照)をコンテンツに含めて POST 要求をhttp://teamcity:8111/app/rest/buildQueue(英語)に送信します - キューに入れられたビルドまたは完成したビルドの詳細と同じノードです。キューに入れられたビルドの詳細が返されます。

ビルドが開始されると、キューに入れられたビルド(/app/rest/buildQueue/XXX)への要求は、実行中または終了したビルドデータを返します。このようにして、ビルドが state="finished" 属性を持つまで、ビルドのトリガー時に返されるビルド詳細の href 属性を使用してビルドの詳細を照会することで、ビルドの完成度を監視できます。

ビルドノードの例

ビルド構成の基本ビルド

<build> <buildType id="buildConfID"/> </build>

個人用としてマークされた固定エージェント、コメント、およびカスタムパラメータでブランチを構築します。

<build personal="true" branchName="logicBuildBranch"> <buildType id="buildConfID"/> <agent id="3"/> <comment><text>build triggering comment</text></comment> <properties> <property name="env.myEnv" value="bbb"/> </properties> </build>

エージェントプールへのキュービルドビルド割り当て

<build>... <agent> <pool id="N"/> </agent> ... </build>

与えられたリビジョンの変更に基づいてビルドし、ビルド前にすべての依存関係とクリーンなソースを強制的に再ビルドし、トリガー時にビルドキュートップに移動しました。(変更は既にTeamCityに認識されている必要があることに注意してください(ビルド構成のUIに表示されます。"lastChanges" 要素の詳細)。

<build> <triggeringOptions cleanSources="true" rebuildAllDependencies="true" queueAtTop="true"/> <buildType id="buildConfID"/> <lastChanges> <change locator="version:a286767fc1154b0c2b93d5728dd5bbcdefdfaca,buildType:(id:buildConfID)"/> </lastChanges> </build>

ビルドをトリガーするためのコマンドラインの例:

curl -v -u user:password http://teamcity.server.url:8111/app/rest/buildQueue --request POST --header "Content-Type:application/xml" --data-binary @build.xml

ビルド・タグ

タグを取得する

GET http://teamcity:8111/app/rest/builds/<buildLocator>/tags/

タグを置き換える

PUT http://teamcity:8111/app/rest/builds/<buildLocator>/tags/

GETによって返されるものと同じXMLまたはJSONを入力します。

タグの追加

POST http://teamcity:8111/app/rest/builds/<buildLocator>/tags/

GETによって返されるのと同じXMLまたはJSON、またはプレーンテキストのタグ名を投稿します。ここの <buildLocator> は、単一のビルドのみと一致する必要があります。

ビルド・ピン留め

現在のピンの状態を取得する

GET http://teamcity:8111/app/rest/builds/<buildLocator>/pin/

ビルドを固定する

PUT http://teamcity:8111/app/rest/builds/<buildLocator>/pin/

リクエストデータ内のテキストは、アクションのコメントとして追加されます。

ビルドの固定を解除する

DELETE http://teamcity:8111/app/rest/builds/<buildLocator>/pin/

リクエストデータのテキストは、アクションのコメントとして追加されます。ここの <buildLocator> は、単一のビルドのみと一致する必要があります。

ビルドキャンセル/停止

実行中または待機中のビルドをキャンセルする

<buildCancelRequest comment='CommentText' readdIntoQueue='false'/> アイテムを実行中またはキュー内のビルドのURLにPOSTします。例:

curl -v -u user:password --request POST "http://teamcity:8111/app/rest/buildQueue/<buildLocator>" --data "<buildCancelRequest comment='' readdIntoQueue='false' />" --header "Content-Type: application/xml"

実行中のビルドを停止し、キューに再度追加する

<buildCancelRequest comment='CommentText' readdIntoQueue='true' /> アイテムを実行中のビルドのURLにPOSTします。例:

curl -v -u user:password --request POST "http://teamcity:8111/app/rest/builds/<buildLocator>" --data "<buildCancelRequest comment='' readdIntoQueue='true' />" --header "Content-Type: application/xml"

ビルドアイテムの canceledInfo 要素を参照してください

GET http://teamcity:8111/app/rest/builds/<buildLocator>から入手できます。

ビルド成果物

<build_locator> によって決定されたビルドのビルドアーティファクトファイルのコンテンツを返す

GET http://teamcity:8111/app/rest/builds/<build_locator>/artifacts/content/<path>

<path> は、ビルドのアーティファクトのルートに対して空にすることも、ビルドのアーティファクト内のパスにすることもできます。パスは、dir/path/archive.zip!/path_within_archiveなどのアーカイブコンテンツにまたがることができます。

  • Media-Type:application / octet-stream、またはより具体的なメディアタイプ(アーティファクトファイル拡張子から決定されます)。

  • 考えられるエラー:指定されたパスがディレクトリを参照している場合は400。

ビルドアーティファクトに関する情報を返す

GET http://teamcity:8111/app/rest/builds/<build_locator>/artifacts/metadata/<path>
  • メディアタイプ:application / xmlまたはapplication / json。

ディレクトリとアーカイブのアーティファクトの子のリストを返します

GET http://teamcity:8111/app/rest/builds/<build_locator>/artifacts/children/<path>
  • メディアタイプ:application / xmlまたはapplication / json。

  • 考えられるエラー:アーティファクトがディレクトリでもアーカイブでもない場合は400。

指定されたパスにあるアーティファクトのリストを含むアーカイブを返します

GET http://teamcity:8111/app/rest/builds/<build_locator>/artifacts/archived/<path>?locator=pattern:<wildcard>

オプションの locator パラメータにファイル <wildcard> を指定して、ワイルドカードに一致するファイルのみにファイルを制限できます。 <artifact relative name> は、アーカイブ名の後に !/ 区切り文字を使用して、アーカイブのファイルの参照をサポートします。

  • メディアタイプ:application / zip

  • 考えられるエラー:アーティファクトがディレクトリでもアーカイブでもない場合は400。

サンプル :

GET http://teamcity:8111/app/rest/builds/id:100/artifacts/children/my-great-tool-0.1.jar!/META-INF GET http://teamcity:8111/app/rest/builds/buildType:(id:Build_Intallers),status:SUCCESS/artifacts/metadata/my-great-tool-0.1.jar!/META-INF/MANIFEST.MF GET http://teamcity:8111/app/rest/builds/buildType:(id:Build_Intallers),number:16.7.0.2/artifacts/metadata/my-great-tool-0.1.jar!/lib/commons-logging-1.1.1.jar!/META-INF/MANIFEST.MF GET http://teamcity:8111/app/rest/builds/buildType:(id:Build_Intallers),tag:release/artifacts/content/my-great-tool-0.1.jar!/lib/commons-logging-1.1.1.jar!/META-INF/MANIFEST.MF

認証

TeamCityビルド内からアーティファクトをダウンロードする場合は、ダウンロードアーティファクト要求の認証情報として teamcity.auth.userId/teamcity.auth.password システムプロパティの値を使用することを検討してください。このようにTeamCityは、あるビルドが別のアーティファクトを使用したことを記録してビルドの依存関係タブに表示します。

その他のビルド要求

変更

<changes> は、TeamCity UIのビルドの変更に表示されるのと同じ方法で変更を表すことを目的としています。ほとんどの場合、これらは現在のビルドと以前のビルド間のコミットです。 <changes> タグは、デフォルトではビルドに含まれていません。href属性のみを持っています。hrefで指定されたリクエストを実行すると、必要な変更が行われます。

ビルドに含まれるすべての変更のリストを取得する

GET http://teamcity:8111/app/rest/changes?locator=build:(id:<buildId>)

個別の変更の詳細を取得する

GET http://teamcity:8111/app/rest/changes/id:changeId

変更されたファイルアクションに関する情報を取得する

ファイルのノードには、変更されたファイルがリストされます。変更されたファイルアクションに関する情報は、added , edited , removed , copiedまたは unchangedとしてリストされているファイルの changeType 属性を介して報告されます。

すべての変更をロケーターでフィルター

GET http://teamcity:8111/app/rest/changes?locator=<changeLocator>

プロジェクトのすべての変更を取得する

GET http://teamcity:8111/app/rest/changes?locator=project:projectId

IDで識別される特定の変更以降のビルド構成のすべての変更を取得する

http://teamcity:8111/app/rest/changes?locator=buildType:(id:buildConfigurationId),sinceChange:(id:changeId)

ビルド構成の保留中の変更を取得する

http://teamcity:8111/app/rest/changes?locator=buildType:(id:BUILD_CONF_ID),pending:true

<lastChanges> タグには、ビルドに含まれる最後のコミットに関する情報が含まれています。ビルドをトリガーする場合、そのネストされた <change> 要素には、ビルドのトリガーに使用する変更を指定する locator フィールドを含めることができます。

リビジョン

<revisions> タグは、TeamCity UIのビルドの変更タブのリビジョンテーブルと同じです。エージェント上のビルドによってチェックアウトされる、このビルドに関連付けられているすべてのVCSリポジトリのリビジョンを一覧表示します。改訂は、TeamCityに知られている変更に対応する場合と対応しない場合があります。例:新しく作成されたビルド設定とVCSルートの場合、リビジョンに対応する変更はありません。

指定されたリビジョンのすべてのビルドを取得する

GET http://teamcity:8111/app/rest/builds?locator=revision(version:XXXX)

TeamCity 10以降<versionedSettingsRevision> は、ビルドのバージョン対応設定の改訂を表すために追加されます。

スナップショットの依存関係

特定のビルドの全体のビルドチェーン(すべてのスナップショット依存関係にリンクされたビルド)を取得する

GET http://teamcity:8111/app/rest/builds?locator=snapshotDependency:(to:(id:XXXX),includeInitial:true),defaultFilter:false

これにより、ID XXXXのビルドのすべてのスナップショット依存関係ビルドが再帰的に取得されます。

特定のビルドのすべてのスナップショット依存ビルドを見つける

GET http://teamcity:8111/app/rest/builds?locator=snapshotDependency:(to:(id:XXXX),includeInitial:true),defaultFilter:false

成果物の依存関係

TeamCity 10.0.3以降、実験的な機能があります:

指定されたIDのビルドからアーティファクトをダウンロードしたすべてのビルドを取得する (TeamCity Web UIで提供されるアーティファクト)

GET http://teamcity:8111/app/rest/builds?locator=artifactDependency:(from:(id:<build ID>),recursive:false)

指定されたIDのビルドによってアーティファクトがダウンロードされたすべてのビルドを取得する (TeamCity Web UIでダウンロードされたアーティファクト)

GET http://teamcity:8111/app/rest/builds?locator=artifactDependency:(to:(id:<build ID>),recursive:false)

ビルドパラメータ

ビルドのパラメーターを取得する

GET http://teamcity:8111/app/rest/builds/id:<build_id>/resulting-properties

フィールドをビルド

単一のビルドのフィールドを取得する

GET http://teamcity:8111/app/rest/builds/<buildLocator>/<field_name>

これは、<field_name>number , status , id , branchNameの1つであるtext / plainと他のビルドのbean属性を受け入れ/生成します。

統計

1つのビルドの統計を取得する

GET http://teamcity:8111/app/rest/builds/<buildLocator>/statistics/

標準/バンドルされた統計値のみがリストされます。カスタムチャートも参照してください。

単一のビルド統計値を取得する

GET http://teamcity:8111/app/rest/builds/<buildLocator>/statistics/<value_name>

ビルドのリストの統計を取得する

GET http://teamcity:8111/app/rest/builds?locator=BUILDS_LOCATOR&fields=build(id,number,status,buildType(id,name,projectName),statistics(property(name,value)))

ビルドログ

RESTリクエストによるビルドログのダウンロードはサポートされていませんが、ここに記載されているログファイルをダウンロードする方法があります。

テストと構築の問題

ビルドの問題を一覧表示する

GET http://teamcity:8111/app/rest/problemOccurrences?locator=build:(BUILD_LOCATOR)

テストの一覧表示

GET http://teamcity:8111/app/rest/testOccurrences?locator=<locator dimension>:<value>

サポートされているロケーター :

  • build:(<build locator>) - ビルドでテスト実行

  • build:(<build locator>),muted:true - ビルドでミュートされたテストに失敗しました。

  • currentlyFailing:true,affectedProject:<project_locator> - 指定されたプロジェクトで現在失敗しているテスト(再帰的)。

  • currentlyMuted:true,affectedProject:<project_locator> –指定されたプロジェクトで現在再帰的にミュートされているテスト。プロジェクトのミュート問題タブも参照してください。

サンプル :

すべてのビルドのテストをリストする

GET http://teamcity:8111/app/rest/testOccurrences?locator=build:<buildLocator>

個別のテスト履歴を取得する

GET http://teamcity:8111/app/rest/testOccurrences?locator=test:<testLocator>

ビルドの実行時にミュートされたビルドのテストを一覧表示します

GET http://teamcity:8111/app/rest/testOccurrences?locator=build:(id:XXX),muted:true

現在ミュートされているテストのリスト (失敗以来ミュート)

GET http://teamcity:8111/app/rest/testOccurrences?locator=build:(id:XXX),currentlyMuted:true

サポートされているテストロケータ :

  • テスト履歴ページのURLの一部として利用可能なid:<internal test id>

  • name:<full test name>

TeamCity 10以降、単一のテスト呼び出し/実行を公開するための実験的サポートがあります。

テストの呼び出しを取得する

GET http://teamcity:8111/app/rest/testOccurrences?locator=build:(id:XXX),test:(id:XXX)&fields=$long,testOccurrence($short,invocations($long))

すべての呼び出しがフラット化されたすべてのテスト実行をリストする

GET http://teamcity:8111/app/rest/testOccurrences?locator=build:(id:XXX),test:(id:XXX),expandInvocations:true

ミュートテストとビルド問題

TeamCity 2017.2以降

ミュートされたすべてのテストを一覧表示し、問題を構築する

GET http://teamcity:8111/app/rest/mutes

テストのミュートを解除するか、問題を構築する

DELETE http://teamcity:81111/app/rest/mutes/id:XXXX

テストをミュートまたは問題を構築する

POST http://teamcity:8111/app/rest/mutes

GETによって返されるものと同じXMLまたはJSONを使用します。

調査

ルートプロジェクトとそのサブプロジェクトの調査を一覧表示する

GET http://teamcity:8111/app/rest/investigations

サポートされているロケータ

  • test: (id:TEST_NAME_ID)
  • test: (name:FULL_TEST_NAME)
  • assignee: (<user_locator>)
  • buildType:(id:XXXX)

特定のテストの調査を取得する

http://teamcity:8111/app/rest/investigations?locator=test:(id:TEST_NAME_ID) http://teamcity:8111/app/rest/investigations?locator=test:(name:FULL_TEST_NAME)

ユーザーに割り当てられた調査を取得する

GET http://teamcity:8111/app/rest/investigations?locator=assignee:(<user locator>)

ビルド構成の調査を取得する

GET http://teamcity:8111/app/rest/investigations?locator=buildType:(id:XXXX)

調査を割り当て/置換するには

単一の調査:

POST/PUT からhttp://teamcity:8111/app/rest/investigations(英語)

複数の調査の実験的サポートPOST/PUT からhttp://teamcity:8111/app/rest/investigations/multiple(英語)(調査のリストを受け入れます)。

GETによって返されるものと同じXMLまたはJSONを使用します。

エージェント

エージェントの一覧表示 (デフォルトでは許可されたエージェントのみが含まれます)

GET http://teamcity:8111/app/rest/agents

接続されているすべての承認済みエージェントをリストする

GET http://teamcity:8111/app/rest/agents?locator=connected:true,authorized:true

許可されたすべてのエージェントをリストする

GET http://teamcity:8111/app/rest/agents?locator=authorized:true

有効な承認済みエージェントをすべて一覧表示します

GET http://teamcity:8111/app/rest/agents?locator=enabled:true,authorized:true

すべてのエージェントをリストする (無許可を含む)

GET http://teamcity:8111/app/rest/agents?locator=authorized:any

リクエストはデフォルトのフィルタリングを使用します(指定されたロケーターディメンションに応じて、他はデフォルトの暗黙の値を持つことができます)。このフィルタリングを無効にするには、ロケーターに ,defaultFilter:false を追加します。

エージェントを有効/無効にする

PUT http://teamcity:8111/app/rest/agents/<agentLocator>/enabled

true または false テキストをtext / plainとして配置します。例(英語)を参照してください。

エージェントの承認/承認解除

PUT http://teamcity:8111/app/rest/agents/<agentLocator>/authorized

true または false テキストをtext / plainとして配置します。

エージェントの単一フィールドを取得/配置する

GET/PUT http://teamcity:8111/app/rest/agents/<agentLocator>/<field_name>

ビルドエージェントを削除する

DELETE http://teamcity:8111/app/rest/agents/<agentLocator>

エージェントを有効化/無効化および許可/許可解除するときにコメントを追加する

エージェント使用可能/許可済みデータは、enabledInfo および authorizedInfo ノードに公開されています。

<agent id="1" name="agentName" typeId="1" connected="true" enabled="true" authorized="true" uptodate="true" ip="..........." href="/app/rest/agents/id:1"> <enabledInfo status="true"> <comment> <user username="userName" id="1" href="/app/rest/users/id:1"/> <timestamp>20160406T175040+0300</timestamp> <text>newcomment</text> </comment> </enabledInfo> <authorizedInfo status="true"> <comment> <user username="userName" id="1" href="/app/rest/users/id:1"/> <timestamp>20160406T183033+0300</timestamp> </comment> </authorizedInfo> .... </agent>

GET および PUT リクエストは、http://teamcity:8111/app/rest/agents/<agentLocator>/enabledInfo(英語)およびhttp://teamcity:8111/app/rest/agents / <agentLocator> / authorized(英語)の URLでサポートされています。

PUT では、ステータスとコメント/テキストのサブアイテムのみが考慮されます。コメントでエージェントを無効にする例:

curl -v -u user:password --request PUT "http://teamcity:8111/app/rest/agents/id:1/enabledInfo" --data "<enabledInfo status='false'><comment><text>commentText</text></comment></enabledInfo>" --header "Content-Type:application/xml

エージェントプール

すべてのエージェントプールを一覧表示する

GET http://teamcity:8111/app/rest/agentPools

IDを使用したエージェントプールの取得/変更/削除

GET/PUT/DELETE http://teamcity:8111/app/rest/agentPools/id:ID

エージェントプールを追加する

POST agentPool name='PoolName' 要素をhttp://teamcity:8111/app/rest/agentPools(英語)に。

以前のプールからプールにエージェントを移動する

POST <agent id='YYY'/> からプールのエージェントhttp://teamcity.url/app/rest/agentPools/id:XXX/agents(英語)へ。

例:

curl -v -u user:password [http://teamcity.url/app/rest/agentPools/id:XXX/agents](http://teamcity.url/app/rest/agentPools/id:XXX/agents) --request POST --header "Content-Type:application/xml" --data "<agent id='1'/>"

エージェントプールへのプロジェクトの割り当て

プロジェクトをプールに追加する

POST <project> ノードからhttp://teamcity.url/app/rest/agentPools/id:XXX/projects(英語)へ。

プールからプロジェクトを削除する

DELETE http://teamcity.url/app/rest/agentPools/id:XXX/projects/id:YYY

ユーザー

ユーザーのリスト

GET http://teamcity:8111/app/rest/users

特定のユーザーの詳細を取得する

GET http://teamcity:8111/app/rest/users/<userLocator>

ユーザーを作成する

POST http://teamcity:8111/app/rest/users

特定のユーザーを更新/削除

PUT/DELETE http://teamcity:8111/app/rest/users/<userLocator>

ユーザーに対する POST および PUT 要求の場合、対応するGET要求によって取得された形式でデータをポストします。次の属性/要素のみがサポートされています: name , username , email , password , roles , groups , properties

ユーザーのロールを操作する

GET http://teamcity:8111/app/rest/users/<userLocator>/roles

<userLocator> は次の形式になります。

  • id:<internal user id> - 内部IDでユーザーを参照する

  • username:<user's username> - ユーザー名/ログイン名でユーザーを参照する

ユーザーの単一フィールド

GET/PUT http://teamcity:8111/app/rest/users/<userLocator>/<field_name>

ユーザーの単一のプロパティ

GET/DELETE/PUT http://teamcity:8111/app/rest/users/<userLocator>/properties/<property_name>

ユーザーグループ

グループのリスト

GET http://teamcity:8111/app/rest/userGroups

グループ内のユーザーのリスト

GET http://teamcity:8111/app/rest/userGroups/key:Group_Key

グループを作る

POST http://teamcity:8111/app/rest/userGroups

グループを削除する

DELETE http://teamcity:8111/app/rest/userGroups/key:Group_Key

ユーザーアクセストークン

アクセストークンのリスト

GET http://teamcity:8111/app/rest/users/<userLocator>/tokens

アクセストークンを作成する

POST http://teamcity:8111/app/rest/users/<userLocator>/tokens/<tokenName>

アクセストークンを削除する

DELETE http://teamcity:8111/app/rest/users/<userLocator>/tokens/<tokenName>

監査記録

ユーザーアクションのレコードにアクセスするには、TeamCityの監査ページでも利用可能

GET http://teamcity:8111/app/rest/audit

ユーザ、システムの動作、ビルドタイプなどでレコードをフィルタすることができます(利用可能なすべてのフィルタを確認するには GET http://teamcity:8111/app/rest/audit?locator=$help(英語)を使用してください)。

データバックアップ

バックアップを開始

POST http://teamcity:8111/app/rest/server/backup?includeConfigs=true&includeDatabase=true&includeBuildLogs=true&fileName=

<fileName> は、バックアップを保存するファイルのプレフィックスです。ファイルは、デフォルトのバックアップディレクトリに作成されます(参照より)。

現在のバックアップステータスを取得する (アイドル/実行)

GET http://teamcity:8111/app/rest/server/backup

型付きパラメータの指定

型付きパラメーターのリスト

プロジェクトの場合:

GET http://teamcity:8111/app/rest/projects/<locator>/parameters

ビルド構成の場合:

GET http://teamcity:8111/app/rest/buildTypes/<locator>/parameters

返される情報は、parameters count , property name , valueおよび typeです。 type エレメントの rawValue は、UIで定義されているパラメーター仕様です。

特定のパラメーターの詳細を取得する

GET http://teamcity:8111/app/rest/buildTypes/<locator>/parameters/<name>

プレーンテキスト、XML、JSONを受け入れる/返します。要求に関連するContent-Typeヘッダを指定してください。

新しいパラメーターを作成する

POST は、GET からhttp://teamcity:8111/app/rest/buildTypes/<locator>/parameters/(英語)に返されるものと同じXMLまたはJSON、または単なるプレーンテキストです。 type=passwordなどの安全なパラメーターがリストされていますが、値は応答に含まれていないため、結果をPOSTする前に修正する必要があります。

TeamCity 9.1以降、パラメータの部分的な更新が可能です(現在実験的な状態です)。

ビルド状況アイコン

ビルドステータスを表すアイコン:

.svgアイコン (お勧め)

GET http://teamcity:8111/app/rest/builds/<buildLocator>/statusIcon.svg

.pngアイコン

GET http://teamcity:8111/app/rest/builds/<buildLocator>/statusIcon

複数のビルドのビルドステータスを表すアイコン ( TeamCity 10.0以降 )

GET リクエストと strob ビルドロケーターディメンション。

リクエスト例 :

PROJECT_ID IDを持つプロジェクトの場合:

GET http://teamcity:8111/app/rest/builds/aggregated/strob:(buildType:(project:(id:PROJECT_ID)))/statusIcon.svg

BUILD_CONF_ID IDを持つビルド構成内のすべてのアクティブブランチの場合

GET http://teamcity:8111/app/rest/builds/aggregated/strob:(branch:(buildType:(id:BUILD_CONF_ID),policy:active_history_and_active_vcs_branches),locator:(buildType:(id:BUILD_CONF_ID)))/statusIcon.svg

要求 /app/rest/builds/aggregated/<build locator> の場合、状況はビルドのリスト app/rest/builds?locator=<build locator>によって計算されます。これにより、単純な img タグを使用して、ビルドステータスアイコンを任意のHTMLページに埋め込むことができます。

BUILD_CONF_ID IDを使用したビルド構成の場合:

最後のビルドの状況

<img src="http://teamcity:8111/app/rest/builds/buildType:(id:BUILD_CONF_ID)/statusIcon"/>

myTag タグでタグ付けされた最後のビルドの状況:

<img src="http://teamcity:8111/app/rest/builds/buildType:(id:BUILD_CONF_ID),tag:myTag/statusIcon"/>

BuildSuccessfulStatus.png

他のすべてのビルドロケーターがサポートされています。

例:次のマークダウンマークアップを使用して、IDが TeamCityPluginsByJetBrains_TeamcityGoogleTagManagerPlugin_Build のビルド構成およびゲスト認証が有効なサーバーhttps://teamcity.jetbrains.com(英語)のGitHubリポジトリのビルドステータスを追加できます。

[![Build status](https://teamcity.jetbrains.com/guestAuth/app/rest/builds/buildType:(id:TeamCityPluginsByJetBrains_TeamcityGoogleTagManagerPlugin_Build)/statusIcon.svg)](https://teamcity.jetbrains.com/viewType.html?buildTypeId=TeamCityPluginsByJetBrains_TeamcityGoogleTagManagerPlugin_Build)

返されたイメージに「データを取得する権限がありません」というテキスト(no-permission-to-get-data.png)が含まれている場合は、次のいずれかが当てはまることを確認してください。

  • サーバーでguestユーザーアクセスが有効になっており、guestユーザーが参照されているビルド構成にアクセスするためのアクセス許可を持っています。

  • 参照されているビルド構成には、「状況ウィジェットを有効にする」 オプション ONがあります。

  • 同じブラウザでTeamCityサーバーにログインしており、参照しているビルド構成を表示する権限があります。GitHubはサーバー側からイメージを取得するため、これはGitHubページの埋め込みイメージには役に立ちません。

TeamCityライセンス情報の要求

TeamCity 10以降 :

ライセンス情報

GET http://teamcity:8111/app/rest/server/licensingData

ライセンスキーのリスト

GET http://teamcity:8111/app/rest/server/licensingData/licenseKeys

ライセンスキーの詳細

GET http://teamcity:8111/app/rest/server/licensingData/licenseKeys/<license_key>

ライセンスキーを追加

http://teamcity:8111/app/rest/server/licensingData/licenseKeys(英語)へのPOST テキスト/プレーン改行区切りキー。

ライセンスキーを削除する

DELETE http://teamcity:8111/app/rest/server/licensingData/licenseKeys/<license_key>

CCTray

CCTray互換のXMLはhttp://teamcity:8111/app/rest/cctray/projects.xml(英語)から入手できます。

認証なし(ゲストユーザーが利用できるビルド構成のみ):http://teamcity:8111/guestAuth/app/rest/cctray/projects.xml(英語)

CCTrayフォーマットのXMLには、デフォルトで一時停止ビルド構成は含まれていません。URLは、標準のビルド構成ロケーターではなく locator パラメーターを受け入れます。

リクエスト例

curl(英語)コマンドラインツールを使用して、TeamCity REST APIと対話できます。

コマンド例:

curl -v --basic --user USERNAME:PASSWORD --request POST "http://teamcity:8111/app/rest/users/" --data @data.xml --header "Content-Type: application/xml"

ここで、USERNAME , PASSWORD , teamcity:8111 は実際の値に置き換えられ、data.xml ファイルにはサーバーに送信するデータが含まれています。

新しいプロジェクトを作成する

カールツールを使用する:

curl -v -u USER:PASSWORD http://teamcity:8111/app/rest/projects --header "Content-Type: application/xml" --data-binary "<newProjectDescription name='New Project Name' id='newProjectId'><parentProject locator='id:project1'/></newProjectDescription>"

ユーザーをシステム管理者にする

  1. スーパーユーザートークンを取得します。

  2. 要求を出します。

  3. curl(英語)コマンドラインツールを取得し、コマンドラインを使用します。

curl -v -u :SUPERUSER_TOKEN --request PUT http://teamcity:8111/app/rest/users/username:USERNAME/roles/SYSTEM_ADMIN/g/

SUPERUSER_TOKEN は、各サーバー起動に固有のスーパーユーザートークンです。 teamcity:8111 - TeamCityサーバーのURL。 USERNAME - システム管理者になるユーザーのユーザー名