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/

注意

您还可以观察 API，因为 UI 正在使用它来查看它是如何根据各种标准进行过滤的。

任何其他查询字符串参数都可用于将返回的结果列表过滤到与给定值匹配的结果。仅可使用数据库中存在的字段和关系进行过滤。指定值中的任何特殊字符都应进行 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：检查给定字段或相关对象是否为 null；需要布尔值。

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

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

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

空值可以指定为 None 或 Null（两者都不区分大小写），但建议使用 isnull 查找以显式检查空值。

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

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

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