Documentation

インスタンスの API エンドポイント

このリソースに GET リクエストを実行して、インスタンスリストを取得します。

GET /api/v2/instances
HTTP 200 OK
Allow: GET, HEAD, OPTIONS
Content-Type: application/json
Vary: Accept
X-API-Node: localhost
X-API-Time: 0.059s

返されるデータ構造には以下のものが含まれます。

{
    "count": 99,
    "next": null,
    "previous": null,
    "results": [
}

count フィールドはクエリーで見つかったインスタンスの合計数を示します。next および previous フィールドは、単一ページに収まらない結果がある場合に、それらの結果へのリンクを提供します。results にはインスタンスのレコードが一覧表示されますが、ゼロの場合もあります。

結果

各インスタンスのデータ構造には以下のフィールドが含まれます。

  • id: インスタンスのデータベース ID (整数)
  • type: インスタンスのデータタイプ (選択)
    • instance: インスタンス
  • url: インスタンスの URL (文字列)
  • related: 関連リソースの URL のあるデータ構造 (オブジェクト)
  • uuid: インスタンスの UUID (Universally Unique Identifier) (文字列)
  • hostname: インスタンスのホスト名 (文字列)
  • created: インスタンス作成時のタイムスタンプ (日時)
  • modified: インスタンスの最終更新時のタイムスタンプ (日時)
  • version: インスタンスのバージョン (文字列)
  • capacity: インスタンスの総容量 (整数)
  • consumed_capacity: インスタンスが消費した容量 (フィールド)
  • percent_capacity_remaining: インスタンスの残りの容量のパーセンテージ (フィールド)
  • jobs_running: インスタンスで実行中のジョブの数 (フィールド)

並び替え

特定の順番でインスタンスが返されることを指定するには、order_by クエリー文字列のパラメーターを GET リクエストで使用します。

?order_by=name

逆の順序に並び替えるには、フィールド名の前にダッシュ - を加えます。

?order_by=-name

フィールド名をコンマ , 区切りにすると、複数のフィールドの並び替えを指定できます。

?order_by=name,some_other_field

検索

モデルの指定された全テキストフィールド内で大文字小文字の区別のない検索を実行するには、search クエリー文字列のパラメーターを使用します。

?search=findme

関連フィールドを検索します (AWX 1.4 / Ansible Tower 3.1 で追加)。

?related__search=findme

フィルタリング

特定の値に一致する結果一覧に対して、追加のクエリー文字列パラメーターを使ってフィルタリングすることもできます。このフィルタリングに使用できるのは、データベースに存在するフィールドと関係のみです。指定された値の特殊文字は、エンコードされた URL にする必要があります。例を示します。

?field=value%20xyz

フィールドは関係にまで及ぶ可能性がありますが、その場合はデータベースで定義されたフィールドと関係に限定されます。

?other__field=value

特定の基準に一致する結果を除外するには、フィールドパラメーターの前に not__ を追加します。

?not__field=value

デフォルトでは、クエリー文字列フィルターはすべて AND 条件になっているので、すべての フィルターに一致する結果のみが返されます (AWX 1.4 で追加)。複数基準の いずれか に一致する結果にまとめるには、各クエリー文字列パラメーターの前に or__ を追加します。

?or__field=value&or__field=othervalue
?or__not__field=value&or__field=othervalue

デフォルトの AND 条件のフィルタリングでは、データベース関係全体でフィルタリングされている関連オブジェクトそれぞれに同時に全フィルターが適用されます (Ansible Tower 1.4.5 で追加) 。チェーンフィルター (chain) では、フィルターを個別に関連オブジェクトごとに適用します。これを使用するには、chain__ をクエリー文字列パラメーターの前に追加します。

?chain__related__field=value&chain__related__field2=othervalue
?chain__not__related__field=value&chain__related__field2=othervalue

上記で最初のクエリーが ?related__field=value&related__field2=othervalue となっていれば、同一の関連オブジェクトが両方の条件を満たしているプライマリーオブジェクトのみが返されますが、上記通りのチェーンフィルターを使用すると、各条件に一致するプライマリーオブジェクトの共通集合が返されます。

フィールド名に lookup を追加すると、より詳細なクエリーによるフィールドルックアップが可能になります。

?field__lookup=value

以下のフィールドのルックアップがサポートされています。

  • exact: 完全一致 (指定されない場合のデフォルトのルックアップ)
  • iexact: 大文字小文字の区別のない exact
  • contains: フィールドに値を含む
  • icontains: 大文字小文字の区別のない contains
  • startswith: 値で始まるフィールド
  • istartswith: 大文字小文字の区別のない startswith
  • endswith: 値で終わるフィールド
  • iendswith: 大文字小文字の区別のない endswith
  • regex: 特定の正規表現に一致するフィールド
  • iregex: 大文字小文字の区別のない regex
  • gt: Greater than の比較条件
  • gte: Greater than or equal to の比較条件
  • lt: Less than の比較条件
  • lte: Less than or equal to の比較条件
  • isnull: 特定フィールドもしくは関連オブジェクトが null かどうかをチェック。ブール値を想定
  • in: 特定フィールドの値が提供されたリストに存在するかどうかをチェック。アイテムのリストを想定

ブール値は true の場合 True または 1 を、false の場合は False または 0 を指定します (どちらも大文字小文字の区別なし)。

Null 値は None または Null (どちらも大文字小文字の区別なし) を指定できますが、isnull ルックアップを使用して明示的に null 値をチェックすることが推奨されます。

in ルックアップのリストは、値をコンマ区切りのリストとして指定することができます。

クエリー文字列のパラメーターによるユーザーのアクセスレベルのリクエストをベースにしたフィルタリング (Ansible Tower 3.1 で追加)。

  • role_level: フィルターをかけるロールのレベル。例、admin_role

オプションエンドポイントの確認

オプションエンドポイント テーブルでは、このエンドポイントのオプションを確認できます。ブラウザー表示が可能な API でエンドポイントを表示している場合は、「オプション」ボタンをクリックすると以下の raw JSON が表示されます。

name instances
description # List instances: Make a GET request to this resource to retrieve the list of instances.
renders
0 application/json
1 text/html
parses
0 application/json
added_in_version 3.2.0
actions
GET
id
type integer
label ID
help_text Database ID for this instance.
type
type choice
label Type
help_text Data type for this instance.
choices
0
0 instance
1 Instance
url
type string
label URL
help_text URL for this instance.
related
type object
label Related
help_text Data structure with URLs of related resources.
uuid
type string
label Uuid
help_text Unique identifier for this instance.
hostname
type string
label Hostname
help_text Hostname for this instance.
created
type datetime
label Created
help_text Timestamp when this instance was created.
modified
type datetime
label Modified
help_text Timestamp when this instance was last modified.
version
type string
label Version
help_text Version of this instance.
capacity
type integer
label Capacity
min_value 0
help_text Total capacity for this instance.
consumed_capacity
type field
label Consumed capacity
help_text Capacity this instance has consumed.
percent_capacity_remaining
type field
label Percent capacity remaining
help_text Percentage of remaining capacity for this instance.
jobs_running
type field
label Jobs running
help_text Number of jobs running in this instance.
types
0 instance
related_search_fields
0 ramparts_groups__search