これは、FastAPI で最も期待されていた機能の 1 つで、約 3 週間前にリリースされました。少なくとも Pydantic モデル FastAPI について話しているときは。

はい、Pydantic モデルを使用してクエリ パラメーターをマッピングできる機能について話しています。

それでは、この投稿では、あなたのすべてを紹介しようと思います?できますか？この件についてはどうすることもできません ?:

?クエリパラメータのマッピング

Pydantic でクエリ パラメーターのマッピングを開始するために最初に行う必要があるのは、FastAPI バージョン 0.115.0 を使用していることを確認することです。

この後、いつでも FastAPI ドキュメントにアクセスして、すでに利用可能なものを確認できます。 Sebastián とチーム メンバーは、ドキュメントを常に最新の状態に保ち、有益な情報を提供することに、本当に本当によく取り組んでいます ✨.

?ちょっとした歴史

FastAPI でクエリ パラメーターをマッピングする方法について、いくつかの例から始めましょう。 ?

これを行う最も簡単な方法は次のとおりです:

from fastapi import FastAPI

app = FastAPI()

@app.get("/")
async def search(
    limit: int | None = 10,
    skip: int | None = 1,
    filter: str | None = None
):
    return {
        "limit": limit,
        "skip": skip,
        "filter": filter
    }

これで、次のように呼び出すことができます:

GET http://localhost:8000/?limit=42&skip=12&filter=banana

ただし、このクエリ パラメータが他のルートで使用されることが判明した場合は、次のように分離します。

from typing import Any
from fastapi import Depends, FastAPI, Query

app = FastAPI()

async def pagination_query_string(
    limit: int | None = Query(10, ge=5, le=100),
    skip: int | None = Query(1, ge=1),
    filter: str | None = Query(None)
) -> dict[str, Any]:
    return {
        "limit": limit,
        "skip": skip,
        "filter": filter
    }

@app.get("/")
async def search(q: dict[str, Any] = Depends(pagination_query_string)):
    return q

または、Pydantic を使用してモデルをマッピングしているため、少しリファクタリングするだけで次のようになります:

from fastapi import Depends, FastAPI, Query
from pydantic import BaseModel

app = FastAPI()

class PaginationQueryString(BaseModel):
    limit: int | None = 10
    skip: int | None = 1
    filter: str | None = None

async def pagination_query_string(
    limit: int | None = Query(10, ge=5, le=100),
    skip: int | None = Query(1, ge=1),
    filter: str | None = Query(None)
) -> PaginationQueryString:
    return PaginationQueryString(
        limit=limit,
        skip=skip,
        filter=filter
    )

@app.get("/")
async def search(q: PaginationQueryString = Depends(pagination_query_string)):
    return q

⌨️ Pydantic を使用してクエリ文字列をマッピングする

クエリ文字列を取得したい場合、関数を作成して依存関係として追加する必要はありません。 PaginationQueryString 型のオブジェクトが必要であり、それがクエリ文字列であることを FastAPI に伝えるだけです:

from typing import Annotated
from fastapi import FastAPI, Query
from pydantic import BaseModel

app = FastAPI()

class PaginationQueryString(BaseModel):
    limit: int | None = 10
    skip: int | None = 1
    filter: str | None = None

@app.get("/")
async def search(q: Annotated[PaginationQueryString, Query()]):
    return q

簡単ですよね？ ?

⚠️制限は何ですか?

少なくともバージョン 0.115.0 では、ネストされたモデルではあまりうまく機能しません。

次のようなことを試してみましょう:

from typing import Annotated
from fastapi import FastAPI, Query
from pydantic import BaseModel

app = FastAPI()

class Filter(BaseModel):
    name: str | None = None
    age: int | None = None
    nickname: str | None = None

class PaginationQueryString(BaseModel):
    limit: int | None = 10
    skip: int | None = 1
    filter: Filter | None = None

@app.get("/")
async def search(q: Annotated[PaginationQueryString, Query()]):
    return q

以前のように呼び出す場合:

GET http://localhost:8000/?limit=42&skip=12&filter=chocolate

フィルターがオブジェクトであることを示すエラーが表示されます:

{
    "detail": [
        {
            "type": "model_attributes_type",
            "loc": [
                "query",
                "filter"
            ],
            "msg": "Input should be a valid dictionary or object to extract fields from",
            "input": "chocolate"
        }
    ]
}

少なくとも現時点では、それは絶対に正しいです！フィルターを文字列ではなく Pydantic モデルに変更しました。しかし、これを辞書に変換しようとすると:

http://localhost:8000/?limit=42&skip=12&filter={"name": "Rafael", "age": 38, "nickname": "ceb10n"}

FastAPI は、フィルターが有効な辞書である必要があることを示します ?:

{
    "detail": [
        {
            "type": "model_attributes_type",
            "loc": [
                "query",
                "filter"
            ],
            "msg": "Input should be a valid dictionary or object to extract fields from",
            "input": "{\"name\": \"Rafael\", \"age\": 38, \"nickname\": \"ceb10n\"}"
        }
    ]
}

これは、FastAPI が Starlette の QueryParams に依存しており、辞書ではなく文字列を FastAPI に与えるために発生します。そして、少なくともバージョン 0.115.0 では、エラーが発生します。

⁉️ それでは、クエリパラメータで Pydantic モデルをいつ使用すればよいのでしょうか?

とても簡単です:

✅ 複雑なネストされたオブジェクトを必要としない単純なクエリ文字列をお持ちですか?使ってください！ ?

❌ 複雑なネストされたクエリ文字列を作成しましたか?まだ使用していないのですか？ (クエリ文字列を再考してみるのもいいかもしれません。? シンプルであればあるほど良いです ?)