集合とは、システムで "queryset" と呼ばれるもので、各種演算子でフィルタリングできます。
たとえば、名前に "foo" が含まれるグループを検索します。
http://<Tower server name>/api/v2/groups/?name__contains=foo
完全に一致するグループを検索するには、以下を使用します。
http://<Tower server name>/api/v2/groups/?name=foo
リソースが整数型のものである場合は、以下のように \_\_int を最後に追加して文字列入力値を整数に変換する必要があります。
http://<Tower server name>/api/v2/arbitrary_resource/?x__int=5
また、関連リソースも以下のようにクエリーすることができます。
http://<Tower server name>/api/v2/users/?first_name__icontains=kim
これで名前に "Kim" という文字列が含まれるユーザーすべてが返されます。
複数のフィールドに対して一度にフィルタリングを実行することもできます。
http://<Tower server name>/api/v2/groups/?name__icontains=test&has_active_failures=false
この場合は、グループ名に "test" が含まれ、失敗のないものがすべて返されます。
利用可能な演算子についての詳細情報は、https://docs.djangoproject.com/en/dev/ref/models/querysets/ を参照してください。
注釈
UI を使って各基準に対してフィルタリングを実行している際に、API を確認することもできます。
特定の値に一致する結果一覧に対して、追加のクエリー文字列パラメーターを使ってフィルタリングすることもできます。このフィルタリングに使用できるのは、データベースに存在するフィールドと関係のみです。指定された値の特殊文字は、エンコードされた url にする必要があります。例を示します。
?field=value%20xyz
フィールドは関係にまで及ぶ可能性がありますが、その場合はデータベースで定義されたフィールドと関係に限定されます。
?other__field=value
特定の基準に一致する結果を除外するには、フィールドパラメーターの前に not__ を追加します。
?not__field=value
(AWX 1.4 で追加) デフォルトでは、クエリー文字列フィルターはすべて AND 条件になっているので、全フィルターに一致する結果のみが返されます。複数基準のいずれかに一致する結果にまとめるには、各クエリー文字列パラメーターの前に or__ を追加します。
?or__field=value&or__field=othervalue
?or__not__field=value&or__field=othervalue
(Ansible Tower 1.4.5 で追加) デフォルトの AND 条件のフィルタリングでは、データベース関係全体でフィルタリングされている関連オブジェクトそれぞれに同時に全フィルターが適用されます。チェーンフィルター (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: 完全一致で大文字小文字の区別なし
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