FastAPI クエリパラメータ
クエリパラメータは URL 内の?後に、&クエリパラメータは URL 内の ? の後、& で区切られたキーと値のペアです。関数のパラメータがパスパラメータでもリクエストボディでもない場合、FastAPI はそれを自動的にクエリパラメータとして解釈します。
基本的な使い方
クエリパラメータを宣言するには、関数のパラメータに型注釈とデフォルト値を追加するだけです:
例
app = FastAPI()
# skip と limit はクエリパラメータで、デフォルト値を持ちます
fake_items_db = [{"item_name": "Foo"}, {"item_name": "Bar"}, {"item_name": "Baz"}]
@app.get("/items/")
async def read_item(skip: int = 0, limit: int = 10):
# ページネーションクエリのシミュレーション
return fake_items_db[skip : skip + limit]
クエリパラメータの URL 内での形式:
http://127.0.0.1:8000/items/?skip=0&limit=10
異なるアクセス方法でのパラメータ値:
| URL | skip の値 | limit の値 | 説明 |
|---|---|---|---|
/items/ | 0 | 10 | デフォルト値を使用 |
/items/?skip=20 | 20 | 10 | skip は渡された値を使用し、limit はデフォルト値を使用します |
/items/?skip=20&limit=5 | 20 | 5 | 両方のパラメータは渡された値を使用します |
オプションパラメータ
デフォルト値をNoneに設定するだけで、オプションのクエリパラメータを宣言できます:
例
app = FastAPI()
@app.get("/items/{item_id}")
async def read_item(item_id: str, q: str | None = None):
# item_id はパスパラメータ(必須)、q はクエリパラメータ(オプション)です
if q:
return {"item_id": item_id, "q": q}
return {"item_id": item_id}
ここでq: str | None = Noneの意味はq文字列またはNone、デフォルト値はNone。
FastAPI はデフォルト値によって
= Noneパラメータが必須かどうかを判断し、型注釈によるのではありませんstr | None。型注釈は主にエディタのサポート向上に役立ちます。
クエリパラメータの型変換
FastAPI はクエリパラメータを自動的にbool型に変換できます:
例
app = FastAPI()
@app.get("/items/{item_id}")
async def read_item(item_id: str, short: bool = False):
# short パラメータは自動的にブール値に変換されます
if short:
return {"item_id": item_id}
return {"item_id": item_id, "description": "これはとても長い説明です"}
以下の URL 内のshortパラメータはすべて変換されますTrue:
/items/foo?short=1 /items/foo?short=True /items/foo?short=true /items/foo?short=on /items/foo?short=yes
その他の値は変換されますFalse。
必須クエリパラメータ
デフォルト値を設定しないクエリパラメータが必須パラメータになります:
例
app = FastAPI()
@app.get("/items/{item_id}")
async def read_item(item_id: str, needy: str):
# needy にはデフォルト値がなく、必須クエリパラメータです
return {"item_id": item_id, "needy": needy}
アクセスしたとき/items/fooに提供されていないneedyパラメータがある場合、FastAPI は以下のようなエラーを返します:
{
"detail": [
{
"type": "missing",
"loc": ["query", "needy"],
"msg": "Field required",
"input": null
}
]
}
必須・デフォルト値あり・オプションのパラメータを混在させる
同じ関数内で異なるタイプのクエリパラメータを混在させることができます:
例
app = FastAPI()
@app.get("/items/{item_id}")
async def read_item(
item_id: str, # パスパラメータ(必須)
needy: str, # 必須クエリパラメータ
skip: int = 0, # デフォルト値を持つクエリパラメータ
limit: int | None = None, # オプションのクエリパラメータ
):
item = {"item_id": item_id, "needy": needy, "skip": skip}
if limit:
item.update({"limit": limit})
return item
パラメータ型のまとめ:
| パラメータ | 宣言方法 | 必須かどうか | 説明 |
|---|---|---|---|
item_id | item_id: str | 必須 | パスパラメータ、URL パス内に現れる |
needy | needy: str | 必須 | クエリパラメータ、デフォルト値なし |
skip | skip: int = 0 | オプション | クエリパラメータ、デフォルト値 0 |
limit | limit: int | None = None | オプション | クエリパラメータ、デフォルト値は None |
複数のパスパラメータとクエリパラメータ
FastAPI は複数のパスパラメータとクエリパラメータを同時に認識でき、パラメータの宣言順序は認識に影響しません:
例
app = FastAPI()
@app.get("/users/{user_id}/items/{item_id}")
async def read_user_item(
user_id: int, # パスパラメータ
item_id: str, # パスパラメータ
q: str | None = None, # オプションのクエリパラメータ
short: bool = False, # デフォルト値を持つクエリパラメータ
):
item = {"item_id": item_id, "owner_id": user_id}
if q:
item.update({"q": q})
if not short:
item.update({"description": "これはとても長い説明です"})
return item
FastAPI はパラメータ名でパス内の変数を照合するため、関数のパラメータの順序は重要ではありません。
まとめ
クエリパラメータの核心ポイント:
- デフォルト値があるパラメータはオプションで、デフォルト値がないパラメータは必須です
- FastAPI は URL 内の文字列を自動的に宣言された型に変換します
bool型は複数の書き方をサポートしています(true、1、on、yesなど)- クエリパラメータはパスパラメータと混在して使用でき、順序は関係ありません