Zum Inhalt

Query-Parameter-Modelle

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. 😎

Hinweis

Dies wird seit FastAPI Version 0.115.0 unterstĂŒtzt. đŸ€“

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
đŸ€“ Other versions and variants 
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

Tip

Prefer to use the Annotated version if possible.

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

Tip

Prefer to use the Annotated version if possible.

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 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
đŸ€“ Other versions and variants 
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

Tip

Prefer to use the Annotated version if possible.

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

Tip

Prefer to use the Annotated version if possible.

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"
        }
    ]
}

Zusammenfassung

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

Tipp

Spoiler-Alarm: Sie können auch Pydantic-Modelle verwenden, um Cookies und Header zu deklarieren, aber darĂŒber werden Sie spĂ€ter im Tutorial lesen. đŸ€«