Ceeds Academy教材アプリ教材・症状語・タグで検索
索引グラフ試す
アプリFW/ライブラリ▸FastAPI

FastAPI: ルーティングとパラメータ(パス/クエリ)

hands-on所要 20分最新草稿
前提: FastAPI: 最小API(起動 / GET / /docs)→次: FastAPI: リクエストバリデーション(Pydantic)
意味グラフ(この教材と内容的に近い教材・1ネスト)
例え(Analogies)
パス/クエリ=住所と注文オプション

パスパラメータ(/items/3)は「どの品物か」を指す住所、クエリ(?q=)は「どんな条件で」の注文オプション。型ヒントで自動にチェックされる。

概要

📍 app-frameworks ▸ FastAPI ▸ ルーティングとパラメータ | 種別: hands-on | facts_as_of 2026-06(FastAPI 0.136)

公式ドキュメント — hands-on

🎞 スライド

パラメータ=「URLから値を受け取る」

パス と クエリ の2種類

どこに入るか(テキスト図)

GET /items/42?q=book
│ │
パス │ │ クエリ
▼ ▼
item_id = 42 q = "book"

型ヒントで自動変換+検証

item_id: int → 数字以外なら 422 を自動で返す

—
出典(sources)

fastapi.tiangolo.com (Path/Query Parameters) ; FastAPI 0.136 / 2026-06確認

確認問題(Review-Questions)
型ヒント item_id: int を付ける利点は?記述
基礎公式
解答・解説▾ 開く

自動で型変換され、不正な値は422で弾かれる(検証)。

/items/{id} の {id} は何パラメータか?択一
基礎公式
解答・解説▾ 開く

パスパラメータ。

目次
例え概要公式ドキュメント出典確認問題
鮮度
最新
更新: 2026-06-15
次回棚卸し: 2026-12-15
周期: 6か月
版: FastAPI 0.136

概要

パスパラメータ(/items/{id})とクエリパラメータ(?q=)を受け取る。型ヒントを書くだけで自動変換・検証され、不正な入力は自動で 422 になる。

公式ドキュメント準拠(FastAPI 0.136)

@app.get("/items/{item_id}")
def get_item(item_id: int, q: str | None = None):
    return {"item_id": item_id, "q": q}
  • {item_id}=パス、q=クエリ。型ヒント(int)で自動変換+検証(不正は 422)。
  • パスに含めた名前はパスパラメータ、それ以外の引数はクエリパラメータになる。

出典: FastAPI: Path Parameters / Query Parameters

🧭 誤解訂正集

よくある誤解 正しい理解
パスもクエリも同じ書き方 パスは {} でURLに埋め、クエリは関数引数に書く
型変換は自分でする 型ヒントで FastAPI が自動変換(失敗は 422)
クエリは必須 既定値(= None 等)を付ければ任意になる

📖 用語

  • ルーティング … URL とメソッドを処理関数に対応づける仕組み。
  • パスパラメータ … URL の一部として渡す値(/items/{id})。
  • クエリパラメータ … ?key=value で渡す値。任意指定にしやすい。
  • 422 Unprocessable Entity … 入力が型/検証に合わないときの応答コード。

✅ 確認の目安(can-do)

パスパラメータとクエリパラメータを区別して定義でき、**「この値はパスとクエリのどちらが適切か・なぜ 422 になるか」**を説明できる。

⚠️ エラー復旧集

症状 原因 復旧
422 Unprocessable Entity 型不一致(int に文字) 型に合う値を送る
クエリが反映されない パスに含めている 関数引数(パス以外)に定義