6. 过滤

任何集合都是系统称为“queryset”的内容，可以通过各种运算符进行过滤。

例如，要查找包含名称“foo”的组

http://<awx server name>/api/v2/groups/?name__contains=foo

要查找完全匹配

http://<awx server name>/api/v2/groups/?name=foo

如果资源是整数类型，则必须在末尾添加\_\_int 将字符串输入值转换为整数，如下所示

http://<awx server name>/api/v2/arbitrary_resource/?x__int=5

还可以查询相关资源，如下所示

http://<awx server name>/api/v2/users/?first_name__icontains=kim

这将返回所有名称中包含字符串“Kim”的用户。

您还可以同时根据多个字段进行过滤

http://<awx server name>/api/v2/groups/?name__icontains=test&has_active_failures=false

这将查找包含名称“test”且没有活动错误的组。

有关可用的运算符类型的更多信息，请参阅：https://docs.django.ac.cn/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__related__field=value&chain__related__field2=othervalue
?chain__not__related__field=value&chain__related__field2=othervalue

如果上面的第一个查询写成?related__field=value&related__field2=othervalue，则它只返回同一个相关对象满足这两个条件的主对象。如使用链式过滤器所写，它将返回匹配每个条件的主对象的交集。

字段查找也可用于更高级的查询，方法是将查找附加到字段名称

?field__lookup=value

支持以下字段查找

  • exact：精确匹配（如果未指定，则为默认查找，有关更多信息，请参阅以下说明）。

  • iexact：exact 的不区分大小写版本。

  • contains：字段包含值。

  • icontains：contains 的不区分大小写版本。

  • startswith：字段以值开头。

  • istartswith：startswith 的不区分大小写版本。

  • endswith：字段以值结尾。

  • iendswith：endswith 的不区分大小写版本。

  • regex：字段匹配给定的正则表达式。

  • iregex：regex 的不区分大小写版本。

  • gt：大于比较。

  • gte：大于或等于比较。

  • lt：小于比较。

  • lte：小于或等于比较。

  • isnull：检查给定字段或相关对象是否为空；需要布尔值。

  • in：检查给定字段的值是否存在于提供的列表中；需要一个项目列表。

  • 布尔值可以指定为True或1表示真，False或0表示假（均不区分大小写）。

例如，?created__gte=2023-01-01 将提供 2023 年 1 月 1 日之后创建的项目列表。

空值可以指定为None或Null（均不区分大小写），尽管建议使用isnull查找来显式检查空值。

列表（对于in查找）可以指定为用逗号分隔的值列表。

基于请求用户的访问级别通过查询字符串参数进行过滤

  • role_level：要过滤的角色级别，例如admin_role

注意

以前的 AWX 版本默认返回具有__exact结果的查询，但您可能会发现最新版本返回更大的子集。作为解决方法，请将limit设置为?limit__exact以进行默认过滤。例如，/api/v2/jobs/?limit__exact=example.domain.com的结果为

{
    "count": 1,
    "next": null,
    "previous": null,
    "results": [
...