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
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
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}
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
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()シリアライズを実行します