---
title: "アップロードファイルとアップロードハンドラ"
version: 6.1
locale: ja
source: https://docs.djangoproject.com/ja/6.1/ref/files/uploads/
canonical: https://djangodocs.dev/ja/6.1/ref/files/uploads/
---
# アップロードファイルとアップロードハンドラ

## アップロードファイル

#### `class UploadedFile`

ファイルアップロード中、実際のファイルデータは [`request.FILES`](/ja/6.1/ref/request-response/#django.http.HttpRequest.FILES) に保存されます。この辞書の各エントリーは `UploadedFile` オブジェクト(またはそのサブクラス)です。これはアップロードされたファイルのラッパーです。アップロードされたコンテンツにアクセスするために、通常、以下のメソッドのいずれかを使用します:

#### `UploadedFile.read()`

アップロードされたデータ全体をファイルから読み込む。このメソッドには注意が必要です。アップロードされたファイルが巨大な場合、それをメモリに読み込もうとするとシステムを圧迫する可能性があります。おそらく代わりに `chunks()` を使うことになるでしょう。

#### `UploadedFile.multiple_chunks(chunk_size=None)`

アップロードされたファイルが、複数のチャンクに分けて読み込む必要があるほど大きい場合に `True` を返します。デフォルトでは2.5MB以上のファイルですが、設定可能です。

#### `UploadedFile.chunks(chunk_size=None)`

ファイルのチャンクを返すジェネレータです。`multiple_chunks()` が `True` の場合、 `read()` の代わりにこのメソッドをループで使用すべきです。

実際には、常に `chunks()` を使用するのが最も簡単です。 `read()` を使用する代わりに `chunks()` をループ処理することで、大きなファイルがシステムのメモリを圧迫しないようにできます。

`UploadedFile` の有用な属性は次の通りです:

#### `UploadedFile.name`

アップロードされたファイルの名前 (例: `my_file.txt`)。

#### `UploadedFile.size`

アップロードされたファイルのサイズ（バイト単位）。

#### `UploadedFile.content_type`

ファイルと共にアップロードされるコンテンツタイプのヘッダ (例: `text/plain` や `application/pdf`)。ユーザーから提供されるデータのように、アップロードされたファイルが実際にこのタイプであると信頼すべきではありません。依然として、ファイルがコンテンツタイプヘッダが示すコンテンツを含んでいることを検証する必要があります。"信頼するが検証せよ" です。

#### `UploadedFile.content_type_extra`

`content-type` ヘッダーに渡される追加のパラメータを含む辞書です。通常、Google App Engine などのサービスがファイルのアップロードを取り扱っている場合に提供されます。その結果、ハンドラはアップロードされたファイル内容を受信しないかもしれず、代わりにファイルへの URL や他のポインターを受け取ります ([**RFC 2388**](https://datatracker.ietf.org/doc/html/rfc2388.html#section-5.3) を参照)。

#### `UploadedFile.charset`

`text/*` コンテンツタイプについては、ブラウザが提供する文字セット(例えば `utf8`)です。ここでも、"信頼するが検証せよ" が最良の方針です。

> **Note**
>
> 通常の Python ファイルのように、アップロードされたファイルをイテレートすることで、ファイルを一行ずつ読むことができます:
>
> ```
> for line in uploadedfile:
>     do_something_with(line)
> ```
>
> Lines are split using [universal newlines](https://docs.python.org/3/glossary.html#term-universal-newlines). The following are
> recognized as ending a line: the Unix end-of-line convention `'\n'`, the
> Windows convention `'\r\n'`, and the old Macintosh convention `'\r'`.

`UploadedFile` のサブクラスには以下が含まれます:

#### `class TemporaryUploadedFile`

一時的な場所にアップロードされたファイル (つまり、stream-to-disk)。このクラスは、 [`TemporaryFileUploadHandler`](#django.core.files.uploadhandler.TemporaryFileUploadHandler) によって使用されます。 [`UploadedFile`](#django.core.files.uploadedfile.UploadedFile) のメソッドに加えて、1つの追加メソッドを持っています:

#### `TemporaryUploadedFile.temporary_file_path()`

一時アップロードされたファイルの完全なパスを返します。

#### `class InMemoryUploadedFile`

メモリへのアップロードされたファイル(つまり、stream-to-memory)。このクラスは [`MemoryFileUploadHandler`](#django.core.files.uploadhandler.MemoryFileUploadHandler) によって使用されます。

## ビルトインのアップロードハンドラ

[`MemoryFileUploadHandler`](#django.core.files.uploadhandler.MemoryFileUploadHandler) と [`TemporaryFileUploadHandler`](#django.core.files.uploadhandler.TemporaryFileUploadHandler) は、小さなファイルをメモリに読み込み、大きなファイルをディスクに保存するDjangoのデフォルトのファイルアップロードの動作を提供します。これらは `django.core.files.uploadhandler` に位置しています。

#### `class MemoryFileUploadHandler`

小さいファイル用にアップロードをメモリにストリームするためのファイルアップロードハンドラ。

#### `class TemporaryFileUploadHandler`

[`TemporaryUploadedFile`](#django.core.files.uploadedfile.TemporaryUploadedFile) を使ってデータを一時ファイルにストリームするアップロードハンドラ。

## アップロードハンドラをカスタマイズする

#### `class FileUploadHandler`

全てのファイルアップロードハンドラは、`django.core.files.uploadhandler.FileUploadHandler` のサブクラスとなります。アップロードハンドラはいつでも好きなときに定義できます。

### 必要なメソッド

カスタマイズされたファイルアップロードハンドラでは、以下のメソッドを定義する **必要があります**。

#### `FileUploadHandler.receive_data_chunk(raw_data, start)`

ファイルアップロードから、データの "chunk" を受け取ります。

`raw_data` はアップロードされたデータを含むバイト文字列です。

`start` はこの `raw_data` チャンクが始まる、ファイル内での位置です。

あなたが返すデータは、その後のアップロードハンドラの `receive_data_chunk` メソッドに渡されます。 この方法で、1 つのハンドラは他のハンドラの「フィルタ」になることができます。

`receive_data_chunk` から `None` を返し、残りのアップロードハンドラがこのチャンクを取得するのを短絡します。 これは、アップロードしたデータを自分で保存しておき、将来のハンドラでデータのコピーを保存したくない場合に便利です。

`StopUpload` または `SkipFile` 例外を発生させると、アップロードが中止されるか、ファイルが完全にスキップされます。

#### `FileUploadHandler.file_complete(file_size)`

ファイルのアップロードが完了したときに呼ばれます。

ハンドラーは `request.FILES` に格納される `UploadedFile` オブジェクトを返すべきです。またハンドラーは、`UploadedFile` オブジェクトが後続のアップロードハンドラーから来るべきであることを示すために `None` を返すこともできます。

### 省略可能なメソッド

独自のアップロードハンドラは、以下の省略可能なメソッドや属性を定義できます:

#### `FileUploadHandler.chunk_size`

Django がメモリに格納してハンドラに送り込む "chunks" のサイズです (byte で表されます)。 つまり、この属性は `FileUploadHandler.receive_data_chunk` に渡されるチャンクのサイズをコントロールします。

パフォーマンスを最大限にするために、チャンクサイズは `4` で割り切れる必要があり、2 GB (2<sup>31</sup> bytes) を超えてはいけません。 複数のハンドラによってチャンクサイズが複数ある場合、Django はハンドラで定義された最小のチャンクサイズを使用します。

デフォルトは 64\*2<sup>10</sup> bytes、つまり 64 KB です。

#### `FileUploadHandler.new_file(field_name, file_name, content_type, content_length, charset, content_type_extra)`

新しいファイルのアップロード開始を通知するコールバックです。 アップロードハンドラにデータが送られる前に呼び出されます。

`field_name` は、ファイル `<input>` フィールドの文字列名です。

`file_name` はブラウザによって提供されるファイル名です。

`content_type` は、ブラウザによって提供される MIME タイプです -- 例: `'image/jpeg'`。

`content_length` は、ブラウザによって与えられる画像の長さです。提供されずに `None` となることがあります。

`charset` は、ブラウザによって与えられる文字セットです (例: `utf8`)。`content_length` のように、提供されないことがあります。

`content_type_extra` は、`content-type` からの、ファイルについての追加情報です。[`UploadedFile.content_type_extra`](#django.core.files.uploadedfile.UploadedFile.content_type_extra) を参照してください。

このメソッドは、将来のハンドラがこのファイルをハンドリングするのを防ぐため、`StopFutureHandlers` 例外を投げます。

#### `FileUploadHandler.upload_complete()`

全てのアップロード (全てのファイル)  が完了したことを通知するコールバックです。

#### `FileUploadHandler.upload_interrupted()`

アップロードが中断されたことを通知するコールバック。例えば、ユーザーがファイルアップロード中にブラウザを閉じたときなど。

#### `FileUploadHandler.handle_raw_input(input_data, META, content_length, boundary, encoding)`

ハンドラに対して、生の HTTP インプットのパースを完全にオーバーライドできるようにします。

`input_data` は、`read()` をサポートするファイルのようなオブジェクトです。

`META` は、`request.META` と同じオブジェクトです。

`content_length` は、`input_data` 内のデータの長さです。`input_data` から `content_length` バイト以上を読み出さないでください。

`boundary` は、このリクエストの MIME boundary です。

`encoding` は、リクエストのエンコーディングです。

アップロードハンドリングを継続したいとき、`None` を返します。もしくはリクエストに適した新しいデータ構造を直接返したいとき、 `(POST, FILES)` のタプルを返します。