TeamCity 2019.1ヘルプ

REST API

一般情報

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

REST APIを使用するために、アプリケーションはTeamCityサーバーにHTTP要求を行い、その応答を解析します。

TeamCity REST APIは、アプリケーションをTeamCityと統合したり、TeamCityサーバーとの対話をスクリプト化したい人のために使用できます。TeamCityのREST APIはURLパスを介してリソース(エンティティ)にアクセスすることを可能にします。

一般的な使用箇所

このドキュメントは完全なガイドではなく、APIを使用するために役立ついくつかの最初の知識を提供するだけです。

ブラウザでhttp://teamcity:8111/app/rest/server(英語) URLを開くことから始めることができます:このページはあなたにAPIを探索するためのいくつかのポインタを与えるでしょう。

サポートされている要求とパラメータの名前の完全なリストを取得するには、http://teamcity:8111/app/rest/application.wadl(英語)を使用してください。これは、サポートされている要求とそのパラメータの主な発見元です。同じデータがhttp://teamcity:8111/app/rest/swagger.json(英語)エンドポイントを介してSwagger(英語)フォーマットで公開されています。

APIを使用する前に、必ずこのセクションを参照してください。

エラー応答に含まれるサポートされているロケーター寸法のリストについては、$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に対して自分自身を認証できます。

  • Teamcity 2019.1以降、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. Under the http://teamcity:8111/app/rest/<version>(英語) URLs other versions CAN be available. Our general policy is to supply TeamCity with at least one previous version. The REST API protocol version is the TeamCity version where this protocl was first introduced.

For example, in TeamCity 2019.1 you can use 2018.1 instead of <version> to get the latest version of REST API or 2017.2 , 2017.1 , 10.0 , 9.1 , 9.0 , 8.1 , 8.0 to get earlier versions of the protocol.

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部分です。
    複数のアイテムを取得する一般的な方法は、<restApiPath>.../app/rest/<items> の形式で使用することです(たとえば、".../app/rest/builds")。これらのURLは、返されたアイテムをフィルタ処理できるロケータパラメータを定期的に受け入れます。個々のアイテムは、.../app/rest/<items>/<item_locator>の形式のURLで定期的にアドレス指定できます。このURLは常に単一の項目を返します。 <item_locator> ロケーターが複数の項目に一致する場合、最初のものが返されます。複数アイテムと単一アイテムの両方のリクエストで、通常fieldsパラメータがサポートされています。

ロケーター

さまざまな場所で、リクエスト内でどのエンティティをフィルタ処理または影響を与えるかを定義するフィルタ文字列を指定できます。このストリング表現は、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:送信されたペイロードからエンティティを作成します。新しいエンティティを作成するには、1つのエンティティデータを定期的に .../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のデータを削除します。

応答フォーマット

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 フィールドを含む」という意味です。フィールド指定の順序は関係ありません。

例:

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

ロギング

logs\teamcity-rest.log サーバーログでエラーとRESTリクエスト処理の詳細を得ることができます。

logs\teamcity-rest.log サーバーログでエラーとRESTリクエスト処理の詳細を得ることができます。

要求に応えてエラーを受け取り、その理由を調査したい場合は、休息関連サーバーログを調べましょう。

