HTTP clients can send a number of headers to tell the server about copies of a\nresource that they have already seen. This is commonly used when retrieving a\nWeb page (using an HTTP GET request) to avoid sending all the data for\nsomething the client has already retrieved. However, the same headers can be\nused for all HTTP methods (POST, PUT, DELETE, etc.).
For each page (response) that Django sends back from a view, it might provide\ntwo HTTP headers: the ETag header and the Last-Modified header. These\nheaders are optional on HTTP responses. They can be set by your view function,\nor you can rely on the ConditionalGetMiddleware\nmiddleware to set the ETag header.
When the client next requests the same resource, it might send along a header\nsuch as either If-modified-since or\nIf-unmodified-since, containing the date of the last\nmodification time it was sent, or either If-match or\nIf-none-match, containing the last ETag it was\nsent. If the current version of the page matches the ETag sent by the\nclient, or if the resource has not been modified, a 304 status code can be sent\nback, instead of a full response, telling the client that nothing has changed.\nDepending on the header, if the page has been modified or does not match the\nETag sent by the client, a 412 status code (Precondition Failed) may be\nreturned.
When you need more fine-grained control you may use per-view conditional\nprocessing functions.
\ncondition decoratorLink para este cabeçalho#Sometimes (in fact, quite often) you can create functions to rapidly compute\nthe ETag value or the last-modified time for a\nresource, without needing to do all the computations needed to construct\nthe full view. Django can then use these functions to provide an\n“early bailout” option for the view processing. Telling the client that the\ncontent has not been modified since the last request, perhaps.
\nThese two functions are passed as parameters to the\ndjango.views.decorators.http.condition decorator. This decorator uses\nthe two functions (you only need to supply one, if you can’t compute both\nquantities easily and quickly) to work out if the headers in the HTTP request\nmatch those on the resource. If they don’t match, a new copy of the resource\nmust be computed and your normal view is called.
The condition decorator’s signature looks like this:
condition(etag_func=None, last_modified_func=None)\nThe two functions, to compute the ETag and the last modified time, will be\npassed the incoming request object and the same parameters, in the same\norder, as the view function they are helping to wrap. The function passed\nlast_modified_func should return a standard datetime value specifying the\nlast time the resource was modified, or None if the resource doesn’t\nexist. The function passed to the etag decorator should return a string\nrepresenting the ETag for the resource, or None\nif it doesn’t exist.
The decorator sets the ETag and Last-Modified headers on the response\nif they are not already set by the view and if the request’s method is safe\n(GET or HEAD).
Using this feature usefully is probably best explained with an example.\nSuppose you have this pair of models, representing a small blog system:
\nimport datetime\nfrom django.db import models\n\nclass Blog(models.Model):\n ...\n\nclass Entry(models.Model):\n blog = models.ForeignKey(Blog, on_delete=models.CASCADE)\n published = models.DateTimeField(default=datetime.datetime.now)\n ...\nIf the front page, displaying the latest blog entries, only changes when you\nadd a new blog entry, you can compute the last modified time very quickly. You\nneed the latest published date for every entry associated with that blog.\nOne way to do this would be:
def latest_entry(request, blog_id):\n return Entry.objects.filter(blog=blog_id).latest("published").published\nYou can then use this function to provide early detection of an unchanged page\nfor your front page view:
\nfrom django.views.decorators.http import condition\n\n@condition(last_modified_func=latest_entry)\ndef front_page(request, blog_id):\n ...\nAs a general rule, if you can provide functions to compute both the ETag and\nthe last modified time, you should do so. You don’t know which headers any\ngiven HTTP client will send you, so be prepared to handle both. However,\nsometimes only one value is easy to compute and Django provides decorators\nthat handle only ETag or only last-modified computations.
\nThe django.views.decorators.http.etag and\ndjango.views.decorators.http.last_modified decorators are passed the same\ntype of functions as the condition decorator. Their signatures are:
etag(etag_func)\nlast_modified(last_modified_func)\nWe could write the earlier example, which only uses a last-modified function,\nusing one of these decorators:
\n@last_modified(latest_entry)\ndef front_page(request, blog_id):\n ...\n…or:
\ndef front_page(request, blog_id):\n ...\nfront_page = last_modified(latest_entry)(front_page)\ncondition when testing both conditionsLink para este cabeçalho#It might look nicer to some people to try and chain the etag and\nlast_modified decorators if you want to test both preconditions. However,\nthis would lead to incorrect behavior.
# Bad code. Don't do this!\n@etag(etag_func)\n@last_modified(last_modified_func)\ndef my_view(request):\n # ...\n\n# End of bad code.\nThe first decorator doesn’t know anything about the second and might\nanswer that the response is not modified even if the second decorators would\ndetermine otherwise. The condition decorator uses both callback functions\nsimultaneously to work out the right action to take.
The condition decorator is useful for more than only GET and\nHEAD requests (HEAD requests are the same as GET in this\nsituation). It can also be used to provide checking for POST,\nPUT and DELETE requests. In these situations, the idea isn’t to return\na “not modified” response, but to tell the client that the resource they are\ntrying to change has been altered in the meantime.
For example, consider the following exchange between the client and server:
\nClient requests /foo/.
Server responds with some content with an ETag of "abcd1234".
Client sends an HTTP PUT request to /foo/ to update the\nresource. It also sends an If-Match: "abcd1234" header to specify\nthe version it is trying to update.
Server checks to see if the resource has changed, by computing the ETag\nthe same way it does for a GET request (using the same function).\nIf the resource has changed, it will return a 412 status code,\nmeaning “precondition failed”.
Client sends a GET request to /foo/, after receiving a 412\nresponse, to retrieve an updated version of the content before updating\nit.
The important thing this example shows is that the same functions can be used\nto compute the ETag and last modification values in all situations. In fact,\nyou should use the same functions, so that the same values are returned\nevery time.
\n\nDjango provides conditional GET handling via\ndjango.middleware.http.ConditionalGetMiddleware. While being suitable\nfor many situations, the middleware has limitations for advanced usage:
It’s applied globally to all views in your project.
It doesn’t save you from generating the response, which may be expensive.
It’s only appropriate for HTTP GET requests.
You should choose the most appropriate tool for your particular problem here.\nIf you have a way to compute ETags and modification times quickly and if some\nview takes a while to generate the content, you should consider using the\ncondition decorator described in this document. If everything already runs\nfairly quickly, stick to using the middleware and the amount of network\ntraffic sent back to the clients will still be reduced if the view hasn’t\nchanged.