Documentation

インベントリーリストの API エンドポイント

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

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

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

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

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

結果

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

  • id: インベントリーのデータベース ID (整数)
  • type: インベントリーのデータタイプ (選択)
    • inventory: インベントリー
  • url: インベントリーの URL (文字列)
  • related: 関連リソースの URL のあるデータ構造 (オブジェクト)
  • summary_fields: 関連リソースの名前/説明のあるデータ構造 (オブジェクト)
  • created: インベントリー作成時のタイムスタンプ (日時)
  • modified: インベントリーの最終更新時のタイムスタンプ (日時)
  • name: インベントリーの名前 (文字列)
  • description: インベントリーのオプションでの説明 (文字列)
  • organization: このインベントリーを含んでいる組織 (フィールド)
  • kind: 表示されているインベントリーの種類 (選択)
    • "": ホストにインベントリーへの直接リンクがあります。
    • smart: host_filter プロパティーを使用して生成されたインベントリー用のホスト。
  • host_filter: このインベントリーのホストに適用されるフィルター (文字列)
  • variables: YAML または JSON 形式のインベントリー変数 (文字列)
  • has_active_failures: インベントリーのホストが失敗したかどうかを示すフラグ (ブール値)
  • total_hosts: インべントリー内のホストの合計数 (整数)
  • hosts_with_active_failures: アクティブなエラーのあるインベントリー内のホスト数 (整数)
  • total_groups: インべントリー内のグループの合計数 (整数)
  • groups_with_active_failures: アクティブなエラーのあるインベントリー内のグループ数 (整数)
  • has_inventory_sources: インベントリーに外部のインベントリーソースがあるかどうかを示すフラグ (ブール値)
  • total_inventory_sources: インベントリー内で設定される外部インベントリーソースの合計数 (整数)
  • inventory_sources_with_failures: エラーのあるこのインベントリー内の外部インベントリーソースの数 (整数)
  • insights_credential: このインベントリーに属するホストがRed Hat Insights API にアクセスする際に使用する認証情報 (フィールド)
  • pending_deletion: インベントリーが削除中であることを示すフラグ (ブール値)

並び替え

特定の順番でインベントリーが返されることを指定するには、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

インベントリーの作成

新規インベントリーを作成するには、以下のインベントリーフィールドを使ってリソースに POST リクエストを実行します。

  • name: インベントリーの名前 (文字列、必須)
  • description: インベントリーのオプションでの説明 (文字列。デフォルトは "")
  • organization: このインベントリーを含んでいる組織 (フィールド。必須)
  • kind: 表示されているインベントリーの種類 (選択)
    • "": ホストにインベントリーへの直接リンクがあります。(デフォルト)
    • smart: host_filter プロパティーを使用して生成されたインベントリー用のホスト。
  • host_filter: このインベントリーのホストに適用されるフィルター (文字列。デフォルトは "")
  • variables: YAML または JSON 形式のインベントリー変数 (文字列。デフォルトは "")

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

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

name Inventory List
description # List Inventories: Make a GET request to this resource to retrieve the list of inventories.
renders
0 application/json
1 text/html
parses
0 application/json
added_in_version 1.2
actions
POST
name
type string
required
true
label Name
max_length 512
help_text Name of this inventory.
description
type string
required
false
label Description
help_text Optional description of this inventory.
default (Empty Text)
organization
type field
required
true
label Organization
help_text Organization containing this inventory.
kind
type choice
required false
label Kind
help_text Kind of inventory being represented.
default (Empty Text)
choices
0
0 (Empty text)
1 Hosts have a direct link to this inventory.
1
0 smart
1 Hosts for inventory generated using the host_filter property.
host_filter
type string
required false
label Host filter
help_text Filter that will be applied to the hosts of this inventory.
default null
variables
type string
required false
label Variables
help_text Inventory variables in JSON or YAML format.
default (Empty Text)
insights_credential
type field
required false
label Insights credential
help_text Credentials to be used by hosts belonging to this inventory when accessing Red Hat Insights API.
GET
id
type integer
label ID
help_text Database ID for this inventory.
type
type choice
label Type
help_text Data type for this inventory.
choices
0
0 inventory
1 Inventory
url
type string
label Url
help_text URL for this inventory.
related
type object
label Related
help_text Data structure with URLs of related resources.
summary_fields
type object
label Summary fields
help_text Data structure with name/description for related resources.
created
type datetime
label Created
help_text Timestamp when this inventory was created.
modified
type datetime
label Modified
help_text Timestamp when this inventory was last modified.
name
type string
label Name
help_text Name of this inventory.
description
type string
label Description
help_text Optional description of this inventory.
organization
type field
label Organization
help_text Organization containing this inventory.
kind
type choice
label Kind
help_text Kind of inventory being represented.
choices
0
0 (Empty text)
1 Hosts have a direct link to this inventory.
1
0 smart
1 Hosts for inventory generated using the host_filter property.
host_filter
type string
label Host filter
help_text Filter that will be applied to the hosts of this inventory.
variables
type string
label Variables
help_text Inventory variables in JSON or YAML format.
has_active_failures
type boolean
label Has active failures
help_text Flag indicating whether any hosts in this inventory have failed.
total_hosts
type integer
label Total hosts
help_text Total number of hosts in this inventory.
min_value 0
hosts_with_active_failures
type integer
label Hosts with active failures
help_text Number of hosts in this inventory with active failures.
min_value 0
total_groups
type integer
label Total groups
help_text Total number of groups in this inventory.
min_value 0
groups_with_active_failures
type integer
label Groups with active failures
help_text Number of groups in this inventory with active failures.
min_value 0
has_inventory_sources
type boolean
label Has inventory sources
help_text Flag indicating whether this inventory has any external inventory sources.
total_inventory_sources
type integer
label Total inventory sources
help_text Total number of external inventory sources configured within this inventory.
min_value 0
inventory_sources_with_failures
type integer
label Inventory sources with failures
help_text Number of external inventory sources in this inventory with failures.
min_value 0
insights_credential
type field
label Insights credential
help_text Credentials to be used by hosts belonging to this inventory when accessing Red Hat Insights API.
pending_deletion
type boolean
label Pending deletion
help_text Flag indicating the inventory is being deleted.
types
0 inventory
search_fields
0 description
1 name