リクエストとレスポンスのオブジェクト

簡単な概要

Django は、システムを通じてステータスを渡すために、リクエストとレスポンスのオブジェクトを使います。

あるページがリクエストされたとき、Django はリクエストに関するメタデータを含んだ HttpRequest オブジェクトを生成します。それから Django は HttpRequest をビュー関数の最初の関数として渡し、適切なビューを読み込みます。あらゆるビューは HttpResponse オブジェクトを返す必要があります。

このドキュメントでは、HttpRequest と HttpResponse オブジェクトの API を説明しています。これは django.http モジュールにて定義されています。

HttpRequest オブジェクト

class HttpRequest

属性

特に記載がない限り、全ての属性は読み取り専用だと考えてください。

HttpRequest.scheme

リクエストのスキームを表す文字列です (通常は http か https)。

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.GET

渡された HTTP GET パラメータを含む、ディクショナリライクのオブジェクトです。後述の QueryDict のドキュメントを参照してください。

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.current_app

url テンプレートタグは、その値を reverse() の current_app 引数に使います。

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.is_secure()

リクエストがセキュアである場合、つまりHTTPSで行われた場合に True を返します。

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.read(size=None)

HttpRequest.readline()

HttpRequest.readlines()

HttpRequest.__iter__()

HttpRequest インスタンスから読み取るためのファイルライクなインターフェースを実装するメソッドです。これにより、着信リクエストをストリーミング形式で消費することが可能になります。一般的な使用例は、大きなXMLペイロードをメモリ内で完全なXMLツリーを構築することなく、繰り返しパーサーで処理する場合です。

この標準インターフェースを用いると、 HttpRequest インスタンスは ElementTree のようなXMLパーサーに直接渡すことができます。

import xml.etree.ElementTree as ET

for element in ET.iterparse(request):
    process(element)

QueryDict オブジェクト

class 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.appendlist(key, item)

key に関連付けられた内部リストに項目を追加します。

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'}

QueryDict.urlencode(safe=None)

クエリ文字列形式のデータを文字列で返します。例えば：

>>> q = QueryDict("a=2&b=3&b=5")
>>> q.urlencode()
'a=2&b=3&b=5'

safe パラメータを使って、エンコードを不要とする文字を渡すことができます。たとえば:

>>> q = QueryDict(mutable=True)
>>> q["next"] = "/a&b/"
>>> q.urlencode(safe="/")
'next=/a%26b/'

HttpResponse オブジェクト

class 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.content

必要に応じて文字列からエンコードされた、コンテンツを表すバイト文字列。

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 タイプであり、オプションで文字セットエンコーディングを指定して HTTP Content-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 オブジェクト

class 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 を持っています。

Changed in Django 4.2:

非同期イテレーションのサポートが追加されました。

属性

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

New in Django 4.2.

StreamingHttpResponse.streaming_content が非同期イテレータであるかどうかを示す真偽値です。

これは、 StreamingHttpResponse.streaming_content をラップする必要があるミドルウェアにとって便利です。

切断の取り扱い

New in Django 5.0.

クライアントがストリーミングレスポンス中に切断されると、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を提供するサードパーティパッケージを使用する必要があります。

メソッド

FileResponse.set_headers(open_file)

このメソッドはレスポンス初期化中に自動的に呼び出され、open_file に応じてさまざまなヘッダー (Content-Length、Content-Type、および Content-Disposition) を設定します。

HttpResponseBase クラス

class HttpResponseBase

HttpResponseBase クラスは、Django のすべてのレスポンスに共通です。直接レスポンスを作成するために使用すべきではありませんが、型チェックの際に役立つことがあります。