FastAPI フォームデータ

クライアントが HTML フォーム（application/x-www-form-urlencoded）でデータを送信する場合は、使用する必要がありますFormフォームフィールドを受け取るために、ではなくBaseModel。

python-multipart のインストール

フォーム機能を使用する前に、事前にインストールする必要がありますpython-multipart：

pip install python-multipart

フォームデータの受け取り

使用Formフォームフィールドを宣言する：

例

from fastapi import FastAPI, Form

app = FastAPI()


@app.post("/login/")
async def login(
    username: str = Form(),      # 必須フォームフィールド
    password: str = Form(),      # 必須フォームフィールド
):
    return {"username": username}

フォームフィールドと JSON リクエストボディの違い

比較項目JSON リクエストボディフォームデータ
Content-Typeapplication/jsonapplication/x-www-form-urlencoded
宣言方法Pydantic BaseModelForm()
データ構造ネストされたオブジェクトと配列をサポートフラットなキーと値のペア
適用シナリオAPI インターフェース（フロントエンドとバックエンドの分離）HTML フォーム送信

フォームデータは「フィールド」の形式で送信され、JSON ではありません。したがって、Formパラメータを Pydantic モデルとして宣言することはできません。フォームフィールドと JSON リクエストボディは同じルートで同時に使用できません。

オプションのフォームフィールド

クエリパラメータと同様に、デフォルト値を持つフォームフィールドはオプションです：

例

from fastapi import FastAPI, Form

app = FastAPI()


@app.post("/items/")
async def create_item(
    name: str = Form(...),                    # 必須
    description: str | None = Form(None),     # オプション、デフォルトは None
    price: float = Form(..., gt=0),           # 必須、0 より大きい必要があります
):
    return {"name": name, "description": description, "price": price}

HTML フォームを使ったテスト

HTML ページを作成してフォーム送信をテストできます：

例

<form action="http://localhost:8000/items/" method="post">
    <label for="name">Name:</label>
    <input type="text" id="name" name="name" required>
    <br>
    <label for="description">Description:</label>
    <textarea id="description" name="description"></textarea>
    <br>
    <label for="price">Price:</label>
    <input type="number" id="price" name="price" required min="0">
    <br>
    <button type="submit">Submit</button>
</form>

フォームデータの検証とドキュメント

使用Form宣言されたフィールドは、FastAPI が自動的にデータ検証を行い、API ドキュメントに表示します：

まとめ

  • 使用FormHTML フォームで送信されたデータを受け取る
  • フォームデータは JSON ではなく、BaseModelリクエストボディと混在させることはできません
  • Form()必須フィールドを宣言し、Form(None)オプションフィールドを宣言する
  • インストールが必要python-multipart 包
  • フォームフィールドはクエリパラメータと同じ検証ルールをサポートします（min_length、gtなど）
その他の拡張