FastAPI ファイルアップロード

FastAPI は提供していますFileとUploadFileファイルアップロードを処理する2つの方法で、単独のファイルアップロードとフォームとファイルの混合アップロードをサポートしています。


依存関係のインストール

ファイルアップロードも同様に依存しますpython-multipart:

pip install python-multipart

UploadFile を使用する

UploadFile推奨される方法であり、より豊富なファイル情報アクセスインターフェースを提供します:

例

from fastapi import FastAPI, UploadFile

app = FastAPI()


@app.post("/uploadfile/")
async def create_upload_file(file: UploadFile):
    # UploadFile が提供する属性とメソッド
    return {
        "filename": file.filename,          # ファイル名
        "content_type": file.content_type,  # ファイルのMIMEタイプ
        "size": file.size,                  # ファイルサイズ(バイト)
    }

UploadFileの属性とメソッド:

属性/メソッド型説明
filenamestr | Noneアップロードされたファイルの元のファイル名
content_typestr | NoneファイルのMIMEタイプ(例:image/png)
fileSpooledTemporaryFileファイルに似たオブジェクトで、ファイル内容を読み取れます
sizeint | Noneファイルサイズ(バイト)
read()メソッドファイル内容を読み取りますbytes
write()メソッドファイルに内容を書き込みます
seek()メソッドファイルポインタの位置を移動します
close()メソッドファイルを閉じます

UploadFile"SpooledTemporaryFile" を使用してファイル内容を保存します。ファイルが小さい場合はメモリ内に保存され、ファイルが大きい場合は自動的にディスクに書き込まれるため、bytesよりメモリを節約できます。


File を使用してファイル内容を受け取る

Fileファイル内容を直接読み取ってbytes、小さなファイルに適しています:

例

from fastapi import FastAPI, File

app = FastAPI()


@app.post("/files/")
async def create_file(file: bytes = File()):
    # file はファイルの元のバイトデータです
    return {"file_size": len(file)}

FileとUploadFileの比較:

比較項目FileUploadFile
データ型bytesファイルオブジェクト
メモリ使用量ファイル全体をメモリにロード大きなファイルは自動的にディスクに書き込まれる
ファイル情報なし(内容のみ)ファイル名、タイプ、サイズあり
適用シーン小さなファイル大きなファイル、ファイル情報が必要なシーン

オプションのファイルアップロード

デフォルト値を使用Noneファイルアップロードをオプションにします:

例

from fastapi import FastAPI, UploadFile

app = FastAPI()


@app.post("/uploadfile/")
async def create_upload_file(file: UploadFile | None = None):
    if not file:
        return {"message": "ファイルがアップロードされていません"}
    return {"filename": file.filename}

複数ファイルのアップロード

リストを使用して複数のファイルを受け取ります:

例

from fastapi import FastAPI, UploadFile

app = FastAPI()


@app.post("/uploadfiles/")
async def create_upload_files(files: list[UploadFile]):
    return {"filenames": [file.filename for file in files]}

フォームとファイルの混合アップロード

同じルート内でフォームデータとファイルを同時に受け取ることができます:

例

from fastapi import FastAPI, File, UploadFile, Form

app = FastAPI()


@app.post("/items/")
async def create_item(
    # フォームフィールド
    name: str = Form(...),
    description: str | None = Form(None),
    # ファイルアップロード
    file: UploadFile | None = None,
):
    result = {"name": name, "description": description}
    if file:
        result["filename"] = file.filename
    return result

アップロードしたファイルの保存

以下の例は、アップロードしたファイルをディスクに保存する方法を示しています:

例

import shutil
from fastapi import FastAPI, UploadFile

app = FastAPI()


@app.post("/uploadfile/")
async def create_upload_file(file: UploadFile):
    # アップロードしたファイルを指定されたパスに保存します
    with open(f"uploads/{file.filename}", "wb") as buffer:
        shutil.copyfileobj(file.file, buffer)
    return {"filename": file.filename, "message": "ファイルのアップロードに成功しました"}

実際のプロジェクトでは、ファイルをアップロードする際には注意が必要です:1) ファイルのタイプとサイズを検証する;2) 安全なファイル名を使用する(パストラバーサル攻撃を避ける);3) アップロードディレクトリの権限を制限する;4) 大きなファイルの場合は一度に読み取るのではなく、ストリーミング処理を使用する。


まとめ

  • 推奨されるのはUploadFile、それはよりメモリを節約し、豊富なファイル情報を提供します
  • File小さなファイルのシナリオに適しており、直接読み取りますbytes
  • 使用してlist[UploadFile]複数ファイルのアップロードを受け取ります
  • フォーム(Form)とファイル(UploadFile)は同じルート内で使用できます
  • ファイルアップロード時のセキュリティに注意:ファイルタイプを検証し、安全なファイル名を使用し、サイズを制限する
その他の拡張