リクエストとレスポンスのオブジェクト¶
簡単な概要¶
Django は、システムを通じてステータスを渡すために、リクエストとレスポンスのオブジェクトを使います。
あるページがリクエストされたとき、Django はリクエストに関するメタデータを含んだ HttpRequest
オブジェクトを生成します。それから Django は HttpRequest
をビュー関数の最初の関数として渡し、適切なビューを読み込みます。あらゆるビューは HttpResponse
オブジェクトを返す必要があります。
このドキュメントでは、HttpRequest
と HttpResponse
オブジェクトの API を説明しています。これは django.http
モジュールにて定義されています。
HttpRequest
オブジェクト¶
属性¶
特に記載がない限り、全ての属性は読み取り専用だと考えてください。
-
HttpRequest.
body
[ソース]¶ 生の HTTP リクエストボディをバイト文字列として。これは、従来の HTML フォームとは異なる方法でデータを処理するのに便利です:バイナリイメージ、XML ペイロードなど。従来のフォームデータを処理する場合は、
HttpRequest.POST
を使用してください。HttpRequest.read()
やHttpRequest.readline()
を用いて、ファイルのようなインタフェースからHttpRequest
を読み取ることもできます。これらの I/O ストリームメソッドを用いてリクエストを読み取った 後にbody
属性にアクセスすると、RawPostDataException
が発生します。
-
HttpRequest.
path
¶ 要求されたページへのフルパスを表す文字列であり、scheme、ドメイン、クエリ文字列は含みません。
例:
"/music/bands/the_beatles/"
-
HttpRequest.
path_info
¶ 一部のWebサーバー構成では、ホスト名の後のURLがスクリプトプレフィックス部分とパス情報部分に分割されます。
path_info
属性は、使用されるWebサーバーに関わらず常にパス情報部分を含んでいます。これをpath
の代わりに使用することで、テストサーバーとデプロイメントサーバー間でコードを移動させやすくなります。たとえば、アプリケーションの
WSGIScriptAlias
が"/minfo"
に設定されている場合、path
が"/minfo/music/bands/the_beatles/"
である一方、path_info
は"/music/bands/the_beatles/"
となる可能性があります。
-
HttpRequest.
method
¶ リクエストで使用された HTTP メソッドを表す文字列です。この値は常に大文字となることが保証されています。たとえば、次のようになります。
if request.method == "GET": do_something() elif request.method == "POST": do_something_else()
-
HttpRequest.
encoding
[ソース]¶ フォーム提出データをデコードする際に使用されている現在のエンコーディングを表す文字列(または
None
で、これはDEFAULT_CHARSET
設定が使用されることを意味します)。この属性に書き込むことで、フォームデータにアクセスする際に使用されるエンコーディングを変更できます。その後の属性アクセス(GET
やPOST
からの読み取りなど)は、新しいencoding
値を使用します。フォームデータがDEFAULT_CHARSET
エンコーディングでないことがわかっている場合に便利です。
-
HttpRequest.
content_type
¶ リクエストの MIME タイプを表す文字列です。
CONTENT_TYPE
から識別されます。
-
HttpRequest.
content_params
¶ CONTENT_TYPE
ヘッダに含まれる、キーと値のパラーメータのディクショナリです。
-
HttpRequest.
POST
¶ リクエストにフォームデータが含まれている場合に、すべての与えられた HTTP POST パラメータを含む辞書のようなオブジェクト。以下の
QueryDict
ドキュメントを参照してください。リクエストにポストされた生のデータや非フォームデータにアクセスする必要がある場合は、代わりにHttpRequest.body
属性を通じてアクセスしてください。POST メソッドでフォームデータが含まれていない場合に、空の
POST
ディクショナリを備えたリクエストが発生する可能性があります。そのため、POST メソッドの使用を確認するためにif request.POST
を使用すべきではありません。代わりに、if request.method == "POST"
を使用してください (HttpRequest.method
を参照)。POST
には file-upload の情報が含まれ ません 。詳しくはFILES
を参照してください。
-
HttpRequest.
COOKIES
¶ すべてのクッキーが格納されたディクショナリです。キーと値は文字列です。
-
HttpRequest.
FILES
¶ FILES
は、アップロードされた全てのファイルを含む辞書型のオブジェクトです。FILES
の各キーは<input type="file" name="">
のname
から成ります。FILES
の各値はUploadedFile
です。詳細については、ファイルの管理 を参照してください。
FILES
には、リクエストメソッドが POST で、リクエストに投稿した<form>
にenctype="multipart/form-data"
が設定されていた場合にのみデータが含まれます。それ以外の場合、FILES
は空の辞書のようなオブジェクトになります。
-
HttpRequest.
META
¶ 利用できるすべての HTTP ヘッダーが格納されたディクショナリです。利用可能なヘッダーはクライアントとサーバーによって異なりますが、以下に例を示します。
CONTENT_LENGTH
-- リクエスト本文の (文字列としての) 長さです。CONTENT_TYPE
-- リクエスト本文の MIME タイプです。HTTP_ACCEPT
-- レスポンスに対して受け入れ可能なコンテンツのタイプです。HTTP_ACCEPT_ENCODING
-- レスポンスに対して受け入れ可能なエンコーディングです。HTTP_ACCEPT_LANGUAGE
-- レスポンスに対して受け入れ可能な言語です。HTTP_HOST
-- クライアントによって送信された HTTP Host ヘッダです。HTTP_REFERER
-- (存在する場合) リファラページです。HTTP_USER_AGENT
-- クライアントのユーザエージェント文字列です。QUERY_STRING
-- クエリ文字列で、単一の (未解析の) 文字列です。REMOTE_ADDR
-- クライアントの IP アドレスです。REMOTE_HOST
-- クライアントのホスト名です。REMOTE_USER
-- ウェブサーバーによって認証されたユーザー(もしあれば)。REQUEST_METHOD
--"GET"
や"POST"
といったです。SERVER_NAME
-- サーバのホスト名です。SERVER_PORT
-- (文字列としての) サーバのポートです。
上記の
CONTENT_LENGTH
とCONTENT_TYPE
を除き、リクエストの HTTP ヘッダーは、すべての文字を大文字に変換し、ハイフンをアンダースコアに置き換え、名前にHTTP_
プレフィックスを追加することでMETA
キーに変換されます。たとえば、X-Bender
というヘッダーはMETA
キーHTTP_X_BENDER
にマッピングされます。runserver
では、名前にアンダースコアを含むヘッダーはすべて削除されるため、META
にそれらが表示されません。これにより、WSGI 環境変数内のアンダースコアとダッシュの曖昧さに基づくヘッダー・スプーフィングが防がれます。この動作は、Nginx や Apache 2.4+ のようなウェブサーバーと一致しています。HttpRequest.headers
はCONTENT_LENGTH
とCONTENT_TYPE
を含む、全てのHTTPプレフィックス付きヘッダーにアクセスするより簡単な方法です。
-
HttpRequest.
headers
[ソース]¶ リクエストからHTTPプリフィックスヘッダー全体 (
Content-Length
とContent-Type
を含む) にアクセスを提供する、大文字小文字を区別しない辞書風オブジェクトです。各ヘッダーの名前は、表示される際にタイトルケース (例:
User-Agent
) でスタイリズされます。ヘッダーは大文字小文字を区別せずにアクセスできます。>>> request.headers {'User-Agent': 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_12_6', ...} >>> "User-Agent" in request.headers True >>> "user-agent" in request.headers True >>> request.headers["User-Agent"] Mozilla/5.0 (Macintosh; Intel Mac OS X 10_12_6) >>> request.headers["user-agent"] Mozilla/5.0 (Macintosh; Intel Mac OS X 10_12_6) >>> request.headers.get("User-Agent") Mozilla/5.0 (Macintosh; Intel Mac OS X 10_12_6) >>> request.headers.get("user-agent") Mozilla/5.0 (Macintosh; Intel Mac OS X 10_12_6)
たとえば Django テンプレートでの使用において、ヘッダーはハイフンの代わりにアンダースコアを使用してもルックアップできます。
{{ request.headers.user_agent }}
-
HttpRequest.
resolver_match
¶ 解決されたURLを表す
ResolverMatch
のインスタンスです。この属性は、URLの解決が行われた後にのみ設定されます。つまり、全てのビューで利用可能ですが、URLの解決が行われる前に実行されるミドルウェアでは利用できません (process_view()
では使用できます)。
アプリケーションコードがセットする属性¶
Django はこれらの属性を自分で設定することはありませんが、アプリケーション側で設定された場合にはその値を利用します。
-
HttpRequest.
urlconf
¶ この値は、現在のリクエストに対する root URLconf として使用され、設定の
ROOT_URLCONF
を上書きします。詳しくは Django のリクエスト処理 を参照してください。urlconf
はNone
に設定することで、それまでにミドルウェアで行われた変更を取り消し、元のROOT_URLCONF
を使用するようにできます。
-
HttpRequest.
exception_reporter_filter
¶ これは、現在のリクエストに対して
DEFAULT_EXCEPTION_REPORTER_FILTER
の代わりに使用されます。詳細については、 カスタムエラーレポート を参照してください。
-
HttpRequest.
exception_reporter_class
¶ これは、現在のリクエストに対して
DEFAULT_EXCEPTION_REPORTER
の代わりに使用されます。詳細については カスタムエラーレポート を参照してください。
ミドルウェアが設定する属性¶
Django の contrib アプリなどのミドルウェアの一部は、リクエストに属性を設定します。もし、リクエストに属性が設定されていない場合は、MIDDLEWARE
リスト中に適切なミドルウェアが含まれているかを確認してください。
-
HttpRequest.
session
¶ SessionMiddleware
は、現在のセッションを表す、読み書き可能でディクショナリライクなオブジェクトを設定します。
-
HttpRequest.
site
¶ CurrentSiteMiddleware
は、現在のサイトを表すSite
またはRequestSite
のインスタンスを、get_current_site()
の返り値で設定します。
-
HttpRequest.
user
¶ AuthenticationMiddleware
から: 現在ログインしているユーザーを表すAUTH_USER_MODEL
のインスタンスです。ユーザーが現在ログインしていない場合、user
はAnonymousUser
のインスタンスに設定されます。is_authenticated
を使用して、それらを区別できます。例えば、こうです:if request.user.is_authenticated: ... # Do something for logged-in users. else: ... # Do something for anonymous users.
auser()
メソッドは同じ機能を提供しますが、非同期コンテキストから使用できます。
メソッド¶
-
HttpRequest.
auser
()¶ - New in Django 5.0.
AuthenticationMiddleware
から: コルーチン。現在ログインしているユーザーを表すAUTH_USER_MODEL
のインスタンスを返します。もしユーザーが現在ログインしていない場合、auser
はAnonymousUser
のインスタンスを返します。これはuser
属性に似ていますが、非同期コンテキストでも機能します。
-
HttpRequest.
get_host
()[ソース]¶ リクエストの発信元ホストを返します。この情報は、順番に
HTTP_X_FORWARDED_HOST
(もしUSE_X_FORWARDED_HOST
が有効な場合) およびHTTP_HOST
ヘッダーから取得されます。これらが値を提供しない場合、メソッドはSERVER_NAME
とSERVER_PORT
の組み合わせを使用します。詳細は PEP 3333 で説明されています。例:
"127.0.0.1:8000"
ホストが
ALLOWED_HOSTS
にないか、ドメイン名が RFC 1034/1035 に従っていない場合、django.core.exceptions.DisallowedHost
を発生させます。注釈
get_host()
メソッドは、ホストが複数のプロキシの背後にある場合に失敗します。一つの解決策として、以下の例に示すように、プロキシのヘッダーを書き換えるためのミドルウェアを使用できます:class MultipleProxyMiddleware: FORWARDED_FOR_FIELDS = [ "HTTP_X_FORWARDED_FOR", "HTTP_X_FORWARDED_HOST", "HTTP_X_FORWARDED_SERVER", ] def __init__(self, get_response): self.get_response = get_response def __call__(self, request): """ Rewrites the proxy headers so that only the most recent proxy is used. """ for field in self.FORWARDED_FOR_FIELDS: if field in request.META: if "," in request.META[field]: parts = request.META[field].split(",") request.META[field] = parts[-1].strip() return self.get_response(request)
このミドルウェアは、
get_host()
の値に依存する他のミドルウェアよりも前に配置されるべきです (例えば、CommonMiddleware
やCsrfViewMiddleware
など)。
-
HttpRequest.
get_port
()[ソース]¶ リクエストの元となったポートを、
HTTP_X_FORWARDED_PORT
とSERVER_PORT
のMETA
変数から、その順に使用して情報を取得し返します (ただし、USE_X_FORWARDED_PORT
が有効になっている場合)。
-
HttpRequest.
get_full_path
()[ソース]¶ 必要に応じて、
path
にクエリ文字列を追加して返します。例:
"/music/bands/the_beatles/?print=true"
-
HttpRequest.
get_full_path_info
()[ソース]¶ get_full_path()
と似ていますが、path
の代わりにpath_info
を使用します。例:
"/minfo/music/bands/the_beatles/?print=true"
-
HttpRequest.
build_absolute_uri
(location=None)[ソース]¶ location
の絶対URI形式を返します。もし location が指定されていない場合、request.get_full_path()
が location に設定されます。もし場所がすでに絶対 URI である場合、それは変更されません。そうでない場合、このリクエストで利用可能なサーバ変数を使用して絶対 URI が構築されます。例えば:
>>> request.build_absolute_uri() 'https://example.com/music/bands/the_beatles/?print=true' >>> request.build_absolute_uri("/bands/") 'https://example.com/bands/' >>> request.build_absolute_uri("https://example2.com/bands/") 'https://example2.com/bands/'
注釈
同一サイト上でHTTPとHTTPSを混在させることは推奨されません。そのため、
build_absolute_uri()
は常に、現在のリクエストと同じスキームを持つ絶対URIを生成します。ユーザーをHTTPSにリダイレクトする必要がある場合は、WebサーバーにすべてのHTTPトラフィックをHTTPSにリダイレクトさせるのが最善です。
-
HttpRequest.
get_signed_cookie
(key, default=RAISE_ERROR, salt='', max_age=None)[ソース]¶ 署名付きクッキーの値を返します。署名が無効である場合は
django.core.signing.BadSignature
例外が発生します。default
引数を提供した場合、例外は抑制され、代わりにそのデフォルト値が返されます。オプションの
salt
引数は、秘密鍵への総当たり攻撃から保護するために使用できます。指定された場合、max_age
引数は、クッキー値に付加された署名付きタイムスタンプと比較して、クッキーがmax_age
秒より古くないことを確認します。例:
>>> request.get_signed_cookie("name") 'Tony' >>> request.get_signed_cookie("name", salt="name-salt") 'Tony' # assuming cookie was set using the same salt >>> request.get_signed_cookie("nonexistent-cookie") KeyError: 'nonexistent-cookie' >>> request.get_signed_cookie("nonexistent-cookie", False) False >>> request.get_signed_cookie("cookie-that-was-tampered-with") BadSignature: ... >>> request.get_signed_cookie("name", max_age=60) SignatureExpired: Signature age 1677.3839159 > 60 seconds >>> request.get_signed_cookie("name", False, max_age=60) False
詳細については、 暗号署名 を参照してください。
-
HttpRequest.
accepts
(mime_type)[ソース]¶ リクエストの
Accept
ヘッダーがmime_type
引数と一致する場合にTrue
を返します。>>> request.accepts("text/html") True
ほとんどのブラウザはデフォルトで
Accept: */*
を送信するため、これはすべてのコンテンツタイプに対してTrue
を返します。APIリクエストに明示的なAccept
ヘッダーを設定することは、それらの利用者のみに異なるコンテンツタイプを返すために役立ちます。APIの利用者に異なるコンテントを返すためのaccepts()
の使用例については、 コンテンツネゴシエーションの例 を参照してください。レスポンスが
Accept
ヘッダーの内容によって変わる場合、 Django のキャッシュミドルウェア
などのキャッシュ形式を使用している場合は、レスポンスが適切にキャッシュされるように、ビューをvary_on_headers('Accept')
でデコレートする必要があります。
-
HttpRequest.
__iter__
()[ソース]¶ HttpRequest
インスタンスから読み取るためのファイルライクなインターフェースを実装するメソッドです。これにより、着信リクエストをストリーミング形式で消費することが可能になります。一般的な使用例は、大きなXMLペイロードをメモリ内で完全なXMLツリーを構築することなく、繰り返しパーサーで処理する場合です。この標準インターフェースを用いると、
HttpRequest
インスタンスはElementTree
のようなXMLパーサーに直接渡すことができます。import xml.etree.ElementTree as ET for element in ET.iterparse(request): process(element)
QueryDict
オブジェクト¶
HttpRequest
オブジェクト内では、GET
と POST
属性は django.http.QueryDict
のインスタンスです。これは、同一のキーに対する複数の値を扱うためにカスタマイズされた、辞書型に似たクラスです。これが必要なのは、いくつかの HTML (特に <select multiple>
) が同一キーで複数の値を渡すからです。
request.POST
や request.GET
の QueryDict
は、通常の request/response 内でアクセスするときには編集不可です。編集可能なものを取得するには、QueryDict.copy()
を使う必要があります。
メソッド¶
QueryDict
はディクショナリのサブクラスなので、標準的なディクショナリのメソッドを全て実装しています。当てはまらないのはおおむね以下の通りです:
-
QueryDict.
__init__
(query_string=None, mutable=False, encoding=None)[ソース]¶ QueryDict
に基づいてQueryDict
オブジェクトをインスタンス化します。>>> QueryDict("a=1&a=2&c=3") <QueryDict: {'a': ['1', '2'], 'c': ['3']}>
query_string
が渡されなかった場合は、QueryDict
空となります (何のキーや値も持ちません)。使用する
QueryDict
のほとんど、特にrequest.POST
やrequest.GET
における場合、編集不可となっています。自分でインスタンスを生成する場合は、__init__()
にmutable=True
を渡すことで編集可能にできます。キーとバリューの両方を設定するための文字列は、
encoding
からstr
に変換されます。encoding
がセットされていない場合、DEFAULT_CHARSET
がデフォルトとなります。
-
classmethod
QueryDict.
fromkeys
(iterable, value='', mutable=False, encoding=None)[ソース]¶ 新しい
QueryDict
を作成します。キーはiterable
で、各値はvalue
になります。例えば:>>> QueryDict.fromkeys(["a", "a", "b"], value="val") <QueryDict: {'a': ['val', 'val'], 'b': ['val']}>
-
QueryDict.
__getitem__
(key)¶ 指定したキーに対する値を返します。キーが複数の値を持つ場合、最後の値を返します。キーが存在しない場合は
django.utils.datastructures.MultiValueDictKeyError
を発生させます (これは Python の標準的なKeyError
サブクラスなので、KeyError
をキャッチすることに固執できます)。
-
QueryDict.
__setitem__
(key, value)[ソース]¶ 指定したキーを
[value]
(各要素がvalue
のリスト) にセットします。 副作用を持つ他のディクショナリ関数と同様に、編集可能なQueryDict
(QueryDict.copy()
で作成されたものなど) のみで呼び出し可能です.
-
QueryDict.
__contains__
(key)¶ 指定したキーがセットされている場合
True
を返します。例えばif "foo" in request.GET
を実行するのと同じです。
-
QueryDict.
get
(key, default=None)¶ __getitem__()
と同じロジックを使いますが、キーが存在しない場合のデフォルト値をフックします。
-
QueryDict.
setdefault
(key, default=None)[ソース]¶ dict.setdefault()
に似ていますが、内部では__setitem__()
を使用します。
-
QueryDict.
update
(other_dict)¶ QueryDict
または辞書のどちらかを取ります。dict.update()
と似ていますが、現在の辞書の項目を置き換えるのではなく 追加 します。例えば:>>> q = QueryDict("a=1", mutable=True) >>> q.update({"a": "2"}) >>> q.getlist("a") ['1', '2'] >>> q["a"] # returns the last '2'
-
QueryDict.
items
()¶ dict.items()
と似ていますが、これは__getitem__()
と同じ最後の値のロジックを使用し、ビューオブジェクトの代わりにイテレータオブジェクトを返します。例えば:>>> q = QueryDict("a=1&a=2&a=3") >>> list(q.items()) [('a', '3')]
-
QueryDict.
values
()¶ dict.values()
のように、__getitem__()
と同じ最後の値のロジックを使用しますが、ビューオブジェクトの代わりにイテレータを返します。例えば:>>> q = QueryDict("a=1&a=2&a=3") >>> list(q.values()) ['3']
加えて、QueryDict
は以下のメソッドを持ちます:
-
QueryDict.
copy
()[ソース]¶ copy.deepcopy()
を使用してオブジェクトのコピーを返します。このコピーは、元のオブジェクトがイミュータブルであったとしても、ミュータブルです。
-
QueryDict.
getlist
(key, default=None)¶ リクエストされたキーのデータのリストを返します。キーが存在しない場合には、
default
がNone
であれば空のリストを返します。デフォルト値がリストでない限り、リストを返すことが保証されています。
-
QueryDict.
setlist
(key, list_)[ソース]¶ 指定されたキーを
list_
に設定します (__setitem__()
と異なります)。
-
QueryDict.
setlistdefault
(key, default_list=None)[ソース]¶ setdefault()
に似ていますが、単一の値の代わりに値のリストを取ります。
-
QueryDict.
lists
()¶ items()
に似ていますが、辞書の各メンバーに対して、すべての値をリストとして含んでいます。例えば:>>> q = QueryDict("a=1&a=2&a=3") >>> q.lists() [('a', ['1', '2', '3'])]
-
QueryDict.
pop
(key)[ソース]¶ 指定されたキーに対応する値のリストを返し、それらを辞書から削除します。キーが存在しない場合は
KeyError
を発生させます。例えば:>>> q = QueryDict("a=1&a=2&a=3", mutable=True) >>> q.pop("a") ['1', '2', '3']
-
QueryDict.
popitem
()[ソース]¶ 辞書の任意のメンバーを削除し (順序の概念がないため)、キーとキーに対するすべての値のリストを含む2値タプルを返します。空の辞書に対して呼び出されると
KeyError
を発生させます。例えば:>>> q = QueryDict("a=1&a=2&a=3", mutable=True) >>> q.popitem() ('a', ['1', '2', '3'])
-
QueryDict.
dict
()¶ QueryDict
の各(key, list)ペアに対して、dict
形式の表現を返します。dict
は、リストの中の要素の1つである item に対して、(key, item) のペアを持ちます。これは、QueryDict.__getitem__()
と同じロジックを使用します。>>> q = QueryDict("a=1&a=3&a=5") >>> q.dict() {'a': '5'}
HttpResponse
オブジェクト¶
Django によって自動的に生成される HttpRequest
オブジェクトとは対照的に、HttpResponse
オブジェクトの作成はあなたの責任です。プログラム内に記述されるあらゆるビューは、HttpResponse
をインスタンス化し、データを格納して返す必要があります。
HttpResponse
クラスは django.http
モジュール内に存在します。
使い方¶
文字列を渡す¶
一般的な使い方としては、ページのコンテンツを文字列、バイト文字列、または memoryview
として、 HttpResponse
コンストラクタに渡します。
>>> from django.http import HttpResponse
>>> response = HttpResponse("Here's the text of the web page.")
>>> response = HttpResponse("Text only, please.", content_type="text/plain")
>>> response = HttpResponse(b"Bytestrings are also accepted.")
>>> response = HttpResponse(memoryview(b"Memoryview as well."))
しかし、内容を段階的に追加したい場合は、 response
をファイルライクオブジェクトとして使用できます:
>>> response = HttpResponse()
>>> response.write("<p>Here's the text of the web page.</p>")
>>> response.write("<p>Here's another paragraph.</p>")
イテレータを渡す¶
最後に、文字列ではなくイテレータを HttpResponse
に渡すこともできます。 HttpResponse
はイテレータを即座に受け取り、その内容を文字列として保存し、破棄します。ファイルやジェネレータのような close()
メソッドを持つオブジェクトは、すぐに閉じられます。
レスポンスに対して、イテレータからクライアントにストリーミングさせる必要がある場合には、代わりに StreamingHttpResponse
クラスを使う必要があります。
ヘッダーフィールドをセットする¶
レスポンスでヘッダーフィールドを設定または削除するには、 HttpResponse.headers
を使用してください。
>>> response = HttpResponse()
>>> response.headers["Age"] = 120
>>> del response.headers["Age"]
レスポンスを辞書のように扱うことで、ヘッダーを操作することもできます:
>>> response = HttpResponse()
>>> response["Age"] = 120
>>> del response["Age"]
これは HttpResponse.headers
へのプロキシで、 HttpResponse
が提供する本来のインタフェースです。
このインターフェースを使用する際、辞書とは異なり、ヘッダーフィールドが存在しない場合に del
が KeyError
を発生させることはありません。
インスタンス化の際にもヘッダーを設定できます:
>>> response = HttpResponse(headers={"Age": 120})
Cache-Control
および Vary
ヘッダーフィールドを設定するには、これらのフィールドが複数のカンマ区切りの値を持ち得るため、 django.utils.cache
から patch_cache_control()
と patch_vary_headers()
メソッドを使用することが推奨されます。"patch" メソッドは、ミドルウェアによって追加された他の値が削除されないように保証します。
HTTP ヘッダフィールドには改行を含めることはできません。改行文字 (CR または LF) を含むヘッダフィールドを設定しようとすると、BadHeaderError
が発生します。
レスポンスをファイル添付物として扱うようにブラウザに指示します。¶
ブラウザにレスポンスをファイル添付として扱うように指示するためには、Content-Type
と Content-Disposition
ヘッダを設定します。例えば、Microsoft Excel スプレッドシートを返す方法は以下のようになります:
>>> response = HttpResponse(
... my_data,
... headers={
... "Content-Type": "application/vnd.ms-excel",
... "Content-Disposition": 'attachment; filename="foo.xls"',
... },
... )
Content-Disposition
ヘッダについては Django 固有のものはありませんが、その構文を忘れやすいので、ここに含めています。
属性¶
-
HttpResponse.
cookies
¶ レスポンスに含まれるクッキーを保持する
http.cookies.SimpleCookie
オブジェクトです。
-
HttpResponse.
headers
¶ 大文字小文字を区別しない辞書型オブジェクトで、
Set-Cookie
ヘッダを除くすべてのHTTPヘッダに対するインターフェイスを提供します。 ヘッダーフィールドをセットする およびHttpResponse.cookies
を参照してください。
-
HttpResponse.
charset
¶ 応答がエンコードされる文字セットを示す文字列です。
HttpResponse
のインスタンス化の際に指定されなかった場合、content_type
から抽出され、もしこれが失敗した場合は、DEFAULT_CHARSET
設定が使用されます。
-
HttpResponse.
status_code
¶ レスポンスの HTTP ステータスコード 。
reason_phrase
が明示的にセットされていない限り、コンストラクタの外でstatus_code
の値を変更するとreason_phrase
の値も変更されます。
-
HttpResponse.
reason_phrase
¶ レスポンスの HTTP reason フレーズです。これは HTTP 標準の デフォルトの reason フレーズを使用します。
reason_phrase
が明示的に設定されていない場合、status_code
の値に基づいて決定されます。
-
HttpResponse.
streaming
¶ これは常に
False
です。この属性は、ミドルウェアが通常のレスポンスとは違う形でストリーミングレスポンスを扱えるようにするために存在しています。
-
HttpResponse.
closed
¶ レスポンスが閉じられた場合、
True
となります。
メソッド¶
-
HttpResponse.
__init__
(content=b'', content_type=None, status=200, reason=None, charset=None, headers=None)[ソース]¶ 指定されたページ内容、コンテンツタイプ、およびヘッダーを持つ
HttpResponse
オブジェクトをインスタンス化します。content
は、最も一般的にはイテレータ、バイト文字列、memoryview
、または文字列です。その他の型は、文字列表現をエンコードしてバイト文字列に変換されます。イテレータは文字列またはバイト文字列を返すべきで、それらはレスポンスの内容を形成するために連結されます。content_type
は、MIME タイプであり、オプションで文字セットエンコーディングを指定して HTTPContent-Type
ヘッダを埋めるために使用されます。指定されていない場合、デフォルトでは'text/html'
とDEFAULT_CHARSET
設定によって形成されます: つまり"text/html; charset=utf-8"
。status
はレスポンスの HTTPステータスコード です。Python のhttp.HTTPStatus
を使用して、HTTPStatus.NO_CONTENT
のような意味のあるエイリアスを使用できます。reason
は HTTP レスポンスフレーズです。指定しない場合、デフォルトのフレーズが使用されます。charset
は、レスポンスがエンコードされる文字セットです。もし指定されていない場合、content_type
から抽出されます。それが失敗した場合は、DEFAULT_CHARSET
設定が使用されます。headers
はレスポンス用のHTTPヘッダーのdict
です。
-
HttpResponse.
__setitem__
(header, value)¶ 指定されたヘッダ名に指定された値を設定します。
header
とvalue
は共に文字列であるべきです。
-
HttpResponse.
__delitem__
(header)¶ 指定された名前のヘッダーを削除します。ヘッダーが存在しなくても、静かに失敗します。大文字小文字を区別しません。
-
HttpResponse.
__getitem__
(header)¶ 指定されたヘッダ名の値を返します。大文字小文字を区別しません。
-
HttpResponse.
get
(header, alternate=None)¶ 指定されたヘッダーの値を返します。ヘッダーが存在しない場合は、
alternate
を返します。
-
HttpResponse.
has_header
(header)¶ 指定された名前のヘッダーが存在するかどうかを大文字小文字を区別せずにチェックし、
True
またはFalse
を返します。
-
HttpResponse.
items
()¶ レスポンスのHTTPヘッダに対して、
dict.items()
のように動作します。
-
HttpResponse.
setdefault
(header, value)¶ ヘッダーがまだ設定されていない場合に、ヘッダーを設定します。
-
HttpResponse.
set_cookie
(key, value='', max_age=None, expires=None, path='/', domain=None, secure=False, httponly=False, samesite=None)¶ クッキーを設定します。パラメータは、Python標準ライブラリ内の
Morsel
クッキーオブジェクトと同じです。max_age
はtimedelta
オブジェクト、整数秒数、またはNone
(デフォルト) である必要があります。これにより、クッキーの有効期限はクライアントのブラウザセッションが終了するまでとなります。expires
が指定されていない場合は自動的に計算されます。expires
は、"Wdy, DD-Mon-YY HH:MM:SS GMT"
形式の文字列か、UTCのdatetime.datetime
オブジェクトであるべきです。もしexpires
がdatetime
オブジェクトである場合、max_age
が計算されます。クロスドメインのクッキーを設定したい場合は、
domain
を使用してください。例えば、domain="example.com"
とすると、www.example.com、blog.example.com などのドメインから読み取れるクッキーが設定されます。そうでない場合、クッキーは設定したドメインのみから読み取れます。secure=True
を使用すると、リクエストがhttps
スキームで行われた場合にのみ、クッキーがサーバーに送信されるようになります。クライアントサイドのJavaScriptがクッキーにアクセスするのを防ぎたい場合は、
httponly=True
を使用してください。HttpOnly は、Set-Cookie HTTP レスポンスヘッダーに含まれるフラグです。これは、クッキーの RFC 6265 標準の一部であり、クライアントサイドのスクリプトが保護されたクッキーデータにアクセスするリスクを軽減する有用な方法です。
samesite='Strict'
やsamesite='Lax'
を使用して、ブラウザにクロスオリジンリクエストを行う際にこのクッキーを送信しないよう指示します。 SameSite はすべてのブラウザに対応しているわけではないため、DjangoのCSRF保護の代わりとなるものではありませんが、防御の深度を増すための措置です。samesite='None'
(文字列) を使えば、このクッキーが同一サイトおよびクロスサイトのすべてのリクエストに送信されることを明示できます。
警告
RFC 6265 には、ユーザーエージェントが少なくとも 4096 バイトのクッキーをサポートすべきであると記されています。多くのブラウザでは、これが最大サイズでもあります。Django は 4096 バイトを超えるクッキーを保存しようとした際に例外を発生させませんが、多くのブラウザでは正しくクッキーを設定しないでしょう。
-
HttpResponse.
set_signed_cookie
(key, value, salt='', max_age=None, expires=None, path='/', domain=None, secure=False, httponly=False, samesite=None)¶ set_cookie()
のように、クッキーを設定する前に 暗号署名 を行います。HttpRequest.get_signed_cookie()
と組み合わせて使用してください。オプショナルなsalt
引数を使用して鍵強度を高めることができますが、対応するHttpRequest.get_signed_cookie()
呼び出しにそれを渡す必要があります。
-
HttpResponse.
delete_cookie
(key, path='/', domain=None, samesite=None)¶ 指定されたキーを持つクッキーを削除します。キーが存在しない場合は、静かに失敗します。
クッキーの動作方法により、
path
とdomain
はset_cookie()
で使用した値と同じでなければなりません。そうでない場合、クッキーが削除されない可能性があります。
-
HttpResponse.
close
()¶ このメソッドは、リクエストの終了時に、WSGIサーバーによって直接呼び出されます。
-
HttpResponse.
write
(content)[ソース]¶ このメソッドは、
HttpResponse
インスタンスをファイルライクオブジェクトにします。
-
HttpResponse.
flush
()¶ このメソッドは、
HttpResponse
インスタンスをファイルライクオブジェクトにします。
-
HttpResponse.
tell
()[ソース]¶ このメソッドは、
HttpResponse
インスタンスをファイルライクオブジェクトにします。
-
HttpResponse.
getvalue
()[ソース]¶ HttpResponse.content
の値を返します。このメソッドにより、HttpResponse
インスタンスはストリームライクオブジェクトになります。
-
HttpResponse.
readable
()¶ 常に
False
です。このメソッドはHttpResponse
インスタンスをストリームライクオブジェクトにします。
-
HttpResponse.
seekable
()¶ 常に
False
です。このメソッドはHttpResponse
インスタンスをストリームライクオブジェクトにします。
-
HttpResponse.
writable
()[ソース]¶ 常に
True
です。このメソッドはHttpResponse
インスタンスをストリームライクオブジェクトにします。
-
HttpResponse.
writelines
(lines)[ソース]¶ レスポンスに行のリストを書き込みます。行区切りは追加されません。このメソッドは、
HttpResponse
インスタンスをストリームライクオブジェクトにします。
HttpResponse
サブクラス¶
Djangoには、異なるタイプのHTTPレスポンスを処理するための HttpResponse
のサブクラスがいくつか含まれています。 HttpResponse
と同様に、これらのサブクラスは django.http
に存在します。
-
class
HttpResponseRedirect
[ソース]¶ コンストラクタには最初の引数が必須です。これはリダイレクト先のパスです。これは完全なURL (例:
'https://www.yahoo.com/search/'
)、ドメインなしの絶対パス (例:'/search/'
)、あるいは相対パス (例:'search/'
) でも構いません。後者の場合、クライアントブラウザが現在のパスに従って完全なURLを自身で再構築します。その他のオプションのコンストラクタ引数については、HttpResponse
を参照してください。この処理はHTTPステータスコード302を返すことに注意してください。-
url
¶ この読み取り専用の属性は、レスポンスがリダイレクトするURLを表しています (
Location
レスポンスヘッダに相当します)。
-
-
class
HttpResponsePermanentRedirect
[ソース]¶ HttpResponseRedirect
に似ていますが、"found" リダイレクト(ステータスコード 302) ではなく、恒久的なリダイレクト(HTTPステータスコード 301) を返します。
-
class
HttpResponseNotModified
[ソース]¶ コンストラクタは引数を取らず、このレスポンスにはコンテンツを追加すべきではありません。これを使用して、ページがユーザーの最後のリクエスト以降に変更されていないことを指定します(ステータスコード304)。
-
class
HttpResponseBadRequest
[ソース]¶ HttpResponse
と似ていますが、ステータスコードとして 400 を使用します。
-
class
HttpResponseNotFound
[ソース]¶ HttpResponse
と似ていますが、404 ステータスコードを使用します。
-
class
HttpResponseForbidden
[ソース]¶ HttpResponse
と似ていますが、403 ステータスコードを使用します。
-
class
HttpResponseNotAllowed
[ソース]¶ HttpResponse
と似ていますが、ステータスコード 405 を使用します。コンストラクタへの最初の引数は必須です: 許可されているメソッドのリスト (例:['GET', 'POST']
)。
-
class
HttpResponseGone
[ソース]¶ HttpResponse
と似ていますが、410 ステータスコードを使用します。
-
class
HttpResponseServerError
[ソース]¶ HttpResponse
と似ていますが、ステータスコードとして 500 を使用します。
注釈
HttpResponse
のカスタムサブクラスが render
メソッドを実装している場合、Djangoはそれを SimpleTemplateResponse
を模倣しているものとして扱い、 render
メソッド自体が有効なレスポンスオブジェクトを返さなければなりません。
カスタムレスポンスクラス¶
Django が提供していないレスポンスクラスが必要になった場合は、http.HTTPStatus
を使用して作成できます。例えば:
from http import HTTPStatus
from django.http import HttpResponse
class HttpResponseNoContent(HttpResponse):
status_code = HTTPStatus.NO_CONTENT
JsonResponse
オブジェクト¶
-
class
JsonResponse
(data, encoder=DjangoJSONEncoder, safe=True, json_dumps_params=None, **kwargs)[ソース]¶ HttpResponse
のサブクラスで、JSONエンコードされたレスポンスを作成するのに役立ちます。このクラスは、いくつかの違いを除き、その基底クラスからほとんどの動作を継承しています:デフォルトの
Content-Type
ヘッダーは application/json に設定されています。最初のパラメーター
data
は、dict
インスタンスであるべきです。safe
パラメーターがFalse
に設定されている場合 (下記参照)、これはどんな JSON シリアライズ可能オブジェクトでも可能です。encoder
のデフォルトはdjango.core.serializers.json.DjangoJSONEncoder
で、このエンコーダーがデータのシリアライズに使用されます。このシリアライザについての詳細は、JSON のシリアライズ を参照してください。safe
ブールパラメータのデフォルト値はTrue
です。もしFalse
に設定されている場合、任意のオブジェクトをシリアライズのために渡すことができます(そうでなければ、dict
インスタンスのみが許可されます)。safe
がTrue
であり、非dict
オブジェクトが第一引数として渡された場合、TypeError
が発生します。json_dumps_params
パラメーターは、レスポンス生成に使用されるjson.dumps()
呼び出しに渡すキーワード引数の辞書です。
使い方¶
一般的な使用方法は以下のようになります:
>>> from django.http import JsonResponse
>>> response = JsonResponse({"foo": "bar"})
>>> response.content
b'{"foo": "bar"}'
辞書以外のオブジェクトのシリアライズ¶
dict
以外のオブジェクトをシリアライズする場合、 safe
パラメータを False
に設定する必要があります:
>>> response = JsonResponse([1, 2, 3], safe=False)
safe=False
を指定しなかった場合、TypeError
が発生します。
dict
オブジェクトに基づいた API は、より拡張性が高く、柔軟性があり、前方互換性の維持が容易になります。したがって、JSON エンコードされたレスポンスでは非 dict オブジェクトの使用は避けるべきです。
警告
ECMAScript 5th edition の前では、JavaScript の Array
コンストラクタに対する侵害が可能でした。この理由から、Django はデフォルトで JsonResponse
コンストラクタに辞書以外のオブジェクトを渡すことを許可しません。ただし、ほとんどの最新ブラウザは ECMAScript 5 を実装しており、この攻撃ベクトルが取り除かれています。したがって、このセキュリティ対策を無効にすることが可能です。
デフォルトのJSONエンコーダーを変更する¶
異なるJSONエンコーダークラスを使用する必要がある場合は、コンストラクターメソッドに encoder
パラメータを渡すことができます。
>>> response = JsonResponse(data, encoder=MyJSONEncoder)
StreamingHttpResponse
オブジェクト¶
StreamingHttpResponse
クラスは、Djangoからブラウザへのレスポンスをストリーミングするために使用されます。
高度な使用法
StreamingHttpResponse
はやや高度です。アプリケーションを WSGI で同期的に、あるいは ASGI で非同期的に提供するかを知り、使用方法を適切に調整することが重要です。
これらの注意点を注意深く読んでください。
WSGI 下での StreamingHttpResponse
の使用例としては、レスポンスの生成に時間がかかりすぎる場合やメモリを大量に使用する場合にコンテンツをストリーミングすることが挙げられます。例えば、大きなCSVファイルを生成する場合 に役立ちます。
しかしながら、これを行う際にはパフォーマンスを考慮する必要があります。WSGIの下でのDjangoは、短期間のリクエストのために設計されています。ストリーミングレスポンスは、レスポンスの全期間にわたってワーカープロセスを占有します。これにより、パフォーマンスが低下する可能性があります。
一般的に、ストリーミングレスポンスに頼るのではなく、リクエスト/レスポンスサイクルの外で高コストのタスクを行うほうが良いです。
しかし、ASGI の下で提供される場合、StreamingHttpResponse
はI/Oを待っている間に他のリクエストが提供されるのを妨げる必要はありません。これにより、ストリーミングコンテンツのための長時間生存するリクエストや、ロングポーリングやサーバー送信イベントといったパターンの実装の可能性が開かれます。
ASGI環境下であっても、StreamingHttpResponse
は、クライアントにデータを転送する前に全内容がイテレートされることが絶対に必要な状況でのみ使用すべきです。コンテンツにアクセスできないため、多くのミドルウェアが正常に機能しません。例えば、ストリーミングレスポンスには ETag
や Content-Length
ヘッダを生成することができません。
StreamingHttpResponse
は、若干異なるAPIを特徴とするため、HttpResponse
のサブクラスではありません。しかし、以下に挙げる顕著な違いを除いて、ほぼ同一です。
コンテンツとしてバイト文字列、
memoryview
、または文字列を生成するイテレータを渡すべきです。WSGI下で提供する場合、これは同期イテレータであるべきです。ASGI下で提供する場合、これは非同期イテレータであるべきです。その内容にアクセスするには、レスポンスオブジェクト自体をイテレートする必要があります。これはクライアントにレスポンスが返されたときのみ発生すべきです。自分でレスポンスをイテレートすべきではありません。
WSGIでは、レスポンスは同期的にイテレートされます。ASGIでは、レスポンスは非同期的にイテレートされます。(これが、イテレータのタイプが使用しているプロトコルと一致しなければならない理由です。)
クラッシュを回避するため、間違ったイテレータのタイプは、イテレート中に正しいタイプにマッピングされ、警告が発生します。ただし、これを行うにはイテレータを完全に消費する必要があり、これは全く
StreamingHttpResponse
を使用する目的を果たしません。これは
content
属性を持ちません。代わりにstreaming_content
属性があります。これはミドルウェアでレスポンスのイテラブルをラップするために使用できますが、消費されるべきではありません。ファイルライクオブジェクトの
tell()
やwrite()
メソッドは使用できません。これらを使用すると例外が発生します。
HttpResponse
と StreamingHttpResponse
は、共通の基底クラス HttpResponseBase
を持っています。
属性¶
-
StreamingHttpResponse.
streaming_content
[ソース]¶ レスポンス内容のイテレータ。 バイト文字列は
HttpResponse.charset
に従ってエンコードされます。
-
StreamingHttpResponse.
status_code
¶ レスポンスの HTTP ステータスコード 。
reason_phrase
が明示的にセットされていない限り、コンストラクタの外でstatus_code
の値を変更するとreason_phrase
の値も変更されます。
-
StreamingHttpResponse.
reason_phrase
¶ レスポンスの HTTP reason フレーズです。これは HTTP 標準の デフォルトの reason フレーズを使用します。
reason_phrase
が明示的に設定されていない場合、status_code
の値に基づいて決定されます。
-
StreamingHttpResponse.
streaming
¶ これは常に
True
です。
-
StreamingHttpResponse.
is_async
¶ StreamingHttpResponse.streaming_content
が非同期イテレータであるかどうかを示す真偽値です。これは、
StreamingHttpResponse.streaming_content
をラップする必要があるミドルウェアにとって便利です。
切断の取り扱い¶
クライアントがストリーミングレスポンス中に切断されると、Django はレスポンスを処理しているコルーチンをキャンセルします。リソースの手動クリーンアップを行いたい場合は、asyncio.CancelledError
をキャッチして行うことができます:
async def streaming_response():
try:
# Do some work here
async for chunk in my_streaming_iterator():
yield chunk
except asyncio.CancelledError:
# Handle disconnect
...
raise
async def my_streaming_view(request):
return StreamingHttpResponse(streaming_response())
この例は、レスポンスがストリーミングされている間にクライアントの切断をどのように処理するかを示しているだけです。ビュー内で StreamingHttpResponse
オブジェクトを返す前に長時間実行される操作を行う場合は、ビュー自体で 切断を処理する 必要があるかもしれません。
FileResponse
オブジェクト¶
-
class
FileResponse
(open_file, as_attachment=False, filename='', **kwargs)[ソース]¶ FileResponse
はバイナリファイルに最適化されたStreamingHttpResponse
のサブクラスです。もし WSGI サーバーが提供していれば wsgi.file_wrapper を使用し、そうでない場合はファイルを小さなチャンクでストリーミングします。as_attachment=True
だと、Content-Disposition
ヘッダーがattachment
に設定され、ブラウザにファイルをダウンロードするように要求します。それ以外の場合は、ファイル名が利用可能な場合のみ、値がinline
(ブラウザのデフォルト値)のContent-Disposition
ヘッダーが設定されます。もし
open_file
に名前がない、またはopen_file
の名前が適切でない場合は、filename
パラメータを使用してカスタムファイル名を提供してください。io.BytesIO
のようなファイルライクオブジェクトを渡す場合、それをFileResponse
に渡す前にseek()
を行うのはあなたの仕事です。open_file
の内容から推測できる場合、Content-Length
ヘッダーは自動的に設定されます。Content-Type
ヘッダーは、filename
やopen_file
の名前から推測できる場合には自動的に設定されます。
FileResponse
は、例えば以下のようにバイナリモードで開かれたファイルのような、バイナリー内容を持つあらゆるファイルライクオブジェクトを受け付けます。
>>> from django.http import FileResponse
>>> response = FileResponse(open("myfile.png", "rb"))
ファイルは自動的に閉じられるため、コンテキストマネージャーで開かないでください。
ASGI における使用
PythonのファイルAPIは同期的です。これは、ファイルをASGI下で提供するためには、ファイルを完全に消費しなければならないことを意味します。
非同期にファイルをストリーミングするには、aiofiles のような非同期ファイルAPIを提供するサードパーティパッケージを使用する必要があります。
HttpResponseBase
クラス¶
HttpResponseBase
クラスは、Django のすべてのレスポンスに共通です。直接レスポンスを作成するために使用すべきではありませんが、型チェックの際に役立つことがあります。