コレクションとは、システムが "queryset" と呼ぶもので、各種演算子を使用してフィルタリングすることができます。
例えば、名前に "foo" が含まれるグループを検索するには、以下を使用します。
http://<controller server name>/api/v2/groups/?name__contains=foo
完全に一致するグループを検索するには、以下を使用します。
http://<controller server name>/api/v2/groups/?name=foo
リソースが整数型である場合は、以下のように \_\_int を末尾に追加して文字列入力値を整数に変換する必要があります。
http://<controller server name>/api/v2/arbitrary_resource/?x__int=5
また、関連リソースも以下のようにクエリーすることができます。
http://<controller server name>/api/v2/users/?first_name__icontains=kim
これで名前に "Kim" という文字列が含まれるユーザーすべてが返されます。
複数のフィールドに対して一度にフィルタリングを実行することもできます。
http://<controller 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
デフォルトでは、クエリー文字列フィルターはすべて AND 条件になっているため、全フィルターに一致する結果のみが返されます。複数基準のいずれかに一致する結果にまとめるには、各クエリー文字列パラメーターの前に or__ を追加します。
?or__field=value&or__field=othervalue
?or__not__field=value&or__field=othervalue
デフォルトの 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: 大文字小文字の区別のない exact
contains: フィールドに値を含む
icontains: 大文字小文字の区別のない contains
startswith: 値で始まるフィールド
istartswith: startswith で大文字小文字の区別なし
endswith: 値で終わるフィールド
iendswith: 大文字小文字の区別のない exact
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 を指定します (どちらも大文字小文字の区別なし)。
たとえば、?created__gte=2020-01-01 は 2020 年 1 月 1 日 の後に作成されたアイテムの一覧を提供します。
Null 値は None または Null (どちらも大文字小文字の区別なし) を指定できますが、isnull ルックアップを使用して明示的に null 値をチェックすることが推奨されます。
in ルックアップのリストは、値をコンマ区切りのリストとして指定することができます。
クエリー文字列のパラメーターによるユーザーのアクセスレベルの要求をもとにしたフィルタリング (automation controller 3.1 で追加)。
role_level: フィルターをかけるロールのレベル。例: admin_role