Django rest framework фильтрация
The root QuerySet provided by the Manager describes all objects in the database table. Usually, though, you’ll need to select only a subset of the complete set of objects.
‒ Django documentation
The default behavior of REST framework’s generic list views is to return the entire queryset for a model manager. Often you will want your API to restrict the items that are returned by the queryset.
The simplest way to filter the queryset of any view that subclasses GenericAPIView is to override the .get_queryset() method.
Overriding this method allows you to customize the queryset returned by the view in a number of different ways.
Установка политики разрешений
Политика разрешений по умолчанию может быть установлена глобально с помощью параметра DEFAULT_PERMISSION_CLASSES . Например.
Если этот параметр не указан, то по умолчанию он разрешает неограниченный доступ:
Вы также можете установить политику аутентификации на основе каждого представления или набора представлений, используя представления на основе классов APIView .
Или, если вы используете декоратор @api_view с представлениями, основанными на функциях.
Примечание: когда вы задаете новые классы разрешений с помощью атрибута class или декораторов, вы указываете представлению игнорировать список по умолчанию, заданный в файле settings.py .
При условии наследования от rest_framework.permissions.BasePermission , разрешения могут быть составлены с использованием стандартных побитовых операторов Python. Например, IsAuthenticatedOrReadOnly может быть записано:
Примечание: поддерживаются & (и), | (или) и ~ (не).
Фильтрация по URL-адресу¶
Другой стиль фильтрации может включать ограничение набора запросов на основе некоторой части URL.
Например, если ваша конфигурация URL содержит запись, подобную этой:
Затем вы можете написать представление, которое возвращает набор запросов на покупку, отфильтрованный по имени пользователя в части URL:
Django Rest Framework PSQ
Пакет Django Rest Framework PSQ — это расширение, обеспечивающее поддержку того, чтобы классы permission_classes, serializer_class и queryset зависели от правил permission-based.
Корневой QuerySet, предоставляемый менеджером, описывает все объекты в таблице базы данных. Обычно, однако, вам нужно выбрать только подмножество полного набора объектов.
‒ Django documentation
По умолчанию общие представления списков в REST framework возвращают весь набор запросов для менеджера модели. Часто вы хотите, чтобы ваш API ограничивал элементы, возвращаемые набором запросов.
Самый простой способ фильтровать набор запросов любого представления, которое является подклассом GenericAPIView , - это переопределить метод .get_queryset() .
Переопределение этого метода позволяет вам настроить набор запросов, возвращаемый представлением, различными способами.
Methods
Base methods:
get_queryset(self)
Returns the queryset that should be used for list views, and that should be used as the base for lookups in detail views. Defaults to returning the queryset specified by the queryset attribute.
This method should always be used rather than accessing self.queryset directly, as self.queryset gets evaluated only once, and those results are cached for all subsequent requests.
May be overridden to provide dynamic behavior, such as returning a queryset, that is specific to the user making the request.
Note: If the serializer_class used in the generic view spans orm relations, leading to an n+1 problem, you could optimize your queryset in this method using select_related and prefetch_related . To get more information about n+1 problem and use cases of the mentioned methods refer to related section in django documentation.
get_object(self)
Returns an object instance that should be used for detail views. Defaults to using the lookup_field parameter to filter the base queryset.
May be overridden to provide more complex behavior, such as object lookups based on more than one URL kwarg.
filter_queryset(self, queryset)
Given a queryset, filter it with whichever filter backends are in use, returning a new queryset.
get_serializer_class(self)
Returns the class that should be used for the serializer. Defaults to returning the serializer_class attribute.
May be overridden to provide dynamic behavior, such as using different serializers for read and write operations, or providing different serializers to different types of users.
Save and deletion hooks:
The following methods are provided by the mixin classes, and provide easy overriding of the object save or deletion behavior.
- perform_create(self, serializer) - Called by CreateModelMixin when saving a new object instance.
- perform_update(self, serializer) - Called by UpdateModelMixin when saving an existing object instance.
- perform_destroy(self, instance) - Called by DestroyModelMixin when deleting an object instance.
These hooks are particularly useful for setting attributes that are implicit in the request, but are not part of the request data. For instance, you might set an attribute on the object based on the request user, or based on a URL keyword argument.
These override points are also particularly useful for adding behavior that occurs before or after saving an object, such as emailing a confirmation, or logging the update.
You can also use these hooks to provide additional validation, by raising a ValidationError() . This can be useful if you need some validation logic to apply at the point of database save. For example:
Other methods:
You won't typically need to override the following methods, although you might need to call into them if you're writing custom views using GenericAPIView .
- get_serializer_context(self) - Returns a dictionary containing any extra context that should be supplied to the serializer. Defaults to including 'request' , 'view' and 'format' keys.
- get_serializer(self, instance=None, data=None, many=False, partial=False) - Returns a serializer instance.
- get_paginated_response(self, data) - Returns a paginated style Response object.
- paginate_queryset(self, queryset) - Paginate a queryset if required, either returning a page object, or None if pagination is not configured for this view.
- filter_queryset(self, queryset) - Given a queryset, filter it with whichever filter backends are in use, returning a new queryset.
The mixin classes provide the actions that are used to provide the basic view behavior. Note that the mixin classes provide action methods rather than defining the handler methods, such as .get() and .post() , directly. This allows for more flexible composition of behavior.
The mixin classes can be imported from rest_framework.mixins .
Фильтрация по текущему пользователю¶
Вы можете захотеть отфильтровать набор запросов, чтобы гарантировать, что будут возвращены только результаты, относящиеся к текущему аутентифицированному пользователю, сделавшему запрос.
DRY Rest Permissions
Пакет DRY Rest Permissions предоставляет возможность определять различные разрешения для отдельных действий по умолчанию и пользовательских действий. Этот пакет предназначен для приложений с разрешениями, которые вытекают из отношений, определенных в модели данных приложения. Он также поддерживает проверку разрешений, возвращаемую клиентскому приложению через сериализатор API. Кроме того, он поддерживает добавление разрешений к действиям списка по умолчанию и пользовательским действиям списка для ограничения данных, которые они извлекают для каждого пользователя.
Django REST framework полный фильтр поиска слов¶
djangorestframework-word-filter разработан как альтернатива filters.SearchFilter , который будет искать полное слово в тексте, или точное совпадение.
RetrieveAPIView
Used for read-only endpoints to represent a single model instance.
Provides a get method handler.
Filtering against the URL¶
Another style of filtering might involve restricting the queryset based on some part of the URL.
For example if your URL config contained an entry like this:
You could then write a view that returned a purchase queryset filtered by the username portion of the URL:
Setting filter backends
The default filter backends may be set globally, using the DEFAULT_FILTER_BACKENDS setting. For example.
You can also set the filter backends on a per-view, or per-viewset basis, using the GenericAPIView class-based views.
Attributes
Basic settings:
The following attributes control the basic view behavior.
- queryset - The queryset that should be used for returning objects from this view. Typically, you must either set this attribute, or override the get_queryset() method. If you are overriding a view method, it is important that you call get_queryset() instead of accessing this property directly, as queryset will get evaluated once, and those results will be cached for all subsequent requests.
- serializer_class - The serializer class that should be used for validating and deserializing input, and for serializing output. Typically, you must either set this attribute, or override the get_serializer_class() method.
- lookup_field - The model field that should be used to for performing object lookup of individual model instances. Defaults to 'pk' . Note that when using hyperlinked APIs you'll need to ensure that both the API views and the serializer classes set the lookup fields if you need to use a custom value.
- lookup_url_kwarg - The URL keyword argument that should be used for object lookup. The URL conf should include a keyword argument corresponding to this value. If unset this defaults to using the same value as lookup_field .
Pagination:
The following attributes are used to control pagination when used with list views.
- pagination_class - The pagination class that should be used when paginating list results. Defaults to the same value as the DEFAULT_PAGINATION_CLASS setting, which is 'rest_framework.pagination.PageNumberPagination' . Setting pagination_class=None will disable pagination on this view.
Filtering:
- filter_backends - A list of filter backend classes that should be used for filtering the queryset. Defaults to the same value as the DEFAULT_FILTER_BACKENDS setting.
CreateModelMixin
Provides a .create(request, *args, **kwargs) method, that implements creating and saving a new model instance.
If an object is created this returns a 201 Created response, with a serialized representation of the object as the body of the response. If the representation contains a key named url , then the Location header of the response will be populated with that value.
If the request data provided for creating the object was invalid, a 400 Bad Request response will be returned, with the error details as the body of the response.
Customizing the interface¶
to_html(self, request, queryset, view)
The method should return a rendered HTML string.
ListModelMixin
Provides a .list(request, *args, **kwargs) method, that implements listing a queryset.
If the queryset is populated, this returns a 200 OK response, with a serialized representation of the queryset as the body of the response. The response data may optionally be paginated.
CreateAPIView
Used for create-only endpoints.
Provides a post method handler.
drf-url-filters¶
drf-url-filter is a simple Django app to apply filters on drf ModelViewSet ‘s Queryset in a clean, simple and configurable way. It also supports validations on incoming query params and their values. A beautiful python package Voluptuous is being used for validations on the incoming query parameters. The best part about voluptuous is you can define your own validations as per your query params requirements.
© Django.Fun 2017-2021 | Django.Fun is not associated with the Django Software Foundation. Django is a registered trademark of the Django Software Foundation.
The root QuerySet provided by the Manager describes all objects in the database table. Usually, though, you'll need to select only a subset of the complete set of objects.
— Django documentation
The default behavior of REST framework's generic list views is to return the entire queryset for a model manager. Often you will want your API to restrict the items that are returned by the queryset.
The simplest way to filter the queryset of any view that subclasses GenericAPIView is to override the .get_queryset() method.
Overriding this method allows you to customize the queryset returned by the view in a number of different ways.
GenericAPIView
This class extends REST framework's APIView class, adding commonly required behavior for standard list and detail views.
Each of the concrete generic views provided is built by combining GenericAPIView , with one or more mixin classes.
OrderingFilter¶
The OrderingFilter class supports simple query parameter controlled ordering of results.
By default, the query parameter is named 'ordering' , but this may by overridden with the ORDERING_PARAM setting.
For example, to order users by username:
The client may also specify reverse orderings by prefixing the field name with ‘-‘, like so:
Multiple orderings may also be specified:
Specifying a default ordering¶
If an ordering attribute is set on the view, this will be used as the default ordering.
Typically you’d instead control this by setting order_by on the initial queryset, but using the ordering parameter on the view allows you to specify the ordering in a way that it can then be passed automatically as context to a rendered template. This makes it possible to automatically render column headers differently if they are being used to order the results.
The ordering attribute may be either a string or a list/tuple of strings.
You can also provide your own generic filtering backend, or write an installable app for other developers to use.
To do so override BaseFilterBackend , and override the .filter_queryset(self, request, queryset, view) method. The method should return a new, filtered queryset.
As well as allowing clients to perform searches and filtering, generic filter backends can be useful for restricting which objects should be visible to any given request or user.
Django URL Filter¶
django-url-filter предоставляет безопасный способ фильтрации данных через удобные для человека URL. Он работает очень похоже на сериализаторы и поля DRF в том смысле, что они могут быть вложенными, за исключением того, что они называются filtersets и filters. Это обеспечивает простой способ фильтрации связанных данных. Также эта библиотека является универсальной, поэтому ее можно использовать для фильтрации других источников данных, а не только Django QuerySet s.
DjangoFilterBackend¶
Библиотека ** ``django-filter :doc:` ` включает класс DjangoFilterBackend , который поддерживает высоконастраиваемую фильтрацию полей для REST-фреймворка.
Чтобы использовать DjangoFilterBackend , сначала установите django-filter .
Затем добавьте 'django_filters' к INSTALLED_APPS в Django:
Теперь вам следует либо добавить бэкенд фильтра в настройки:
Или добавьте бэкэнд фильтра к отдельному представлению или набору представлений.
Если вам нужна простая фильтрация на основе равенства, вы можете установить атрибут filterset_fields на представлении или наборе представлений, перечисляющий набор полей, по которым вы хотите фильтровать.
Это автоматически создаст класс FilterSet для заданных полей, и позволит вам делать такие запросы, как:
Для более сложных требований к фильтрации вы можете указать FilterSet класс, который должен использоваться представлением. Вы можете прочитать больше о FilterSet s в django-filter documentation . Также рекомендуется прочитать раздел DRF integration .
Как определяются разрешения
Разрешения во фреймворке REST всегда определяются как список классов разрешений.
Перед запуском основной части представления проверяется каждое разрешение в списке. Если проверка какого-либо разрешения не удалась, будет вызвано исключение exceptions.PermissionDenied или exceptions.NotAuthenticated , и основное тело представления не будет запущено.
При неудачной проверке разрешений будет возвращен ответ «403 Forbidden» или «401 Unauthorized», в соответствии со следующими правилами:
Specifying which fields may be ordered against
It's recommended that you explicitly specify which fields the API should allowing in the ordering filter. You can do this by setting an ordering_fields attribute on the view, like so:
This helps prevent unexpected data leakage, such as allowing users to order against a password hash field or other sensitive data.
If you don't specify an ordering_fields attribute on the view, the filter class will default to allowing the user to filter on any readable fields on the serializer specified by the serializer_class attribute.
If you are confident that the queryset being used by the view doesn't contain any sensitive data, you can also explicitly specify that a view should allow ordering on any model field or queryset aggregate, by using the special value '__all__' .
RetrieveModelMixin
Provides a .retrieve(request, *args, **kwargs) method, that implements returning an existing model instance in a response.
If an object can be retrieved this returns a 200 OK response, with a serialized representation of the object as the body of the response. Otherwise it will return a 404 Not Found .
DestroyModelMixin
Provides a .destroy(request, *args, **kwargs) method, that implements deletion of an existing model instance.
If an object is deleted this returns a 204 No Content response, otherwise it will return a 404 Not Found .
The following classes are the concrete generic views. If you're using generic views this is normally the level you'll be working at unless you need heavily customized behavior.
The view classes can be imported from rest_framework.generics .
Composed Permissions
Пакет Composed Permissions предоставляет простой способ определения сложных и многоглубинных (с логическими операторами) объектов разрешений, используя небольшие и многократно используемые компоненты.
Filtering against query parameters¶
A final example of filtering the initial queryset would be to determine the initial queryset based on query parameters in the url.
As well as being able to override the default queryset, REST framework also includes support for generic filtering backends that allow you to easily construct complex searches and filters.
Generic filters can also present themselves as HTML controls in the browsable API and admin API.
ListAPIView
Used for read-only endpoints to represent a collection of model instances.
Provides a get method handler.
DjangoObjectPermissions
Этот класс разрешений связан со стандартной структурой объектных разрешений Django, которая позволяет предоставлять разрешения на модели для каждого объекта. Чтобы использовать этот класс разрешений, вам также потребуется добавить бэкенд разрешений, поддерживающий разрешения на уровне объектов, например, django-guardian.
Как и в случае с DjangoModelPermissions , это разрешение должно применяться только к представлениям, имеющим свойство .queryset или метод .get_queryset() . Авторизация будет предоставлена только в том случае, если пользователь аутентифицирован и имеет соответствующие разрешения на объект и соответствующие разрешения на модель.
- POST -запросы требуют, чтобы пользователь имел разрешение на добавление экземпляра модели.
- Запросы PUT и PATCH требуют от пользователя разрешения на изменение экземпляра модели.
- Запросы DELETE требуют от пользователя разрешения на удаление экземпляра модели.
Обратите внимание, что DjangoObjectPermissions не требует пакета django-guardian и должен одинаково хорошо поддерживать другие бэкенды объектного уровня.
Как и в случае с DjangoModelPermissions , вы можете использовать пользовательские разрешения модели, переопределив DjangoObjectPermissions и установив свойство .perms_map . За подробностями обращайтесь к исходному коду.
Примечание: Если вам нужны разрешения на просмотр на уровне объектов для запросов GET , HEAD и OPTIONS и вы используете django-guardian для бэкенда разрешений на уровне объектов, вам стоит рассмотреть возможность использования класса DjangoObjectPermissionsFilter , предоставляемого пакетом djangorestframework-guardian . Он гарантирует, что конечные точки списка возвращают только те результаты, включающие объекты, для которых пользователь имеет соответствующие разрешения на просмотр.
Переопределение начального набора queryset¶
Обратите внимание, что вы можете использовать и переопределенный .get_queryset() , и общую фильтрацию вместе, и все будет работать, как ожидалось. Например, если Product имеет отношения «многие-ко-многим» с User , названными purchase , вы можете написать представление следующим образом:
Обзор методов ограничения доступа
REST framework предлагает три различных метода для настройки ограничений доступа в каждом конкретном случае. Они применяются в разных сценариях и имеют разные эффекты и ограничения.
- queryset/get_queryset() : Ограничивает общую видимость существующих объектов из базы данных. Кверисет ограничивает, какие объекты будут отображаться в списке и какие объекты могут быть изменены или удалены. Метод get_queryset() может применять различные кверисеты в зависимости от текущего действия.
- permission_classes/get_permissions() : Проверка общих разрешений на основе текущего действия, запроса и целевого объекта. Разрешения на уровне объекта могут быть применены только к действиям получения, изменения и удаления. Проверки разрешений для list и create будут применены ко всему типу объекта. (В случае списка: с учетом ограничений в наборе запросов).
- serializer_class/get_serializer() : Ограничения на уровне экземпляра, которые применяются ко всем объектам на входе и выходе. Сериализатор может иметь доступ к контексту запроса. Метод get_serializer() может применять различные сериализаторы в зависимости от текущего действия.
В следующей таблице перечислены методы ограничения доступа и уровень контроля, который они обеспечивают над какими действиями.
queryset | permission_classes | serializer_class | |
---|---|---|---|
Action: list | global | no | object-level* |
Action: create | no | global | object-level |
Action: retrieve | global | object-level | object-level |
Action: update | global | object-level | object-level |
Action: partial_update | global | object-level | object-level |
Action: destroy | global | object-level | no |
Can reference action in decision | no** | yes | no** |
Can reference request in decision | no** | yes | yes |
* Класс Serializer не должен вызывать PermissionDenied в действии со списком, иначе весь список не будет возвращен.
** Методы get_*() имеют доступ к текущему представлению и могут возвращать различные экземпляры Serializer или QuerySet в зависимости от запроса или действия.
Настройка бэкендов фильтров¶
Бэкенды фильтров по умолчанию могут быть установлены глобально, с помощью параметра DEFAULT_FILTER_BACKENDS . Например.
Вы также можете установить бэкенды фильтров на основе каждого представления или каждого набора представлений, используя представления на основе классов GenericAPIView .
Django Rest Multiple Models
Django Rest Multiple Models provides a generic view (and mixin) for sending multiple serialized models and/or querysets via a single API request.
Вместе с аутентификацией и дросселированием, разрешения определяют, должен ли запрос получить доступ или отказать в нем.
Разрешения используются для предоставления или запрета доступа различных классов пользователей к различным частям API.
Простейший стиль разрешения — разрешить доступ любому аутентифицированному пользователю и запретить доступ любому неаутентифицированному пользователю. Это соответствует классу IsAuthenticated в REST-фреймворке.
Чуть менее строгий стиль разрешения заключается в том, чтобы разрешить полный доступ аутентифицированным пользователям, но разрешить доступ только для чтения неаутентифицированным пользователям. Это соответствует классу IsAuthenticatedOrReadOnly в REST framework.
DestroyAPIView
Used for delete-only endpoints for a single model instance.
Provides a delete method handler.
Example
For example, you might need to restrict users to only being able to see objects they created.
We could achieve the same behavior by overriding get_queryset() on the views, but using a filter backend allows you to more easily add this restriction to multiple views, or to apply it across the entire API.
RetrieveDestroyAPIView
Used for read or delete endpoints to represent a single model instance.
Provides get and delete method handlers.
Filtering and object lookups¶
Note that if a filter backend is configured for a view, then as well as being used to filter list views, it will also be used to filter the querysets used for returning a single object.
For instance, given the previous example, and a product with an id of 4675 , the following URL would either return the corresponding object, or return a 404 response, depending on if the filtering conditions were met by the given product instance:
Specifying which fields may be ordered against¶
It’s recommended that you explicitly specify which fields the API should allowing in the ordering filter. You can do this by setting an ordering_fields attribute on the view, like so:
This helps prevent unexpected data leakage, such as allowing users to order against a password hash field or other sensitive data.
If you don’t specify an ordering_fields attribute on the view, the filter class will default to allowing the user to filter on any readable fields on the serializer specified by the serializer_class attribute.
If you are confident that the queryset being used by the view doesn’t contain any sensitive data, you can also explicitly specify that a view should allow ordering on any model field or queryset aggregate, by using the special value '__all__' .
Django REST framework filters package
The django-rest-framework-filters package works together with the DjangoFilterBackend class, and allows you to easily create filters across relationships, or create multiple filter lookup types for a given field.
Examples
Typically when using the generic views, you'll override the view, and set several class attributes.
For more complex cases you might also want to override various methods on the view class. For example.
For very simple cases you might want to pass through any class attributes using the .as_view() method. For example, your URLconf might include something like the following entry:
drf-url-filters
drf-url-filter is a simple Django app to apply filters on drf ModelViewSet 's Queryset in a clean, simple and configurable way. It also supports validations on incoming query params and their values. A beautiful python package Voluptuous is being used for validations on the incoming query parameters. The best part about voluptuous is you can define your own validations as per your query params requirements.
Django’s generic views. were developed as a shortcut for common usage patterns. They take certain common idioms and patterns found in view development and abstract them so that you can quickly write common views of data without having to repeat yourself.
— Django Documentation
One of the key benefits of class-based views is the way they allow you to compose bits of reusable behavior. REST framework takes advantage of this by providing a number of pre-built views that provide for commonly used patterns.
The generic views provided by REST framework allow you to quickly build API views that map closely to your database models.
If the generic views don't suit the needs of your API, you can drop down to using the regular APIView class, or reuse the mixins and base classes used by the generic views to compose your own set of reusable generic views.
Filtering against the current user¶
You might want to filter the queryset to ensure that only results relevant to the currently authenticated user making the request are returned.
Фильтрация и поиск объектов¶
Обратите внимание, что если бэкэнд фильтра настроен для представления, то помимо того, что он используется для фильтрации представлений списка, он также будет использоваться для фильтрации наборов запросов, используемых для возврата одного объекта.
Например, учитывая предыдущий пример и продукт с идентификатором 4675 , следующий URL либо вернет соответствующий объект, либо выдаст ответ 404, в зависимости от того, были ли выполнены условия фильтрации для данного экземпляра продукта:
Пример¶
Например, вам может понадобиться ограничить доступ пользователей только к созданным ими объектам.
Мы могли бы добиться такого же поведения, переопределив get_queryset() в представлениях, но использование бэкенда фильтра позволяет вам легче добавить это ограничение к нескольким представлениям или применить его ко всему API.
SearchFilter
The SearchFilter class supports simple single query parameter based searching, and is based on the Django admin's search functionality.
When in use, the browsable API will include a SearchFilter control:
The SearchFilter class will only be applied if the view has a search_fields attribute set. The search_fields attribute should be a list of names of text type fields on the model, such as CharField or TextField .
This will allow the client to filter the items in the list by making queries such as:
You can also perform a related lookup on a ForeignKey or ManyToManyField with the lookup API double-underscore notation:
For JSONField and HStoreField fields you can filter based on nested values within the data structure using the same double-underscore notation:
By default, searches will use case-insensitive partial matches. The search parameter may contain multiple search terms, which should be whitespace and/or comma separated. If multiple search terms are used then objects will be returned in the list only if all the provided terms are matched.
The search behavior may be restricted by prepending various characters to the search_fields .
- '^' Starts-with search.
- '=' Exact matches.
- '@' Full-text search. (Currently only supported Django's PostgreSQL backend.)
- '$' Regex search.
By default, the search parameter is named 'search' , but this may be overridden with the SEARCH_PARAM setting.
To dynamically change search fields based on request content, it's possible to subclass the SearchFilter and override the get_search_fields() function. For example, the following subclass will only search on title if the query parameter title_only is in the request:
For more details, see the Django documentation.
Django REST Framework API Key
Пакет Django REST Framework API Key предоставляет классы разрешений, модели и помощники для добавления авторизации API ключей в ваш API. Его можно использовать для авторизации внутренних или сторонних бэкендов и сервисов (т.е. машин), которые не имеют учетной записи пользователя. API ключи хранятся в безопасном месте с использованием инфраструктуры хеширования паролей Django, и их можно просматривать, редактировать и отзывать в любое время в админке Django.
Creating custom mixins
For example, if you need to lookup objects based on multiple fields in the URL conf, you could create a mixin class like the following:
You can then simply apply this mixin to a view or viewset anytime you need to apply the custom behavior.
Using custom mixins is a good option if you have custom behavior that needs to be used.
Filtering against the URL
Another style of filtering might involve restricting the queryset based on some part of the URL.
For example if your URL config contained an entry like this:
You could then write a view that returned a purchase queryset filtered by the username portion of the URL:
Ограничения разрешений на уровне объектов
По причинам производительности общие представления не будут автоматически применять разрешения на уровне объектов к каждому экземпляру в наборе запросов при возврате списка объектов.
Часто при использовании разрешений на уровне объектов вы также хотите соответствующим образом отфильтровать набор запросов, чтобы гарантировать, что пользователи могут просматривать только те экземпляры, которые им разрешено просматривать.
Поскольку метод get_object() не вызывается, разрешения объектного уровня из метода has_object_permission() не применяются при создании объектов. Чтобы ограничить создание объектов, необходимо реализовать проверку разрешений либо в классе Serializer , либо переопределить метод perform_create() класса ViewSet.
ЗаказФильтр¶
Класс OrderingFilter поддерживает простое упорядочивание результатов, управляемое параметрами запроса.
По умолчанию параметр запроса называется 'ordering' , но это можно отменить с помощью параметра ORDERING_PARAM .
Например, чтобы упорядочить пользователей по имени пользователя:
Клиент также может указать обратный порядок, добавив к имени поля префикс „-„, как показано ниже:
Также можно указать несколько порядков:
Django URL Filter
django-url-filter provides a safe way to filter data via human-friendly URLs. It works very similar to DRF serializers and fields in a sense that they can be nested except they are called filtersets and filters. That provides easy way to filter related data. Also this library is generic-purpose so it can be used to filter other sources of data and not only Django QuerySet s.
Filtering & schemas
The method should return a list of coreapi.Field instances.
The following third party packages provide additional filter implementations.
Overriding the initial queryset¶
Note that you can use both an overridden .get_queryset() and generic filtering together, and everything will work as expected. For example, if Product had a many-to-many relationship with User , named purchase , you might want to write a view like this:
ListCreateAPIView
Used for read-write endpoints to represent a collection of model instances.
Provides get and post method handlers.
Пагинация и схемы¶
Вы также можете сделать элементы управления фильтром доступными для автогенерации схемы, которую обеспечивает REST framework, реализовав метод get_schema_fields() . Этот метод должен иметь следующую сигнатуру:
Метод должен возвращать список экземпляров coreapi.Field .
Следующие пакеты сторонних производителей предоставляют дополнительные реализации фильтров.
AllowAny
Класс разрешения AllowAny разрешает неограниченный доступ, независимо от того, был ли запрос аутентифицирован или неаутентифицирован.
Это разрешение не является строго обязательным, поскольку вы можете достичь того же результата, используя пустой список или кортеж для настройки разрешений, но вы можете найти полезным указать этот класс, поскольку он делает намерение явным.
IsAuthenticated
Класс разрешения IsAuthenticated запрещает доступ любому пользователю, не прошедшему аутентификацию, и разрешает его в противном случае.
IsAdminUser
Класс разрешения IsAdminUser запрещает доступ любому пользователю, если только параметр user.is_staff не равен True , в этом случае разрешение будет разрешено.
Это разрешение подходит, если вы хотите, чтобы ваш API был доступен только подмножеству доверенных администраторов.
IsAuthenticatedOrReadOnly
IsAuthenticatedOrReadOnly позволит аутентифицированным пользователям выполнять любые запросы. Запросы неавторизованных пользователей будут разрешены, только если метод запроса является одним из «безопасных» методов: GET , HEAD или OPTIONS .
Это разрешение подходит, если вы хотите, чтобы ваш API позволял разрешения на чтение анонимным пользователям и разрешал запись только аутентифицированным пользователям.
DjangoModelPermissions
Этот класс разрешений связан со стандартными разрешениями модели Django django.contrib.auth . Это разрешение должно применяться только к представлениям, имеющим свойство .queryset или метод get_queryset() . Авторизация будет предоставлена только в том случае, если пользователь аутентифицирован и имеет соответствующие разрешения модели.
- POST -запросы требуют, чтобы пользователь имел разрешение add на модель.
- Запросы PUT и PATCH требуют от пользователя разрешения на изменение модели.
- Запросы DELETE требуют от пользователя разрешения на удаление модели.
Поведение по умолчанию также можно переопределить для поддержки пользовательских разрешений модели. Например, вы можете включить разрешение модели представления для запросов GET .
Чтобы использовать пользовательские разрешения модели, переопределите DjangoModelPermissions и установите свойство .perms_map . Для получения подробной информации обратитесь к исходному коду.
RetrieveUpdateDestroyAPIView
Used for read-write-delete endpoints to represent a single model instance.
Provides get , put , patch and delete method handlers.
Often you'll want to use the existing generic views, but use some slightly customized behavior. If you find yourself reusing some bit of customized behavior in multiple places, you might want to refactor the behavior into a common class that you can then just apply to any view or viewset as needed.
UpdateModelMixin
Provides a .update(request, *args, **kwargs) method, that implements updating and saving an existing model instance.
If an object is updated this returns a 200 OK response, with a serialized representation of the object as the body of the response.
If the request data provided for updating the object was invalid, a 400 Bad Request response will be returned, with the error details as the body of the response.
Разрешения на уровне объектов
Разрешения фреймворка REST также поддерживают разрешения на уровне объектов. Разрешения на уровне объектов используются для определения того, разрешено ли пользователю действовать с определенным объектом, который обычно является экземпляром модели.
Разрешения на уровне объектов запускаются общими представлениями REST framework при вызове функции .get_object() . Как и в случае с разрешениями на уровне представления, исключение exceptions.PermissionDenied будет вызвано, если пользователю не разрешено действовать с данным объектом.
Это либо вызовет исключение PermissionDenied или NotAuthenticated , либо просто вернет результат, если представление имеет соответствующие разрешения.
Примечание: За исключением DjangoObjectPermissions , предоставленные классы разрешений в rest_framework.permissions не реализуют методы, необходимые для проверки объектных разрешений.
Если вы хотите использовать предоставленные классы разрешений для проверки объектных разрешений, вы должны подклассифицировать их и реализовать метод has_object_permission() , описанный в разделе Custom permissions (ниже).
drf-url-filters¶
drf-url-filter - это простое Django приложение для применения фильтров к drf ModelViewSet „s Queryset чистым, простым и настраиваемым способом. Оно также поддерживает валидацию входящих параметров запроса и их значений. Для проверки входящих параметров запроса используется красивый пакет python Voluptuous . Самое лучшее в voluptuous то, что вы можете определить свои собственные валидации в соответствии с требованиями к параметрам запроса.
Настройка интерфейса¶
Общие фильтры могут также представлять интерфейс в просматриваемом API. Для этого необходимо реализовать метод to_html() , который возвращает отрисованное HTML-представление фильтра. Этот метод должен иметь следующую сигнатуру:
to_html(self, request, queryset, view)
Метод должен возвращать отрендеренную строку HTML.
Overriding the initial queryset
Note that you can use both an overridden .get_queryset() and generic filtering together, and everything will work as expected. For example, if Product had a many-to-many relationship with User , named purchase , you might want to write a view like this:
Filtering against the current user
You might want to filter the queryset to ensure that only results relevant to the currently authenticated user making the request are returned.
Указание того, какие поля могут быть заказаны против¶
Рекомендуется явно указать, какие поля API должен разрешить в фильтре упорядочивания. Вы можете сделать это, установив атрибут ordering_fields на представлении, как показано ниже:
Это помогает предотвратить непредвиденную утечку данных, например, разрешение пользователям делать заказы по хэш-полю пароля или других конфиденциальных данных.
Если вы не укажете атрибут ordering_fields на представлении, класс фильтра по умолчанию позволит пользователю фильтровать по любым читаемым полям на сериализаторе, указанном атрибутом serializer_class .
Если вы уверены, что кверисет, используемый представлением, не содержит конфиденциальных данных, вы также можете явно указать, что представление должно разрешить упорядочивание по любому полю модели или агрегату кверисета, используя специальное значение '__all__' .
Django REST framework filters package¶
The django-rest-framework-filters package works together with the DjangoFilterBackend class, and allows you to easily create filters across relationships, or create multiple filter lookup types for a given field.
OrderingFilter
The OrderingFilter class supports simple query parameter controlled ordering of results.
By default, the query parameter is named 'ordering' , but this may by overridden with the ORDERING_PARAM setting.
For example, to order users by username:
The client may also specify reverse orderings by prefixing the field name with '-', like so:
Multiple orderings may also be specified:
Setting filter backends¶
The default filter backends may be set globally, using the DEFAULT_FILTER_BACKENDS setting. For example.
You can also set the filter backends on a per-view, or per-viewset basis, using the GenericAPIView class-based views.
Django URL Filter¶
django-url-filter provides a safe way to filter data via human-friendly URLs. It works very similar to DRF serializers and fields in a sense that they can be nested except they are called filtersets and filters. That provides easy way to filter related data. Also this library is generic-purpose so it can be used to filter other sources of data and not only Django QuerySet s.
Example¶
For example, you might need to restrict users to only being able to see objects they created.
We could achieve the same behavior by overriding get_queryset() on the views, but using a filter backend allows you to more easily add this restriction to multiple views, or to apply it across the entire API.
RetrieveUpdateAPIView
Used for read or update endpoints to represent a single model instance.
Provides get , put and patch method handlers.
SearchFilter¶
Класс SearchFilter поддерживает простой поиск на основе одного параметра запроса и основан на Django admin’s search functionality.
При использовании просматриваемый API будет включать элемент управления SearchFilter :
Класс SearchFilter будет применяться только в том случае, если у представления установлен атрибут search_fields . Атрибут search_fields должен представлять собой список имен полей текстового типа в модели, например CharField или TextField .
Это позволит клиенту фильтровать элементы в списке, делая такие запросы, как:
Вы также можете выполнить связанный поиск по полю ForeignKey или ManyToManyField с помощью нотации двойного андерскора API поиска:
Для полей JSONField и HStoreField вы можете фильтровать на основе вложенных значений внутри структуры данных, используя ту же нотацию с двойным индексированием:
По умолчанию при поиске используются частичные совпадения без учета регистра. Параметр поиска может содержать несколько условий поиска, которые должны быть разделены пробелами и/или запятыми. Если используется несколько условий поиска, то объекты будут возвращены в списке только в том случае, если совпадут все указанные условия.
Поведение поиска может быть ограничено путем добавления различных символов к search_fields .
„^“ Начинается с поиска.
„@“ Полнотекстовый поиск. (В настоящее время поддерживается только Django’s PostgreSQL backend ).
По умолчанию параметр поиска называется 'search' , но это может быть отменено настройкой SEARCH_PARAM .
Чтобы динамически изменять поля поиска в зависимости от содержимого запроса, можно создать подкласс SearchFilter и переопределить функцию get_search_fields() . Например, следующий подкласс будет искать по title , только если в запросе присутствует параметр запроса title_only :
Более подробную информацию см. в разделе Django documentation .
Фильтрация по параметрам запроса¶
Последним примером фильтрации начального набора запросов может быть определение начального набора запросов на основе параметров запроса в url.
Помимо возможности переопределения набора запросов по умолчанию, REST framework также включает поддержку общих бэкендов фильтрации, которые позволяют легко создавать сложные поиски и фильтры.
Общие фильтры также могут быть представлены в виде элементов управления HTML в просматриваемом API и API администратора.
Filtering and object lookups
Note that if a filter backend is configured for a view, then as well as being used to filter list views, it will also be used to filter the querysets used for returning a single object.
For instance, given the previous example, and a product with an id of 4675 , the following URL would either return the corresponding object, or return a 404 response, depending on if the filtering conditions were met by the given product instance:
Django REST framework full word search filter¶
The djangorestframework-word-filter developed as alternative to filters.SearchFilter which will search full word in text, or exact match.
DRF — Политика доступа
Пакет Django REST — Access Policy предоставляет способ определения сложных правил доступа в декларативных классах политик, которые прикрепляются к наборам представлений или представлениям на основе функций. Политики определяются в JSON в формате, аналогичном политикам AWS Identity & Access Management.
Filtering against query parameters
A final example of filtering the initial queryset would be to determine the initial queryset based on query parameters in the url.
As well as being able to override the default queryset, REST framework also includes support for generic filtering backends that allow you to easily construct complex searches and filters.
Generic filters can also present themselves as HTML controls in the browsable API and admin API.
Пользовательские разрешения
Чтобы реализовать пользовательское разрешение, переопределите BasePermission и реализуйте один из следующих методов или оба:
- .has_permission(self, request, view)
- .has_object_permission(self, request, view, obj)
Эти методы должны возвращать True , если запрос должен получить доступ, и False в противном случае.
Если вам нужно проверить, является ли запрос операцией чтения или записи, вы должны проверить метод запроса на соответствие константе SAFE_METHODS , которая представляет собой кортеж, содержащий ‘ GET ‘, ‘ OPTIONS ‘ и ‘ HEAD ‘. Например:
DjangoFilterBackend
The django-filter library includes a DjangoFilterBackend class which supports highly customizable field filtering for REST framework.
To use DjangoFilterBackend , first install django-filter .
Then add 'django_filters' to Django's INSTALLED_APPS :
You should now either add the filter backend to your settings:
Or add the filter backend to an individual View or ViewSet.
If all you need is simple equality-based filtering, you can set a filterset_fields attribute on the view, or viewset, listing the set of fields you wish to filter against.
This will automatically create a FilterSet class for the given fields, and will allow you to make requests such as:
For more advanced filtering requirements you can specify a FilterSet class that should be used by the view. You can read more about FilterSet s in the django-filter documentation. It's also recommended that you read the section on DRF integration.
Customizing the interface
to_html(self, request, queryset, view)
The method should return a rendered HTML string.
Django Rest Framework Roles
Пакет Django Rest Framework Roles облегчает параметризацию вашего API для нескольких типов пользователей.
Specifying a default ordering
If an ordering attribute is set on the view, this will be used as the default ordering.
Typically you'd instead control this by setting order_by on the initial queryset, but using the ordering parameter on the view allows you to specify the ordering in a way that it can then be passed automatically as context to a rendered template. This makes it possible to automatically render column headers differently if they are being used to order the results.
The ordering attribute may be either a string or a list/tuple of strings.
You can also provide your own generic filtering backend, or write an installable app for other developers to use.
To do so override BaseFilterBackend , and override the .filter_queryset(self, request, queryset, view) method. The method should return a new, filtered queryset.
As well as allowing clients to perform searches and filtering, generic filter backends can be useful for restricting which objects should be visible to any given request or user.
Пакеты сторонних разработчиков
Также доступны следующие пакеты сторонних разработчиков.
Creating custom base classes
If you are using a mixin across multiple views, you can take this a step further and create your own set of base views that can then be used throughout your project. For example:
Using custom base classes is a good option if you have custom behavior that consistently needs to be repeated across a large number of views throughout your project.
Prior to version 3.0 the REST framework mixins treated PUT as either an update or a create operation, depending on if the object already existed or not.
Allowing PUT as create operations is problematic, as it necessarily exposes information about the existence or non-existence of objects. It's also not obvious that transparently allowing re-creating of previously deleted instances is necessarily a better default behavior than simply returning 404 responses.
Both styles " PUT as 404" and " PUT as create" can be valid in different circumstances, but from version 3.0 onwards we now use 404 behavior as the default, due to it being simpler and more obvious.
If you need to generic PUT-as-create behavior you may want to include something like this AllowPUTAsCreateMixin class as a mixin to your views.
The following third party packages provide additional generic view implementations.
Указание порядка по умолчанию¶
Если в представлении установлен атрибут ordering , он будет использоваться в качестве упорядочивания по умолчанию.
Обычно вы контролируете это, устанавливая order_by в начальном наборе запросов, но использование параметра ordering в представлении позволяет вам указать упорядочивание таким образом, что оно может быть автоматически передано в качестве контекста в шаблон рендеринга. Это позволяет автоматически отображать заголовки столбцов по-разному, если они используются для упорядочивания результатов.
Атрибут ordering может быть либо строкой, либо списком/кортежем строк.
Вы также можете предоставить свой собственный общий бэкэнд фильтрации или написать устанавливаемое приложение для использования другими разработчиками.
Для этого переопределите BaseFilterBackend , и переопределите метод .filter_queryset(self, request, queryset, view) . Метод должен вернуть новый, отфильтрованный набор запросов.
Помимо того, что клиенты могут выполнять поиск и фильтрацию, общие бэкенды фильтров могут быть полезны для ограничения того, какие объекты должны быть видны для каждого конкретного запроса или пользователя.
DjangoFilterBackend¶
The ``django-filter :doc:` ` library includes a DjangoFilterBackend class which supports highly customizable field filtering for REST framework.
To use DjangoFilterBackend , first install django-filter .
Then add 'django_filters' to Django’s INSTALLED_APPS :
You should now either add the filter backend to your settings:
Or add the filter backend to an individual View or ViewSet.
If all you need is simple equality-based filtering, you can set a filterset_fields attribute on the view, or viewset, listing the set of fields you wish to filter against.
This will automatically create a FilterSet class for the given fields, and will allow you to make requests such as:
For more advanced filtering requirements you can specify a FilterSet class that should be used by the view. You can read more about FilterSet s in the django-filter documentation . It’s also recommended that you read the section on DRF integration .
Django Rest Framework Role Filters
Пакет Django Rest Framework Role Filters обеспечивает простую фильтрацию по нескольким типам ролей.
SearchFilter¶
The SearchFilter class supports simple single query parameter based searching, and is based on the Django admin’s search functionality.
When in use, the browsable API will include a SearchFilter control:
The SearchFilter class will only be applied if the view has a search_fields attribute set. The search_fields attribute should be a list of names of text type fields on the model, such as CharField or TextField .
This will allow the client to filter the items in the list by making queries such as:
You can also perform a related lookup on a ForeignKey or ManyToManyField with the lookup API double-underscore notation:
For JSONField and HStoreField fields you can filter based on nested values within the data structure using the same double-underscore notation:
By default, searches will use case-insensitive partial matches. The search parameter may contain multiple search terms, which should be whitespace and/or comma separated. If multiple search terms are used then objects will be returned in the list only if all the provided terms are matched.
The search behavior may be restricted by prepending various characters to the search_fields .
‘@’ Full-text search. (Currently only supported Django’s PostgreSQL backend .)
By default, the search parameter is named 'search' , but this may be overridden with the SEARCH_PARAM setting.
To dynamically change search fields based on request content, it’s possible to subclass the SearchFilter and override the get_search_fields() function. For example, the following subclass will only search on title if the query parameter title_only is in the request:
For more details, see the Django documentation .
UpdateAPIView
Used for update-only endpoints for a single model instance.
Provides put and patch method handlers.
Pagination & schemas¶
The method should return a list of coreapi.Field instances.
The following third party packages provide additional filter implementations.
Django REST framework full word search filter
The djangorestframework-word-filter developed as alternative to filters.SearchFilter which will search full word in text, or exact match.
DjangoModelPermissionsOrAnonReadOnly
Аналогично DjangoModelPermissions , но также позволяет неаутентифицированным пользователям иметь доступ к API только для чтения.
REST Condition
Пакет REST Condition — это еще одно расширение для построения сложных разрешений простым и удобным способом. Расширение позволяет комбинировать разрешения с логическими операторами.
Пакет фильтров фреймворка Django REST¶
Класс django-rest-framework-filters package работает вместе с классом DjangoFilterBackend и позволяет легко создавать фильтры по отношениям или создавать несколько типов поиска фильтра для определенного поля.
Руководство API
Примеры
Ниже приведен пример класса разрешения, который проверяет IP-адрес входящего запроса по списку блокировки и отклоняет запрос, если IP-адрес был заблокирован.
Помимо глобальных разрешений, которые действуют на все входящие запросы, вы также можете создавать разрешения на уровне объекта, которые действуют только на операции, затрагивающие конкретный экземпляр объекта. Например:
Также обратите внимание, что общие представления будут проверять разрешения на уровне объектов только для представлений, которые получают один экземпляр модели. Если вам требуется фильтрация списковых представлений на уровне объектов, вам придется фильтровать набор запросов отдельно. Более подробную информацию см. в документации по фильтрации.
Читайте также: