Modèles de paramètres de requête¶

uvx library-skills

Si vous avez un groupe de paramètres de requête liés, vous pouvez créer un modèle Pydantic pour les déclarer.

Cela vous permet de réutiliser le modèle à plusieurs endroits et aussi de déclarer des validations et des métadonnées pour tous les paramètres en une seule fois. 😎

Déclarer des paramètres de requête avec un modèle Pydantic¶

Déclarez les paramètres de requête dont vous avez besoin dans un modèle Pydantic, puis déclarez le paramètre en tant que Query :

from typing import Annotated, Literal

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

app = FastAPI()


class FilterParams(BaseModel):
    limit: int = Field(100, gt=0, le=100)
    offset: int = Field(0, ge=0)
    order_by: Literal["created_at", "updated_at"] = "created_at"
    tags: list[str] = []


@app.get("/items/")
async def read_items(filter_query: Annotated[FilterParams, Query()]):
    return filter_query

from typing import Literal

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

app = FastAPI()


class FilterParams(BaseModel):
    limit: int = Field(100, gt=0, le=100)
    offset: int = Field(0, ge=0)
    order_by: Literal["created_at", "updated_at"] = "created_at"
    tags: list[str] = []


@app.get("/items/")
async def read_items(filter_query: FilterParams = Query()):
    return filter_query

FastAPI extrait les données pour chaque champ à partir des paramètres de requête de la requête et vous fournit le modèle Pydantic que vous avez défini.

Consultez les documents¶

Vous pouvez voir les paramètres de requête dans l'interface des documents à /docs :

Interdisez des paramètres de requête supplémentaires¶

Dans certains cas d'utilisation particuliers (probablement peu courants), vous pouvez vouloir restreindre les paramètres de requête que vous souhaitez recevoir.

Vous pouvez utiliser la configuration du modèle Pydantic pour forbid tout champ extra :

from typing import Annotated, Literal

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

app = FastAPI()


class FilterParams(BaseModel):
    model_config = {"extra": "forbid"}

    limit: int = Field(100, gt=0, le=100)
    offset: int = Field(0, ge=0)
    order_by: Literal["created_at", "updated_at"] = "created_at"
    tags: list[str] = []


@app.get("/items/")
async def read_items(filter_query: Annotated[FilterParams, Query()]):
    return filter_query

from typing import Literal

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

app = FastAPI()


class FilterParams(BaseModel):
    model_config = {"extra": "forbid"}

    limit: int = Field(100, gt=0, le=100)
    offset: int = Field(0, ge=0)
    order_by: Literal["created_at", "updated_at"] = "created_at"
    tags: list[str] = []


@app.get("/items/")
async def read_items(filter_query: FilterParams = Query()):
    return filter_query

Si un client tente d'envoyer des données supplémentaires dans les paramètres de requête, il recevra une réponse d'erreur.

Par exemple, si le client tente d'envoyer un paramètre de requête tool avec la valeur plumbus, comme :

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

Il recevra une réponse d'erreur lui indiquant que le paramètre de requête tool n'est pas autorisé :

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

Combinez des modèles de paramètres¶

Vous pouvez déclarer plusieurs modèles de paramètres de requête et les combiner avec des paramètres de requête individuels ou des dépendances.

from typing import Annotated

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

app = FastAPI()


class Pagination(BaseModel):
    limit: int = Field(10, ge=1)
    offset: int = Field(0, ge=0)


class Filters(BaseModel):
    tags: list[str] = []


@app.get("/items/")
def read_items(
    pagination: Annotated[Pagination, Query()],
    filters: Annotated[Filters, Query()],
    search: str | None = None,
):
    return {"pagination": pagination, "filters": filters, "search": search}

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

app = FastAPI()


class Pagination(BaseModel):
    limit: int = Field(10, ge=1)
    offset: int = Field(0, ge=0)


class Filters(BaseModel):
    tags: list[str] = []


@app.get("/items/")
def read_items(
    pagination: Pagination = Query(),
    filters: Filters = Query(),
    search: str | None = None,
):
    return {"pagination": pagination, "filters": filters, "search": search}

Les paramètres de requête restent au même niveau.

https://example.com/items/?limit=5&offset=10&tags=red&tags=blue&search=shirt

Il n'y a pas de clés pagination ou filters dans la chaîne de requête. Chaque modèle valide les paramètres de requête indépendamment, avec ses propres valeurs par défaut, validateurs de champs et validateurs de modèle. Il en va de même lorsque les modèles ou les paramètres individuels sont déclarés dans des dépendances.

Si des modèles partagent un nom de paramètre ou un alias, chaque modèle valide ce paramètre de requête indépendamment. Utilisez des noms ou des alias distincts pour des valeurs indépendantes. OpenAPI ne répertorie un paramètre partagé qu'une seule fois, comme pour les paramètres partagés avec des dépendances ; les déclarations partagées doivent donc décrire le même type et les mêmes contraintes.

La configuration extra de chaque modèle s'applique à tous les paramètres de requête, y compris ceux déclarés dans d'autres modèles ou dépendances. Avec extra="forbid", tout paramètre extérieur à ce modèle est rejeté. Avec extra="allow", ces paramètres sont inclus en tant que champs supplémentaires du modèle.

Cela fonctionne aussi pour les modèles Header et Cookie.

Modèles de paramètres de requête optionnels¶

Déclarez un modèle de paramètres de requête avec | None et une valeur par défaut de None pour rendre le groupe optionnel.

from datetime import date
from typing import Annotated

from fastapi import FastAPI, Query
from pydantic import BaseModel

app = FastAPI()


class DateRange(BaseModel):
    start: date
    end: date


@app.get("/items/")
async def read_items(
    limit: int = 10,
    date_range: Annotated[DateRange | None, Query()] = None,
):
    return {"limit": limit, "date_range": date_range}

from datetime import date

from fastapi import FastAPI, Query
from pydantic import BaseModel

app = FastAPI()


class DateRange(BaseModel):
    start: date
    end: date


@app.get("/items/")
async def read_items(
    limit: int = 10,
    date_range: DateRange | None = Query(default=None),
):
    return {"limit": limit, "date_range": date_range}

Si ni start ni end n'est envoyé, date_range vaut None. Si l'un des deux est envoyé, FastAPI valide le modèle et exige les deux champs.

L'utilisation de | None sans valeur par défaut laisse le paramètre obligatoire.

Les paramètres supplémentaires suivent la configuration extra du modèle. Les paramètres supplémentaires ignorés ne rendent pas le modèle présent.

OpenAPI répertorie les champs du groupe individuellement et les marque comme optionnels.

Vous pouvez aussi déclarer des modèles de paramètres d'en-tête et des modèles de paramètres de cookie optionnels.

Résumé¶

Vous pouvez utiliser des modèles Pydantic pour déclarer des paramètres de requête dans FastAPI. 😎