Header-параметри¶

Ви можете визначати параметри заголовків, так само як визначаєте Query, Path і Cookie параметри.

Імпорт `Header`¶

Спочатку імпортуйте Header:

Python 3.10+

from typing import Annotated

from fastapi import FastAPI, Header

app = FastAPI()


@app.get("/items/")
async def read_items(user_agent: Annotated[str | None, Header()] = None):
    return {"User-Agent": user_agent}

🤓 Other versions and variants

Python 3.9+Python 3.8+Python 3.10+ - non-AnnotatedPython 3.8+ - non-Annotated

from typing import Annotated, Union

from fastapi import FastAPI, Header

app = FastAPI()


@app.get("/items/")
async def read_items(user_agent: Annotated[Union[str, None], Header()] = None):
    return {"User-Agent": user_agent}

from typing import Union

from fastapi import FastAPI, Header
from typing_extensions import Annotated

app = FastAPI()


@app.get("/items/")
async def read_items(user_agent: Annotated[Union[str, None], Header()] = None):
    return {"User-Agent": user_agent}

Tip

Prefer to use the Annotated version if possible.

from fastapi import FastAPI, Header

app = FastAPI()


@app.get("/items/")
async def read_items(user_agent: str | None = Header(default=None)):
    return {"User-Agent": user_agent}

Tip

Prefer to use the Annotated version if possible.

from typing import Union

from fastapi import FastAPI, Header

app = FastAPI()


@app.get("/items/")
async def read_items(user_agent: Union[str, None] = Header(default=None)):
    return {"User-Agent": user_agent}

Оголошення параметрів `Header`¶

Потім оголосіть параметри заголовків, використовуючи ту ж структуру, що й для Path, Query та Cookie.

Ви можете визначити значення за замовчуванням, а також усі додаткові параметри валідації або анотації:

Python 3.10+

from typing import Annotated

from fastapi import FastAPI, Header

app = FastAPI()


@app.get("/items/")
async def read_items(user_agent: Annotated[str | None, Header()] = None):
    return {"User-Agent": user_agent}

🤓 Other versions and variants

Python 3.9+Python 3.8+Python 3.10+ - non-AnnotatedPython 3.8+ - non-Annotated

from typing import Annotated, Union

from fastapi import FastAPI, Header

app = FastAPI()


@app.get("/items/")
async def read_items(user_agent: Annotated[Union[str, None], Header()] = None):
    return {"User-Agent": user_agent}

from typing import Union

from fastapi import FastAPI, Header
from typing_extensions import Annotated

app = FastAPI()


@app.get("/items/")
async def read_items(user_agent: Annotated[Union[str, None], Header()] = None):
    return {"User-Agent": user_agent}

Tip

Prefer to use the Annotated version if possible.

from fastapi import FastAPI, Header

app = FastAPI()


@app.get("/items/")
async def read_items(user_agent: str | None = Header(default=None)):
    return {"User-Agent": user_agent}

Tip

Prefer to use the Annotated version if possible.

from typing import Union

from fastapi import FastAPI, Header

app = FastAPI()


@app.get("/items/")
async def read_items(user_agent: Union[str, None] = Header(default=None)):
    return {"User-Agent": user_agent}

Технічні деталі

Headerє "сестринським" класом для Path, Query і Cookie. Він також успадковується від загального класу Param.

Але пам’ятайте, що при імпорті Query, Path, Header та інших із fastapi, то насправді вони є функціями, які повертають спеціальні класи.

Інформація

Щоб оголосити заголовки, потрібно використовувати Header, інакше параметри будуть інтерпретуватися як параметри запиту.

Автоматичне перетворення¶

Header має додатковий функціонал порівняно з Path, Query та Cookie.

Більшість стандартних заголовків розділяються символом «дефіс», також відомим як «мінус» (-).

Але змінна, така як user-agent, є недійсною в Python.

Тому, за замовчуванням, Header автоматично перетворює символи підкреслення (_) на дефіси (-) для отримання та документування заголовків.

Оскільки заголовки HTTP не чутливі до регістру, Ви можете використовувати стандартний стиль Python ("snake_case").

Тому Ви можете використовувати user_agent, як зазвичай у коді Python, замість того щоб писати з великої літери, як User_Agent або щось подібне.

Якщо Вам потрібно вимкнути автоматичне перетворення підкреслень у дефіси, встановіть convert_underscores в Header значення False:

Python 3.10+

from typing import Annotated

