ビルドの開始とキャンセル

通常のビルドを開始する

ビルドを開始できるようにするには、次のエンドポイントを介してビルドキューにアクセスする必要があります。

新しいビルドをキューに入れるには、次の 2 つの手順が必要です。

1. ターゲットビルドを表すリクエストペイロード（つまり、 Build エンティティ）を準備します。

2. ペイロードを使用して POST 要求を送信します。

ステップ 1 :

この Build エンティティのペイロードには、ビルド構成（または、REST API 用語では BuildType ）への参照が含まれている必要があります。Build のサブエンティティとして含めます。

ステップ 2 :

ビルドをキューに追加するには、ステップ 1 で指定した本文を使用して POST 要求を送信します。

要求ヘッダーには、許可ヘッダー（ゲスト許可スキームが使用されている場合を除く）と、オプションで Content-Type/Accept ヘッダーを含める必要があります。

エンドポイントは、起動されたビルドの簡単な説明で応答します。また、TCSESSIONID Cookie も含まれます。これを再利用して、次の実行で認証をスキップできます。

カスタムビルドを開始する

より複雑な例は、ビルド構成で指定された設定とは異なる設定でビルドを実行する必要がある場合です。この場合、リクエストでビルドに関する追加データを送信する必要があります。

Build エンティティで使用可能なフィールドから、以下を渡します。

• personal : ビルドが個人的なものであることを定義する

• branchName : デフォルト以外のブランチでビルドを起動するには

• agent : Agent サブエンティティを送信して、このビルドの特定のエージェントを選択します

• comment : ビルドに説明を提供する

• properties : 複合 Properties エンティティを送信して、カスタムビルドパラメーターを設定 (またはそのようなパラメーターが存在しない場合は作成) します。

ほとんどのデータはローカルで利用できるはずです。ただし、この例では、ID を知っている必要がある特定のエージェントを要求します。エージェントを名前で知っている場合は、次のリクエストを送信することでその ID を見つけることができます。

ここで、?locator=... 部分は、エージェントを名前で検索するために使用される AgentLocator エンティティを指定します。リクエストは、ID を解析できるそれぞれの Agent エンティティを返します。

POST リクエストの最終的なペイロードは次のようになります。

基本的な場合と同様に、POST リクエストを介して送信します。その結果、パーソナルビルドは、指定されたエージェント上の myBranch ブランチで 2 つの新しいビルドパラメーター値を使用して実行されます。

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

ビルドをキューに入れたら、そのステータスを確認できます。

ここで、 BuildQueueLocator はキューに入れられたビルドを表します。POST 要求の送信時に受け取ったビルド ID を指定できます。

このリクエストは Build エンティティを返します。デフォルトでは、TeamCity はエンティティの基本フィールドを返します。ポーリングの目的で、ビルドステータスのみを受け取りたい場合があります。リクエストパスで ?fields パラメーターを使用して、レスポンスで使用できるフィールドの範囲を制限できます（続きを読む）。

呼び出しの結果、TeamCity は、id と state の 2 つのフィールドのみが入力された Build エンティティを返します。

キューに入れられたビルドをキャンセルする

キューに入れられたばかりのビルドをキャンセルするには、次を送信します。

ここで、BuildCancelRequest エンティティがペイロードとして使用されます。

このエンティティは、次の 2 つのフィールドで構成されます。

• comment : ビルドがキャンセルされた理由に関するオプションのコメントを提供する

• readdIntoQueue : これが以前にキャンセルされたビルドを復元する要求であるかどうかを宣言するブールプロパティ。ビルドを復元するのではなくキャンセルすることを目的としているため、false に設定します

結果のペイロード:

ID でビルドをキャンセルするには、以下を送信します。

または、キューに入れられたビルドを単に削除することもできます（メタデータが必要ない場合）。これを行うには、同じエンドポイントで DELETE 要求を実行します。

開始したビルドをキャンセルする

すでに開始されているビルドをキャンセルするには、以下を送信します。

上記の例と同じ BuildCancelRequest エンティティを使用します。

ID でビルドをキャンセルするには、以下を送信します。

チェーンビルドのトリガー

TeamCity では、さまざまな構成からのビルドを編成して、単一のチェーンで実行できます。例: ビルド結果を集約するための複合ビルドで終わる 3 つのビルド構成のチェーンを持つことができます: ConfigA → ConfigB → ConfigC → ChainABC。

チェーン全体を開始するには、最後のビルド構成に対して新しいビルドをトリガーします。

チェーンの最後の構成ではない構成に対して新しいビルドをトリガーすると、この構成とその構成が依存する構成のみが実行されます。例: 次のペイロードは、ConfigA → ConfigB シーケンスのみをトリガーします (ConfigB は ConfigA に依存します)。

直接依存関係のあるビルドの再利用

依存ビルドをトリガーするときに、この新しいビルドで再利用する前の構成の完了したビルドを指定できます。例: 次のペイロードは、ID が「4976」の既存の ConfigA ビルドを再利用する新しい ConfigB ビルドをトリガーします。

<build> <buildType id="ConfigB"/> <snapshot-dependencies count="1"> <build id="4976" buildTypeId="ConfigA"/> </snapshot-dependencies> </build>

{ "buildType": { "id": "ConfigB" }, "snapshot-dependencies": { "count": 1, "build": [{ "id": 4976, "buildTypeId": "ConfigA" }] } }

同じリクエストで複数の直接依存関係を指定できます。たとえば、ConfigA と ConfigB が独立した構成で、ConfigC が両方に依存している場合、次のペイロードを送信できます。

<build> <buildType id="ConfigC"/> <snapshot-dependencies> <build id="4997" buildTypeId="ConfigA"/> <build id="4998" buildTypeId="ConfigB"/> </snapshot-dependencies> </build>

{ "buildType": { "id": "ConfigC" }, "snapshot-dependencies": { "build": [ { "id": 4997, "buildTypeId": "ConfigA" }, { "id": 4998, "buildTypeId": "ConfigB" }] } }

間接的な依存関係を持つビルドの再利用

前のセクションでは、リクエストは、トリガーされたビルドが直接依存する構成のビルドを再利用しました。ただし、間接的な依存関係でビルドを再利用することもできます。

例: 同じ ConfigA → ConfigB → ConfigC チェーンの場合、既存の ConfigA ビルドを再利用する ConfigC ビルドをトリガーできます。

/app/rest/buildQueue

<build> <buildType id="ConfigC"/> <snapshot-dependencies count="1"> <build id="4976" buildTypeId="ConfigA"/> </snapshot-dependencies> </build>

{ "buildType": { "id": "ConfigC" }, "snapshot-dependencies": { "count": 1, "build": [{ "id": 4976, "buildTypeId": "ConfigA" }] } }

新しい ConfigB ビルドは、ConfigC の依存関係設定に応じて実行されるかどうかが決まります。ConfigC で適切なビルドの再利用が許可されている場合、ConfigA と ConfigB の両方のビルドが再利用されます。

それ以外の場合、ConfigC が常に新しいビルドを必要とする場合は、(既存の ConfigA ビルドの結果を使用して) 新しい ConfigB ビルドが実行されます。

ビルドキューの一時停止と再開

すべての TeamCity ビルドを一時停止および再開するには、/app/rest/buildQueue/pausedState エンドポイントに PUT リクエストを送信します。リクエスト本文には、次の 2 つのプロパティを持つオブジェクトを渡す必要があります。

• paused — キューが現在一時停止されているかどうかを指定するブール型のプロパティ。

• reason — UI の警告および監査エントリに表示されるコメントを指定する、オプションの文字列プロパティ。