Моделі параметрів заголовків¶

uvx library-skills

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

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

Параметри заголовків з використанням Pydantic моделі¶

Оголосіть потрібні параметри заголовків у Pydantic моделі, а потім оголосіть параметр як Header:

from typing import Annotated

from fastapi import FastAPI, Header
from pydantic import BaseModel

app = FastAPI()


class CommonHeaders(BaseModel):
    host: str
    save_data: bool
    if_modified_since: str | None = None
    traceparent: str | None = None
    x_tag: list[str] = []


@app.get("/items/")
async def read_items(headers: Annotated[CommonHeaders, Header()]):
    return headers

from fastapi import FastAPI, Header
from pydantic import BaseModel

app = FastAPI()


class CommonHeaders(BaseModel):
    host: str
    save_data: bool
    if_modified_since: str | None = None
    traceparent: str | None = None
    x_tag: list[str] = []


@app.get("/items/")
async def read_items(headers: CommonHeaders = Header()):
    return headers

FastAPI буде витягувати дані для кожного поля з заголовків у запиті та передавати їх у створену вами Pydantic модель.

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

Ви можете побачити необхідні заголовки в інтерфейсі документації за адресою /docs:

Заборонити додаткові заголовки¶

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

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

from typing import Annotated

from fastapi import FastAPI, Header
from pydantic import BaseModel

app = FastAPI()


class CommonHeaders(BaseModel):
    model_config = {"extra": "forbid"}

    host: str
    save_data: bool
    if_modified_since: str | None = None
    traceparent: str | None = None
    x_tag: list[str] = []


@app.get("/items/")
async def read_items(headers: Annotated[CommonHeaders, Header()]):
    return headers

from fastapi import FastAPI, Header
from pydantic import BaseModel

app = FastAPI()


class CommonHeaders(BaseModel):
    model_config = {"extra": "forbid"}

    host: str
    save_data: bool
    if_modified_since: str | None = None
    traceparent: str | None = None
    x_tag: list[str] = []


@app.get("/items/")
async def read_items(headers: CommonHeaders = Header()):
    return headers

Якщо клієнт спробує надіслати додаткові заголовки, він отримає помилку у відповіді.

Наприклад, якщо клієнт спробує надіслати заголовок tool зі значенням plumbus, він отримає помилку у відповіді з повідомленням про те, що параметр заголовка tool не дозволений:

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

Вимкнути перетворення підкреслень¶

Так само, як і зі звичайними параметрами заголовків, коли у назвах параметрів є символи підкреслення, вони автоматично перетворюються на дефіси.

Наприклад, якщо у коді у вас є параметр заголовка save_data, очікуваний HTTP-заголовок буде save-data, і він так само відображатиметься в документації.

Якщо з якоїсь причини вам потрібно вимкнути це автоматичне перетворення, ви також можете зробити це для Pydantic моделей для параметрів заголовків.

from typing import Annotated

from fastapi import FastAPI, Header
from pydantic import BaseModel

app = FastAPI()


class CommonHeaders(BaseModel):
    host: str
    save_data: bool
    if_modified_since: str | None = None
    traceparent: str | None = None
    x_tag: list[str] = []


@app.get("/items/")
async def read_items(
    headers: Annotated[CommonHeaders, Header(convert_underscores=False)],
):
    return headers

from fastapi import FastAPI, Header
from pydantic import BaseModel

app = FastAPI()


class CommonHeaders(BaseModel):
    host: str
    save_data: bool
    if_modified_since: str | None = None
    traceparent: str | None = None
    x_tag: list[str] = []


@app.get("/items/")
async def read_items(headers: CommonHeaders = Header(convert_underscores=False)):
    return headers

Поєднати моделі параметрів¶

Ви можете поєднувати кілька моделей параметрів заголовків з окремими параметрами заголовків і залежностями. Кожна модель витягується та перевіряється незалежно, як пояснено для моделей параметрів запиту.

Конфігурація extra кожної моделі застосовується до всіх параметрів заголовків, включно з тими, що оголошені в інших моделях або залежностях. З extra="forbid" будь-який заголовок поза цією моделлю відхиляється. З extra="allow" ці заголовки включаються як додаткові поля моделі.

Кожна модель використовує власне налаштування Header(convert_underscores=...) як під час читання запиту, так і під час генерування OpenAPI. Явно задані псевдоніми полів залишаються буквальними назвами заголовків.

Необов’язкові моделі параметрів заголовків¶

Оголосіть модель параметрів заголовків з | None і значенням за замовчуванням None, щоб зробити групу необов’язковою.

from typing import Annotated

from fastapi import FastAPI, Header
from pydantic import BaseModel

app = FastAPI()


class ClientHeaders(BaseModel):
    x_client_name: str
    x_client_version: str


@app.get("/items/")
async def read_items(client: Annotated[ClientHeaders | None, Header()] = None):
    return client

from fastapi import FastAPI, Header
from pydantic import BaseModel

app = FastAPI()


class ClientHeaders(BaseModel):
    x_client_name: str
    x_client_version: str


@app.get("/items/")
async def read_items(client: ClientHeaders | None = Header(default=None)):
    return client

Якщо не надіслано ані x-client-name, ані x-client-version, client має значення None. Якщо надіслано хоча б один із них, FastAPI перевіряє модель і вимагає обидва поля.

Для значень за замовчуванням, додаткових полів і OpenAPI діють ті самі правила, що й для необов’язкових моделей параметрів запиту.

Заголовки на кшталт Host також підпорядковуються конфігурації extra моделі. З extra="allow" вони роблять модель присутньою, навіть якщо жодне з оголошених полів не передано.

Підсумок¶

Ви можете використовувати Pydantic моделі для оголошення заголовків у FastAPI. 😎