from fastapi import FastAPI, Header

app = FastAPI()


@app.get("/items/")
async def read_items(
    strange_header: Annotated[str | None, Header(convert_underscores=False)] = None,
):
    return {"strange_header": strange_header}

🤓 Other versions and variants

Python 3.9+Python 3.8+Python 3.10+ - non-AnnotatedPython 3.8+ - non-Annotated

from typing import Annotated, Union

from fastapi import FastAPI, Header

app = FastAPI()


@app.get("/items/")
async def read_items(
    strange_header: Annotated[
        Union[str, None], Header(convert_underscores=False)
    ] = None,
):
    return {"strange_header": strange_header}

from typing import Union

from fastapi import FastAPI, Header
from typing_extensions import Annotated

app = FastAPI()


@app.get("/items/")
async def read_items(
    strange_header: Annotated[
        Union[str, None], Header(convert_underscores=False)
    ] = None,
):
    return {"strange_header": strange_header}

Tip

Prefer to use the Annotated version if possible.

from fastapi import FastAPI, Header

app = FastAPI()


@app.get("/items/")
async def read_items(
    strange_header: str | None = Header(default=None, convert_underscores=False),
):
    return {"strange_header": strange_header}

Tip

Prefer to use the Annotated version if possible.

from typing import Union

from fastapi import FastAPI, Header

app = FastAPI()


@app.get("/items/")
async def read_items(
    strange_header: Union[str, None] = Header(default=None, convert_underscores=False),
):
    return {"strange_header": strange_header}

Увага

Перед тим як встановити значення False для convert_underscores пам’ятайте, що деякі HTTP-проксі та сервери не підтримують заголовки з підкресленнями.

Дубльовані заголовки¶

Можливо отримати дубльовані заголовки, тобто той самий заголовок із кількома значеннями.

Це можна визначити, використовуючи список у типізації параметра.

Ви отримаєте всі значення дубльованого заголовка у вигляді list у Python.

Наприклад, щоб оголосити заголовок X-Token, який може з’являтися більше ніж один раз:

Python 3.10+

from typing import Annotated

from fastapi import FastAPI, Header

app = FastAPI()


@app.get("/items/")
async def read_items(x_token: Annotated[list[str] | None, Header()] = None):
    return {"X-Token values": x_token}

🤓 Other versions and variants

Python 3.9+Python 3.8+Python 3.10+ - non-AnnotatedPython 3.9+ - non-AnnotatedPython 3.8+ - non-Annotated

from typing import Annotated, List, Union

from fastapi import FastAPI, Header

app = FastAPI()


@app.get("/items/")
async def read_items(x_token: Annotated[Union[List[str], None], Header()] = None):
    return {"X-Token values": x_token}

from typing import List, Union

from fastapi import FastAPI, Header
from typing_extensions import Annotated

app = FastAPI()


@app.get("/items/")
async def read_items(x_token: Annotated[Union[List[str], None], Header()] = None):
    return {"X-Token values": x_token}

Tip

Prefer to use the Annotated version if possible.

from fastapi import FastAPI, Header

app = FastAPI()


@app.get("/items/")
async def read_items(x_token: list[str] | None = Header(default=None)):
    return {"X-Token values": x_token}

Tip

Prefer to use the Annotated version if possible.

from typing import Union

from fastapi import FastAPI, Header

app = FastAPI()


@app.get("/items/")
async def read_items(x_token: Union[list[str], None] = Header(default=None)):
    return {"X-Token values": x_token}

Tip

Prefer to use the Annotated version if possible.

from typing import List, Union

from fastapi import FastAPI, Header

app = FastAPI()


@app.get("/items/")
async def read_items(x_token: Union[List[str], None] = Header(default=None)):
    return {"X-Token values": x_token}

Якщо Ви взаємодієте з цією операцією шляху, надсилаючи два HTTP-заголовки, наприклад:

X-Token: foo
X-Token: bar

Відповідь буде така:

{
    "X-Token values": [
        "bar",
        "foo"
    ]
}

Підсумок¶

Оголошуйте заголовки за допомогою Header, використовуючи той самий підхід, що й для Query, Path та Cookie.

Не хвилюйтеся про підкреслення у змінних — FastAPI автоматично конвертує їх.

Header-параметри¶

Імпорт Header¶

Оголошення параметрів Header¶

Автоматичне перетворення¶

Дубльовані заголовки¶

Підсумок¶

Імпорт `Header`¶

Оголошення параметрів `Header`¶