Documentation

6. 过滤

一个集合就是一个系统所称的 "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” 的、没有活跃故障的组。

如需了解更多可用的 Operator 类型,请参阅: https://docs.djangoproject.com/en/dev/ref/models/querysets/

注解

您还可以监视 API,因为 UI 被用来查看如何过滤各种条件。

任何额外的查询字符串参数都可用来过返回到与给定值匹配的结果列表。只有数据库中存在的字段和关系时才可以用于过滤。指定的值中的任何特殊字符都应该是 url-encoded。例如:

?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,它将只返回相关对象满足这两个条件的主对象。如使用 chain 过滤器写入,它将返回与每个条件匹配的主对象交集。

通过将查询附加到字段名,也可以将字段查询用于更高级的查询:

?field__lookup=value

支持以下字段查找:

  • exact:完全匹配(如果没有指定,则默认查找)。

  • iexact:完全不区分大小写的版本。

  • contains:字段包含值。

  • icontains:包含不区分大小写的版本。

  • startswith:字段以值开头。

  • istartswith:开头不区分大小写的版本。

  • endswith:字段以值结尾。

  • iendswith:结尾不区分大小写的版本。

  • regex:字段与给出的正则表达式匹配。

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

  • gt:大于比较。

  • gte:大于或等于比较。

  • lt:小于比较。

  • lte:小于或等于比较。

  • isnull:检查给定字段或相关对象是否为 null;需要布尔值。

  • in:检查给定字段的值是否出现在提供的列表中;需要项目列表。

  • 对于 true 布尔值可指定为 True1,对于 false 可指定为 False``0``(均不区分大小写)。

Null 值可指定为 NoneNull``(不区分大小写),但是它首选使用 ``isnull 查询来显式检查 null 值。

列表(用于 in 查询)可指定为用逗号分隔的值列表。

根据请求的用户的访问权限级别通过查询字符串参数进行过滤(在 Ansible Tower 3.1 中添加):

  • role_level:要过滤的角色级别,如 admin_role