모든 컬렉션은 “쿼리 세트”에 해당하며 다양한 연산자를 통해 필터링할 수 있습니다.
예를 들어, “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
특정 기준과 일치하는 결과를 제외하려면 field 매개변수 앞에 ``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의 경우 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)