FastAPI は HTML フォームデータ (Form) と ファイルアップロード (File/UploadFile) を処理します。これらは JSON ボディとは異なり、異なるコンテンツタイプ (multipart/form-data) を使用するため、特別なパラメータ型で宣言する必要があります。
from fastapi import Form
@app.post("/login")
def login(username: str = Form(), password: str = Form()): # form fields, not JSON
# data comes as application/x-www-form-urlencoded or multipart/form-data
return {"username": username}
HTML フォームフィールド (例:ログインフォーム) を受け取るには Form() を使用します。注意:ルートは異なるコンテンツタイプであるため、JSON ボディ または フォームデータのいずれかを使用でき、両方は使用できません。(python-multipart のインストールが必要です。)
from fastapi import File, UploadFile
@app.post("/upload")
async def upload(file: UploadFile): # a single file
contents = await file.read() # read the file's bytes
file.filename # original name
file.content_type # MIME type
# save it:
with open(f"uploads/{file.filename}", "wb") as f:
f.write(contents)
return {"filename": file.filename, "size": len(contents)}
UploadFile は推奨される型です。スプーリングされたファイル (大きなファイルはディスクに保存され、すべてがメモリに入らない)、非同期メソッド (read、write、seek) およびメタデータを備えています。小さなファイル以外は、生の bytes の代わりに使用してください。
@app.post("/upload-many")
async def upload_many(files: list[UploadFile]): # multiple files
return [f.filename for f in files]
@app.post("/profile")
async def profile(name: str = Form(), avatar: UploadFile = File()):
# combine form fields AND a file upload in one multipart request
...
if file.content_type not in ["image/jpeg", "image/png"]: # check type
raise HTTPException(400, "Invalid file type")
# also: limit file SIZE, sanitize filenames, scan content — uploads are untrusted input
フォームデータとファイルアップロードの処理は、一般的で実用的なニーズです。ログインフォーム、プロフィール写真のアップロード、ドキュメント送信、ファイル処理 API はすべてこれを必要とし、FastAPI がデフォルトで使用する JSON ボディとは異なる方法で動作します。
フォームフィールドの Form() を理解し、特に UploadFile によるアップロード (推奨される手段。大きなファイルをディスクにスプーリングするため、すべてをメモリに読み込まない。RAM を枯渇させずに大きなファイルを処理するために重要です) を理解することは、これらの機能に必須です。
同様に重要なのは、アップロードに伴う セキュリティの責任 です。アップロードされたファイルは信頼できない入力であるため、その型とサイズを検証し、ファイル名をサニタイズし、それらを保存・提供する方法に注意深くあることは、脆弱性を回避するために不可欠です。
フォームフィールドを受け取る方法、単一と複数のファイルアップロードを処理する方法、フォームとファイルを組み合わせる方法、およびアップロードを安全に検証する方法を理解することは、ユーザーが送信したコンテンツを受け入れる実世界の API を構築するための実用的な知識です。