RESTAPI ロケーター

ロケーターの寸法

ディメンションは、最終的なフィルター式 (ロケーター) を構築するために使用できる単一の基準です。条件を指定するには、dimension:value 構文を使用します。ロケーターには、コンマで区切られた複数の条件を含めることができます。

一部のディメンションは、通常の型 (文字列、整数、ブール値など) の値を受け入れます。例: BuildLocator では、status:failure および failedToStart:true 条件を定義できます。

他のディメンションはロケーターを値として受け入れます。詳細については、「ネストされたロケーター」セクションを参照してください。

利用可能な寸法を調べる

エンドポイントが異なれば、利用可能なロケーターディメンションのセットも異なります。リクエストに $help を追加して、このエンドポイントで利用可能なディメンションを表示します。例: 次の Postman スクリーンショットは、GET https://<server-url>/app/rest/builds/$help リクエストに対する応答を示しています。

リクエストにロケーターを追加する

リクエストにロケーターを追加するには、パス (/locator) またはクエリ (?locator=) パラメーター構文を使用します。

• /locator を使用して、指定された条件を満たす最初の (最上位の) 結果を取得します。例: GET https://<server-url>/app/rest/projects/name:Build 要求は、パブリック名が「Build」である最初に見つかったプロジェクトを返します。

  

• ?locator= を使用して、指定された条件に適合するすべてのオブジェクトのリストを取得します。例: GET https://<server-url>/app/rest/projects?locator=name:Build 要求は、パブリック名が「Build」であるすべてのプロジェクトを返します。下のイメージでは、リストの最初のビルドは、/app/rest/projects/name:Build 要求によって返されるビルドと同じであることに注意してください。

  

デフォルトの寸法

特定のロケーターにはデフォルトの寸法があります。デフォルトのディメンションは、名前を省略できるディメンションです。例: 次の 2 つのリクエストは同一です。

同様に、次の多次元ロケーターは同じ結果を生成します。

ほとんどのロケーターのデフォルトのディメンションは、ID、内部 ID、または名前です。

この短縮構文では、値には ,、:、-、(、) のようなシンボルを含まない英数字のみを含める必要があります。値にコンマ文字（,）が含まれる場合は、その値を括弧で囲みます（<value>）。

ネストされたロケーター

特定のディメンションは、ロケーターを値として受け入れます。以下のリクエストでは、BuildLocator はネストされた BuildTypeLocator を使用して、「TC_Trunk_Compile」ビルド構成のビルドを検索します。

このサンプルリクエストでは、startDate ディメンションにより、しきい値の日付より前に実行されたビルドが除外されます。startDate ディメンションは、特定の DateTime 値の代わりに BuildLocators を受け入れることもできます。このオプションを使用して、特定のビルドの前または後に実行されたビルドを検索します。

このリクエストでは、ディメンション名なしでネストされた BuildTypeLocator および BuildLocator を使用するため、エンティティは ID によってフィルターされます ( デフォルトの寸法セクションを参照)。つまり、上記のリクエストは次のようなものになります (読みやすくするために、ネストされたロケーターは括弧で囲まれています)。

代わりに、デフォルト以外のディメンションを使用してみます。例: 「id:281819048」ビルドのパブリックビルド番号は「88977」です。

このビルド番号によってしきい値ビルドを設定するには、リクエストを次のように変更します。

ビルド番号は親ビルド構成スコープ内でのみ一意であるため、この要求は失敗する可能性があります (「404: 見つかりません」が返されます)。サーバースコープでは、ビルド番号が繰り返されます (各ビルド構成にはビルド #1、ビルド #2 などがあります)。その結果、ネストされた BuildLocator は、異なる構成に属する「88977」ビルドを取得できます。これにより、以前の buildType:TC_Trunk_Compile 条件との不一致が発生します。

この問題を解決するには、ネストされた BuildLocator が親ロケーターと同じビルド構成を指すようにする必要があります。

この最後のリクエストは有効で機能しますが、ID ディメンションに固執することをお勧めします。一意の ID に基づくロケーターはエラーが発生しにくく、一般に最も効果的なフィルターになります。

ページ付け

TeamCity に大きなリストを処理させるリクエストは、タイムアウトやパフォーマンスの問題を引き起こす可能性があります。これを防ぐために、TeamCity はそのようなリストを 100 個のエンティティを含むバッチ (ページ) に分割します。100 レコードのバッチの準備ができると、サーバーは応答を送信します。

エンティティは、ページネーションに関連する次の情報を含むコレクションで返されます。

• count — このバッチ内のエンティティの数。

• start — このバッチの最初のレコードのゼロから始まるインデックス。このインデックスは、見つかったエンティティのリスト全体におけるレコードの位置を反映します。

• nextHref — 次のページを表示できるロケーター。

• prevHref — 前のページを表示できるロケーター。

カスタム count および start 値を使用してリクエストを送信できます。例: 次のリクエストは、「TC_Trunk」プロジェクトのすべてのビルドを検索し、50 番目のレコードから始まる 200 個のビルドのリストを返します。

ルックアップ制限

TeamCity REST API は、各リクエストで処理されるエンティティの内部制限を 5000 に設定します。例: ビルドサーバーに 5000 を超えるビルドがあり、次のリクエストを送信した場合 ...

... 応答にはビルドが 1 つだけ含まれます。start が 5000 以上の場合、TeamCity は項目がゼロのリストを返します。

リクエストに lookupLimit:<value> 条件を追加して、このデフォルトの 5000 エンティティ制限をオーバーライドできます。次のリクエストは、TeamCity に最初の 7000 ビルドを処理させ、ビルド #6000 から #6100 を返します (デフォルトの count 値は 100)。

デフォルトの 5000 エンティティ制限に達すると、サーバー応答の nextHref 値により、他の項目を表示するために lookupLimit ディメンションが自動的に追加されます。

一般的な推奨事項とベストプラクティス

• ディメンションを指定して検索を絞り込むと、徹底的な検索が回避され、サーバーの負荷が軽減されます。例: 特定のビルド構成のビルドを検索する場合は、buildType ディメンションを指定します。

• count および lookupLimit の寸法に注意してください。これらの組み込みの制限 (デフォルトでは、スキャンされたエンティティが 5000 個、応答ごとに 100 個のエンティティ) のため、検索結果が不完全になる可能性があります。

• ビルドを検索する場合、TeamCity はデフォルトのブランチのビルドのみを処理します。代わりに、branch:<any> ディメンションを追加して、すべてのビルドを処理します。

• リクエストが失敗したり、処理に時間がかかりすぎる場合は、TeamCity REST ログを調べて手がかりを探すことができます。このログを有効にするには、管理 | 診断 | トラブルシューティングに移動し、アクティブなログのプリセットを「debug-rest」に設定します。ログファイルは、管理 | 診断 | サーバーログタブにあります。