Модели параметров запроса¶
Если у вас есть группа связанных параметров запроса, вы можете создать модель Pydantic, чтобы объявить их.
Это позволит вам повторно использовать модель в нескольких местах, а также объявлять валидации и метаданные для всех параметров сразу. 😎
Примечание
Это поддерживается начиная с версии FastAPI 0.115.0. 🤓
Параметры запроса с моделью Pydantic¶
Объявите параметры запроса, которые вам нужны, в модели Pydantic, а затем объявите параметр как 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
🤓 Другие версии и варианты
Совет
По возможности предпочитайте версию с Annotated.
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 извлечёт данные для каждого поля из параметров запроса в запросе и передаст вам определённую вами модель Pydantic.
Проверьте документацию¶
Вы можете увидеть параметры запроса в интерфейсе документации по адресу /docs:
Запрет дополнительных параметров запроса¶
В некоторых особых случаях использования (вероятно, не очень распространённых) вы можете захотеть ограничить параметры запроса, которые вы хотите получать.
Вы можете использовать конфигурацию модели Pydantic, чтобы forbid (запретить) любые 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
🤓 Другие версии и варианты
Совет
По возможности предпочитайте версию с Annotated.
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
Если клиент попытается отправить какие-либо дополнительные данные в параметрах запроса, он получит ответ с ошибкой.
Например, если клиент попытается отправить параметр запроса tool со значением plumbus, например:
https://example.com/items/?limit=10&tool=plumbus
Он получит ответ с ошибкой, сообщающий, что параметр запроса tool не разрешён:
{
"detail": [
{
"type": "extra_forbidden",
"loc": ["query", "tool"],
"msg": "Extra inputs are not permitted",
"input": "plumbus"
}
]
}
Итог¶
Вы можете использовать модели Pydantic для объявления параметров запроса в FastAPI. 😎
Совет
Спойлер: вы также можете использовать модели Pydantic для объявления cookie и заголовков, но об этом вы прочитаете позже в руководстве. 🤫