処理された各リクエストの詳細を取得するには、デバッグログを有効にします(たとえば、管理/診断ページで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データエンティティ要求

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

プロジェクトのリスト: 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(英語)

サブプロジェクトのビルド構成データと、Overviewページで指定されたユーザーによって設定された順序でプロジェクトを取得します。

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>(英語)

新しい空のプロジェクトを作成します。プレーンテキスト(名前)をhttp://teamcity:8111/app/rest/projects/(英語)にPOSTします。

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

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>(英語)( "Accept" ヘッダーに応じてXML、JSON、およびプレーンテキストを生成し、プレーンテキストと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のいずれかです。

プロジェクトの親プロジェクト: 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>(英語)

「VCSルート」はTeamCity UIで設定された設定で、「VCSルートインスタンス」は実際のVCS操作を実行するために「VCSルート」から派生した内部TeamCityエンティティです。VCSルートにパラメータへの%参照がない場合、単一のVCSルートは単一の「VCSルートインスタンス」に対応します。VCSルートがパラメータに対して%参照を持ち、VCSルートが異なる設定にアタッチされているとき、またはカスタムビルドが実行されているときに参照が異なる値に解決される場合、単一の「VCSルート」で複数の「VCSルートインスタンス」が生成されます。

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ルートインスタンス。

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

ビルド構成/テンプレートの詳細: GET http://teamcity:8111/app/rest/buildTypes/<buildConfigurationLocator>(英語)

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

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

いくつかのビルド構成の集約状況を確認するには、ビルド状況アイコンセクションを参照してください。

一時停止ビルド構成状態を取得/設定します: GET/PUT http://teamcity:8111/app/rest/buildTypes / <buildTypeLocator> / paused(英語) (text / plainとして「true」または「false」のテキストを入力)。

ビルド構成設定: 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が次のようなステップと同じパターンに従います。

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

アーティファクト依存関係を無効/有効にします: PUT http://teamcity:8111/app/rest/buildTypes / <buildTypeLocator> / artifact-dependencies / <id> / disabled(英語)

text / plainとして「true」または「false」のテキストを入れます。

エージェント要件の無効化/有効化: PUT http://teamcity:8111/app/rest/buildTypes / <buildTypeLocator> / agent-requirements / <id> / disabled(英語)

text / plainとして「true」または「false」のテキストを入れます。

ビルド構成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(英語)

2017.2の前に :

テンプレートとの間でビルド構成を読み取り、デタッチ、およびアタッチします。GET/DELETE/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/ERROR> - リストは指定された状況でのみ作成されます。

  • 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/(英語)( "true" または "false" テキストを返します)。

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>(英語)

変更IDは変更の内部IDであり、リビジョンではありません。このIDは、REST APIによってリストされた変更ノード、または変更詳細のURL( modIdとして)に表示されます。

プロジェクトに対するすべての変更を取得します。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ルートの場合、リビジョンに対応する変更はありません。

指定されたリビジョンの http://teamcity:8111/app/rest/builds?locator=revision(version:XXXX)を持つすべてのビルドを入手してください。

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

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

特定のビルドのチェーン全体(スナップショット依存関係のあるすべてのビルド)を取得することができます。

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

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

特定のビルドに対するスナップショット依存のビルドをすべて見つけることができます。

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/<buildLocator>/<field_name>(英語)を取得します。これは、<field_name>number , status , id , branchNameの1つであるtext / plainおよび他のビルドのbean属性を受け入れ/生成します。

統計

単一ビルドの統計を取得します。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以降、単一のテスト呼び出し/実行を公開するための実験的サポートがあります。

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

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を使用してください。

調査

Rootプロジェクトとそのサブプロジェクトの調査をリストします。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)

ユーザーに割り当てられた調査を入手してください: http://teamcity:8111/app/rest/investigations?locator=assignee:(<user locator>)

ビルド構成の調査を入手してください: 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(英語) (text / plainとして「true」または「false」のテキストを入力)。例(英語)を参照してください。

エージェントの許可/許可解除: PUT http://teamcity:8111/app/rest/agents / <agentLocator> / authorized(英語) (text / plainとして「true」または「false」のテキストを入力)。

エージェントの有効化/無効化および承認/承認解除時にコメントを追加します。

エージェント使用可能/許可済みデータは、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

エージェントの単一フィールドを取得/ PUTします。GET/PUT http://teamcity:8111/app/rest/agents/<agentLocator>/<field_name>(英語)

ビルドエージェントを削除します: DELETE http://teamcity:8111/app/rest/agents/<agentLocator>(英語)

エージェントプール

エージェントプールを取得/変更/削除します: GET/PUT/DELETE http://teamcity:8111/app/rest/projects/XXX/agentPools/ID(英語)

エージェントプールを追加します。POST agentPool name='PoolName' 要素をhttp://teamcity:8111/app/rest/projects/XXX/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要求によって検索された形式でデータを投稿してください。次の属性/要素のみがサポートされています:名前、ユーザー名、メール、パスワード、ロール、グループ、プロパティー。

ユーザーロールを操作する: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(英語)

型付きパラメータの指定

型付きパラメーターをリストします。

返される情報は、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以降、パラメータの部分的な更新が可能です(現在実験的な状態です)。

ビルド状況アイコン

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

リクエスト例 :

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>(英語)

ライセンスキーを追加します。POST テキスト/改行で区切られたキーをhttp://teamcity:8111/app/rest/server/licensingData/licenseKeys(英語)に追加します。

ライセンスキーを削除します: 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 - システム管理者になるユーザーのユーザー名