Query-Parameter-Modelle¶

uvx library-skills

Wenn Sie eine Gruppe von Query-Parametern haben, die miteinander in Beziehung stehen, können Sie ein Pydantic-Modell erstellen, um diese zu deklarieren.

Dadurch können Sie das Modell an mehreren Stellen wiederverwenden und gleichzeitig Validierungen und Metadaten für alle Parameter auf einmal deklarieren. 😎

Query-Parameter mit einem Pydantic-Modell¶

Deklarieren Sie die benötigten Query-Parameter in einem Pydantic-Modell und dann den Parameter als 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 wird die Daten für jedes Feld aus den Query-Parametern des Request extrahieren und Ihnen das definierte Pydantic-Modell bereitstellen.

Die Dokumentation testen¶

Sie können die Query-Parameter in der Dokumentations-Oberfläche unter /docs einsehen:

Zusätzliche Query-Parameter verbieten¶

In einigen speziellen Anwendungsfällen (wahrscheinlich nicht sehr häufig) möchten Sie möglicherweise die Query-Parameter, die Sie empfangen möchten, beschränken.

Sie können die Modellkonfiguration von Pydantic verwenden, um jegliche extra Felder mit forbid zu verbieten:

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

Wenn ein Client versucht, einige zusätzliche Daten in den Query-Parametern zu senden, erhält er eine Error-Response.

Wenn der Client beispielsweise versucht, einen tool Query-Parameter mit dem Wert plumbus zu senden, wie:

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

erhält er eine Error-Response, die ihm mitteilt, dass der Query-Parameter tool nicht erlaubt ist:

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

Parametermodelle kombinieren¶

Sie können mehrere Query-Parameter-Modelle deklarieren und sie mit einzelnen Query-Parametern oder Abhängigkeiten kombinieren.

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}

Die Requestparameter bleiben auf derselben Ebene.

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

Es gibt keine Schlüssel pagination oder filters im Query-String. Jedes Modell validiert die Query-Parameter unabhängig, mit seinen eigenen Defaultwerten, Feldvalidatoren und Modellvalidatoren. Dasselbe gilt, wenn die Modelle oder einzelnen Parameter in Abhängigkeiten deklariert werden.

Wenn Modelle einen Parameternamen oder Alias gemeinsam nutzen, validiert jedes Modell diesen Requestparameter unabhängig. Verwenden Sie unterschiedliche Namen oder Aliase für unabhängige Werte. OpenAPI listet einen gemeinsam genutzten Parameter nur einmal auf, wie auch bei Parametern, die mit Abhängigkeiten gemeinsam genutzt werden. Daher sollten gemeinsame Deklarationen denselben Typ und dieselben Einschränkungen beschreiben.

Die extra-Konfiguration jedes Modells gilt für alle Query-Parameter, einschließlich derjenigen, die in anderen Modellen oder Abhängigkeiten deklariert sind. Mit extra="forbid" wird jeder Parameter außerhalb dieses Modells abgelehnt. Mit extra="allow" werden diese Parameter als zusätzliche Felder in das Modell aufgenommen.

Dies funktioniert auch für Header- und Cookie-Modelle.

Optionale Query-Parameter-Modelle¶

Deklarieren Sie ein Query-Parameter-Modell mit | None und einem Defaultwert von None, um die Gruppe optional zu machen.

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}

Wenn weder start noch end gesendet wird, ist date_range gleich None. Wenn eines davon gesendet wird, validiert FastAPI das Modell und erfordert beide Felder.

Bei Verwendung von | None ohne Defaultwert bleibt der Parameter erforderlich.

Zusätzliche Parameter folgen der extra-Konfiguration des Modells. Ignorierte zusätzliche Parameter bewirken nicht, dass das Modell als vorhanden gilt.

OpenAPI listet die Felder der Gruppe einzeln auf und markiert sie als optional.

Sie können auch optionale Header-Parameter-Modelle und Cookie-Parameter-Modelle deklarieren.

Zusammenfassung¶

Sie können Pydantic-Modelle verwenden, um Query-Parameter in FastAPI zu deklarieren. 😎