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

Query-Parameter mit einem Pydantic-Modell¶

Deklarieren Sie die benötigten Query-Parameter in einem Pydantic-Modell und dann den Parameter als Query:

fromtypingimport Annotated, Literal
fromfastapiimport FastAPI, Query
frompydanticimport BaseModel, Field
app = FastAPI()
classFilterParams(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 defread_items(filter_query: Annotated[FilterParams, Query()]):
 return filter_query

fromtypingimport Literal
fromfastapiimport FastAPI, Query
frompydanticimport BaseModel, Field
app = FastAPI()
classFilterParams(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 defread_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:

fromtypingimport Annotated, Literal
fromfastapiimport FastAPI, Query
frompydanticimport BaseModel, Field
app = FastAPI()
classFilterParams(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 defread_items(filter_query: Annotated[FilterParams, Query()]):
 return filter_query

fromtypingimport Literal
fromfastapiimport FastAPI, Query
frompydanticimport BaseModel, Field
app = FastAPI()
classFilterParams(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 defread_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. 😎