Моделі параметрів запиту¶

🌐 Переклад ШІ та людьми

Цей переклад виконано ШІ під керівництвом людей. 🤝

Можливі помилки через неправильне розуміння початкового змісту або неприродні формулювання тощо. 🤖

Ви можете покращити цей переклад, допомігши нам краще спрямовувати AI LLM.

Якщо у Вас є група параметрів запиту, які пов’язані між собою, Ви можете створити Pydantic-модель для їх оголошення.

Це дозволить Вам повторно використовувати модель у різних місцях, а також оголошувати перевірки та метадані для всіх параметрів одночасно. 😎

Примітка

Ця можливість підтримується, починаючи з версії FastAPI 0.115.0. 🤓

Параметри запиту з Pydantic-моделлю¶

Оголосіть параметри запиту, які Вам потрібні, у Pydantic-моделі, а потім оголосіть цей параметр як Query:

Python 3.10+

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

Python 3.10+ - non-Annotated

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 буде витягувати дані для кожного поля з параметрів запиту у запиті та передавати їх у визначену вами Pydantic-модель.

Перевірте документацію¶

Ви можете побачити параметри запиту в UI документації за /docs:

Заборона зайвих параметрів запиту¶

У деяких особливих випадках (ймовірно, не дуже поширених) Ви можете захотіти обмежити параметри запиту, які дозволено отримувати.

Ви можете використати конфігурацію моделі Pydantic, щоб заборонити (forbid) будь-які зайві (extra) поля:

Python 3.10+

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

Python 3.10+ - non-Annotated

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

Якщо клієнт спробує надіслати зайві дані у параметрах запиту, він отримає відповідь з помилкою.

Наприклад, якщо клієнт спробує надіслати параметр запиту 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-моделі для оголошення кукі та заголовків, але про це Ви дізнаєтеся пізніше в цьому посібнику. 🤫