FastAPI リクエストボディのフィールドとネストモデル
Pydantic モデル内では、以下を使用できます。Fieldフィールドに検証ルールとメタデータを宣言したり、モデルをネストして複雑な JSON データ構造を処理したりできます。
Field を使用してフィールド検証を宣言する
パスオペレーション関数で使用するのとQuery、Path検証を宣言するのと同じように、Pydantic モデル内ではFieldフィールド検証を宣言します:
例
from typing import Annotated
from fastapi import FastAPI
from pydantic import BaseModel, Field
app = FastAPI()
class Item(BaseModel):
name: str = Field(min_length=1, max_length=100, description="商品名") # 必須、1〜100文字
description: str | None = Field(default=None, max_length=300, description="商品説明") # 任意
price: float = Field(gt=0, description="商品価格") # 必須、0より大きくなければならない
tax: float | None = Field(default=None, ge=0, description="税金") # 任意、>= 0
@app.post("/items/")
async def create_item(item: Item):
return item
from fastapi import FastAPI
from pydantic import BaseModel, Field
app = FastAPI()
class Item(BaseModel):
name: str = Field(min_length=1, max_length=100, description="商品名") # 必須、1〜100文字
description: str | None = Field(default=None, max_length=300, description="商品説明") # 任意
price: float = Field(gt=0, description="商品価格") # 必須、0より大きくなければならない
tax: float | None = Field(default=None, ge=0, description="税金") # 任意、>= 0
@app.post("/items/")
async def create_item(item: Item):
return item
Fieldサポートされている検証パラメータ:
| パラメータタイプ | パラメータ | 説明 |
|---|---|---|
| 文字列検証 | min_length | 最小長 |
max_length | 最大長 | |
pattern | 正規表現マッチング | |
| 数値検証 | gt | より大きい |
ge | 以上 | |
lt | より小さい | |
le | 以下 | |
| メタデータ | title | フィールドタイトル |
description | フィールド説明 |
注意
Fieldからpydanticインポートし、〜からではなくfastapiインポートします。これは〜とQuery、Pathなどが〜から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
tags: list[str] = [] # 文字列リスト、デフォルトは空リスト
@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
tags: list[str] = [] # 文字列リスト、デフォルトは空リスト
@app.post("/items/")
async def create_item(item: Item):
return item
リクエストボディの例:
{
"name": "Foo",
"price": 42.0,
"tags": ["rock", "metal", "bar"]
}
Set を使用して重複を除去する
タグを重複させたくない場合は、次を使用しますset型:
例
class Item(BaseModel):
name: str
description: str | None = None
price: float
tax: float | None = None
tags: set[str] = set() # 重複タグを自動的に除去
name: str
description: str | None = None
price: float
tax: float | None = None
tags: set[str] = set() # 重複タグを自動的に除去
リクエストに重複するタグが含まれていても、レスポンスでは自動的に重複が除去されます。
ネストモデル
Pydantic モデルのフィールド型は別の Pydantic モデルにすることができ、任意の深さのネストをサポートします:
例
from fastapi import FastAPI
from pydantic import BaseModel, HttpUrl
app = FastAPI()
# サブモデル:画像
class Image(BaseModel):
url: HttpUrl # 有効な URL かどうかを自動検証
name: str
# メインモデル:商品、画像サブモデルを含む
class Item(BaseModel):
name: str
description: str | None = None
price: float
tax: float | None = None
tags: set[str] = set()
image: Image | None = None # 任意の画像情報
@app.post("/items/")
async def create_item(item: Item):
return item
from pydantic import BaseModel, HttpUrl
app = FastAPI()
# サブモデル:画像
class Image(BaseModel):
url: HttpUrl # 有効な URL かどうかを自動検証
name: str
# メインモデル:商品、画像サブモデルを含む
class Item(BaseModel):
name: str
description: str | None = None
price: float
tax: float | None = None
tags: set[str] = set()
image: Image | None = None # 任意の画像情報
@app.post("/items/")
async def create_item(item: Item):
return item
対応するリクエストボディの構造:
{
"name": "Foo",
"description": "The pretender",
"price": 42.0,
"tax": 3.2,
"tags": ["rock", "metal", "bar"],
"image": {
"url": "http://example.com/baz.jpg",
"name": "The Foo live"
}
}
リスト内のサブモデル
サブモデルをリストに入れることができます:
例
from fastapi import FastAPI
from pydantic import BaseModel, HttpUrl
app = FastAPI()
class Image(BaseModel):
url: HttpUrl
name: str
class Item(BaseModel):
name: str
description: str | None = None
price: float
tax: float | None = None
tags: set[str] = set()
images: list[Image] | None = None # 画像リスト
@app.post("/items/")
async def create_item(item: Item):
return item
from pydantic import BaseModel, HttpUrl
app = FastAPI()
class Image(BaseModel):
url: HttpUrl
name: str
class Item(BaseModel):
name: str
description: str | None = None
price: float
tax: float | None = None
tags: set[str] = set()
images: list[Image] | None = None # 画像リスト
@app.post("/items/")
async def create_item(item: Item):
return item
対応するリクエストボディ:
{
"name": "Foo",
"price": 42.0,
"images": [
{"url": "http://example.com/baz.jpg", "name": "The Foo live"},
{"url": "http://example.com/dave.jpg", "name": "The Baz"}
]
}
深いネストモデル
任意の深さのネスト構造を定義できます:
例
from fastapi import FastAPI
from pydantic import BaseModel, HttpUrl
app = FastAPI()
class Image(BaseModel):
url: HttpUrl
name: str
class Item(BaseModel):
name: str
description: str | None = None
price: float
tax: float | None = None
tags: set[str] = set()
images: list[Image] | None = None
class Offer(BaseModel):
name: str
description: str | None = None
price: float
items: list[Item] # Offer は複数の Item を含み、Item はさらに複数の Image を含む
@app.post("/offers/")
async def create_offer(offer: Offer):
return offer
from pydantic import BaseModel, HttpUrl
app = FastAPI()
class Image(BaseModel):
url: HttpUrl
name: str
class Item(BaseModel):
name: str
description: str | None = None
price: float
tax: float | None = None
tags: set[str] = set()
images: list[Image] | None = None
class Offer(BaseModel):
name: str
description: str | None = None
price: float
items: list[Item] # Offer は複数の Item を含み、Item はさらに複数の Image を含む
@app.post("/offers/")
async def create_offer(offer: Offer):
return offer
純粋なリストのリクエストボディ
リクエストボディの最外層が JSON 配列の場合、関数パラメータで直接リスト型を宣言できます:
例
from fastapi import FastAPI
from pydantic import BaseModel, HttpUrl
app = FastAPI()
class Image(BaseModel):
url: HttpUrl
name: str
# リクエストボディが直接 Image のリスト
@app.post("/images/multiple/")
async def create_multiple_images(images: list[Image]):
return images
from pydantic import BaseModel, HttpUrl
app = FastAPI()
class Image(BaseModel):
url: HttpUrl
name: str
# リクエストボディが直接 Image のリスト
@app.post("/images/multiple/")
async def create_multiple_images(images: list[Image]):
return images
任意の dict からなるリクエストボディ
キー名が不定な辞書データを受け取る必要がある場合は、次を宣言できますdict型のリクエストボディ:
例
from fastapi import FastAPI
app = FastAPI()
# キーが int、値が float の辞書を受け取る
@app.post("/index-weights/")
async def create_index_weights(weights: dict[int, float]):
return weights
app = FastAPI()
# キーが int、値が float の辞書を受け取る
@app.post("/index-weights/")
async def create_index_weights(weights: dict[int, float]):
return weights
リクエストボディの例:
{
"1": 0.5,
"2": 1.5,
"3": 2.0
}
JSON は文字列型のキーのみサポートしますが、Pydantic は文字列キーを自動的に宣言された型に変換します(この例のように
int)。
まとめ
- Pydantic の
Fieldモデルフィールドに検証とメタデータを追加する list[str]、set[str]などのコレクション型でリスト/セットフィールドを宣言できる- モデルはネストして使用でき、任意の深さの JSON 構造をサポートします
HttpUrlなどの特殊型はフォーマットを自動検証します- 純粋なリストや任意の辞書もリクエストボディの型として使用できます