tiangolo.fastapi/docs/ja/docs/tutorial/query-param-models.md

クエリパラメータモデル

もし関連する複数のクエリパラメータから成るグループがあるなら、それらを宣言するために、Pydanticモデルを作成できます。

こうすることで、複数の場所でそのPydanticモデルを再利用でき、バリデーションやメタデータを、すべてのクエリパラメータに対して一度に宣言できます。😎

/// note | 備考

この機能は、FastAPIのバージョン 0.115.0 からサポートされています。🤓

///

クエリパラメータにPydanticモデルを使用する

必要な複数のクエリパラメータをPydanticモデルで宣言し、さらに、それを Query として宣言しましょう:

{* ../../docs_src/query_param_models/tutorial001_an_py310.py hl[9:13,17] *}

FastAPIは、リクエストのクエリパラメータからそれぞれのフィールドのデータを抽出し、定義されたPydanticモデルを提供します。

ドキュメントの確認

対話的APIドキュメント /docs でクエリパラメータを確認できます:

余分なクエリパラメータを禁止する

特定の（あまり一般的ではないかもしれない）ケースで、受け付けるクエリパラメータを制限する必要があるかもしれません。

Pydanticのモデルの Configuration を利用して、 extra フィールドを forbid とすることができます。

{* ../../docs_src/query_param_models/tutorial002_an_py310.py hl[10] *}

もしクライアントがクエリパラメータとして余分なデータを送ろうとすると、エラーレスポンスが返されます。

例えば、クライアントがクエリパラメータ tool に、値 plumbus を設定して送ろうとすると:

https://example.com/items/?limit=10&tool=plumbus

クエリパラメータ tool が許可されていないことを通知するエラーレスポンスが返されます。

{
    "detail": [
        {
            "type": "extra_forbidden",
            "loc": ["query", "tool"],
            "msg": "Extra inputs are not permitted",
            "input": "plumbus"
        }
    ]
}

まとめ

FastAPIでは、クエリパラメータを宣言するために、Pydanticモデルを使用できます。😎

/// tip | 豆知識

ネタバレ注意: Pydanticモデルはクッキーやヘッダーの宣言にも使用できますが、その内容については後のチュートリアルで学びます。🤫

///