FastAPI リクエストボディ

リクエストボディはクライアントがAPIに送信するデータです。クライアントからJSONデータを受け取る必要がある場合、リクエストボディを使用して渡します。FastAPIはPydanticモデルを使用してリクエストボディの構造を宣言し、データ検証、変換、ドキュメント生成を自動的に行います。


リクエストボディとクエリパラメータの違い

データの受け渡し方場所適用場面HTTPメソッド
パスパラメータURLパス/items/5リソースを識別するGET、PUT、DELETE など
クエリパラメータURL内?key=valueフィルタリング、ページネーションなどのオプションパラメータ主にGET
リクエストボディリクエスト内のJSONデータ複雑なデータの送信POST、PUT、PATCH

データ送信には次を使用すべきPOST(最も一般的)、PUT、DELETE 或 PATCH。ただし、FastAPIは技術的にはGETリクエストでリクエストボディを送信できますが、これはHTTP仕様に準拠しておらず、Swagger UIもGETリクエストに対してリクエストボディのドキュメントを表示しません。


Pydantic モデルを使用したリクエストボディの宣言

1. BaseModel をインポート

from pydantic import BaseModel

2. データモデルを作成

継承するクラスを定義BaseModelし、Pythonの標準型を使用してすべての属性を宣言します:

例

from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()


# リクエストボディのデータモデルを定義
class Item(BaseModel):
    name: str               # 必須:商品名
    description: str | None = None  # 任意:商品説明
    price: float            # 必須:商品価格
    tax: float | None = None        # 任意:税


@app.post("/items/")
async def create_item(item: Item):
    return item

属性が必須かどうかのルールはクエリパラメータと同じです:

  • デフォルト値がある属性は任意です(例:description、tax)
  • デフォルト値がない属性は必須です(例:name、price)

以下のJSONはすべて有効なリクエストボディです:

// 包含所有字段
{
    "name": "Foo",
    "description": "可选描述",
    "price": 45.2,
    "tax": 3.5
}

// 省略可选字段
{
    "name": "Foo",
    "price": 45.2
}

FastAPIによるリクエストボディの処理

Pythonの型宣言だけで、FastAPIは次の作業を自動的に実行できます:

機能説明
リクエストボディの読み取りリクエスト内のデータをJSON形式で読み取る
型変換データを宣言された型に変換します(例:文字列を浮動小数点数に変換)
データ検証データの有効性を検証し、無効な場合は明確なエラーメッセージを返す
パラメータへの代入検証済みデータを関数パラメータに代入し、エディタの自動補完を利用できるようにする
ドキュメント生成JSON Schemaを自動生成し、APIドキュメントに表示する

モデル属性の使用

パス操作関数内では、通常のPythonオブジェクトを操作するように、モデルのすべての属性にアクセスできます:

例

from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()


class Item(BaseModel):
    name: str
    description: str | None = None
    price: float
    tax: float | None = None


@app.post("/items/")
async def create_item(item: Item):
    # モデル属性に直接アクセス
    item_dict = item.model_dump()  # Pydantic v2 のシリアライズ方法
    if item.tax:
        # 税込み価格を計算
        price_with_tax = item.price + item.tax
        item_dict.update({"price_with_tax": price_with_tax})
    return item_dict

Pydantic v2 では、次を使用しますmodel_dump()v1の の代わりにdict()メソッドを使用してモデルデータをシリアライズします。model_dump()モデルのすべてのフィールドを含む辞書を返します。


リクエストボディ + パスパラメータ

パスパラメータとリクエストボディを同時に宣言できます。FastAPIは自動的に正しい場所からデータを取得します:

例

from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()


class Item(BaseModel):
    name: str
    description: str | None = None
    price: float
    tax: float | None = None


# パスパラメータとリクエストボディを同時に使用
@app.put("/items/{item_id}")
async def update_item(item_id: int, item: Item):
    return {"item_id": item_id, "item_name": item.name}

FastAPI の識別ルール:

  • item_idパス内で{item_id}に出現する -> パスパラメータ
  • item型がPydanticモデルである -> リクエストボディ

リクエストボディ + パスパラメータ + クエリパラメータ

3つを同時に使用できます:

例

from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()


class Item(BaseModel):
    name: str
    description: str | None = None
    price: float
    tax: float | None = None


# パスパラメータ、クエリパラメータ、リクエストボディを同時に使用
@app.put("/items/{item_id}")
async def update_item(item_id: int, item: Item, q: str | None = None):
    result = {"item_id": item_id, **item.model_dump()}
    if q:
        result.update({"q": q})
    return result

FastAPI の完全なパラメータ識別ルール:

識別条件パラメータの取得元
パラメータ名がパスの{}内で宣言されているパスパラメータ
パラメータが単一型(int、str、boolなど)クエリパラメータ
パラメータの型がPydanticモデルであるリクエストボディ

まとめ

リクエストボディの重要ポイント:

  • Pydantic の を使用BaseModelリクエストボディ構造を定義する
  • デフォルト値があるフィールドは任意、デフォルト値がないフィールドは必須
  • リクエストボディはパスパラメータやクエリパラメータと同時に使用できます
  • FastAPIはデータ検証、型変換、ドキュメント生成を自動的に実行します
  • Pydantic v2 では、次を使用しますmodel_dump()シリアライズを実行します
その他の拡張機能