REST API

一般的な使用箇所

このドキュメントは完全なガイドではなく、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%として参照できます）。

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

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

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.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部分です。
  複数のアイテムを取得する一般的な方法は、<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://teamcity:8111/app/rest/projects(英語)を使用してください。

• REST APIプラグインプロジェクトの全データを取得するには、http://teamcity:8111/app/rest/projects/<projectsLocator>(英語)、たとえばhttp://teamcity:8111/app/rest/projects/id:RESTAPIPlugin(英語)（サンプルIDを使用）を使用します。

• ビルドを取得するには、http://teamcity:8111/app/rest/buildTypes/id:bt284/builds?locator=status:SUCCESS,tag:EAP(英語)（例のIDが使用されている）などのhttp://teamcity:8111/app/rest/buildTypes/id:bt284/builds?locator=<buildLocator>(英語)を使用します。

• ビルドロケーターによるビルドを取得するにはhttp://teamcity:8111/app/rest/builds/?locator=<buildLocator>(英語)を使用してください。

サポートされている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のデータを削除します。

完全および部分的な回答

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

大部分のリクエストでは、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)(英語)

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

ロギング

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を頻繁にクエリしないで、リクエストされたデータを必要なものだけに制限してください（期限ロケーターを使用し、必要なフィールドを指定します ）。あなたの要求から負荷でサーバーの動作を確認してください。要求の処理に時間がかかる場合は、要求を頻繁に繰り返さないようにしてください。

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

プロジェクトのリスト： 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/<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します。

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

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(英語)に作成します。

また支えられる：

• GET/PUT http://teamcity:8111/app/rest/vcs-roots/<vcsRootLocator>/properties/<property_name>(英語)
• GET/PUT http://teamcity:8111/app/rest/vcs-roots/<vcsRootLocator>/<field_name>(英語)

ここで、<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"を追加するなどして制限を増やすことを検討してください。

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

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

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

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

ビルド構成をコピーします。

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を持つテンプレートロケータを受け付けます。

ビルド番号カウンタを設定します。

ビルド番号の形式を設定します。

ビルドリクエスト

リストビルド： GET http://teamcity:8111/app/rest/builds/?locator=<buildLocator>(英語)。

特定のビルドの詳細を入手する： GET http://teamcity:8111/app/rest/builds/<buildLocator>(英語)。

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

プロジェクト内のビルド構成のリストを、各ビルド構成内の最後に完了したビルドのステータスと共に取得します。

テストと構築の問題

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

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

すべての呼び出しをフラット化してすべてのテスト実行を一覧表示します。

調査

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=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 ノードに公開されています。

GET および PUT 要求は、http://teamcity:8111/app/rest/agents/<agentLocator>/enabledInfo(英語)およびhttp://teamcity:8111/app/rest/agents / <agentLocator> / authorizedという(英語) URLに対してサポートされています。

PUT では、ステータスとコメント/テキストのサブアイテムのみが考慮されます。

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

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

ユーザー

ユーザーのリスト： 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(英語)を使用してください）。

データバックアップ

バックアップを開始します。

<fileName> はバックアップを保存するファイルのプレフィックスです。ファイルは、（参照してください。デフォルトのバックアップディレクトリーに作成されますより ）。現在のバックアップステータス（アイドル/実行中）を取得します： GET http://teamcity:8111/app/rest/server/backup(英語)。

型付きパラメータの指定

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

• プロジェクトの場合: http://teamcity:8111/app/rest/projects/<locator>/parameters(英語)

• ビルド構成の場合: 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以降、パラメータの部分的な更新が可能です（現在実験的な状態です）。

• 名前: GET からhttp://teamcity:8111/app/rest/buildTypes/<locator>/parameters/NAME(英語)に返されるのと同じXMLまたはJSON PUT

• 型: GET からURL http://teamcity:8111/app/rest/buildTypes/<locator>/parameters/NAME/type(英語)に返されたXMLおよびJSONを受け入れる GET/PUT

• 型のrawValue: プレーンテキストを受け入れる GET/PUT http://teamcity:8111/app/rest/buildTypes/<locator>/parameters/NAME/type/rawValue(英語)

ビルド状況アイコン

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

• .svgアイコン（ 推奨 ）： GET http://teamcity:8111/app/rest/builds/<buildLocator>/statusIcon.svg(英語)

• A .pngアイコン： GET http://teamcity:8111/app/rest/builds/<buildLocator>/statusIcon(英語)

• いくつかのビルド（TeamCity 10.0以降）のビルド状況を表すアイコン： GET 要求および strob ビルドロケーターディメンション。

リクエスト例 :

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

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

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

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

最後のビルドの状況

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

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

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

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

• サーバーで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と対話できます。

コマンド例：

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