Zum Inhalt

Header-Parameter

Sie können Header-Parameter genauso definieren, wie Sie Query-, Path- und Cookie-Parameter definieren.

Header importieren

Importieren Sie zuerst Header:

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
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-Parameter deklarieren

Deklarieren Sie dann die Header-Parameter mit derselben Struktur wie bei Path, Query und Cookie.

Sie können den Defaultwert sowie alle zusätzlichen Validierungs- oder Annotationsparameter definieren:

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
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}

Technische Details

Header ist eine „Schwester“-Klasse von Path, Query und Cookie. Sie erbt ebenfalls von der gemeinsamen Param-Klasse.

Aber denken Sie daran, dass bei der Nutzung von Query, Path, Header und anderen Importen aus fastapi, diese tatsächlich Funktionen sind, die spezielle Klassen zurückgeben.

Info

Um Header zu deklarieren, müssen Sie Header verwenden, da die Parameter sonst als Query-Parameter interpretiert werden würden.

Automatische Konvertierung

Header bietet etwas zusätzliche Funktionalität im Vergleich zu Path, Query und Cookie.

Die meisten Standard-Header sind durch ein „Bindestrich“-Zeichen getrennt, auch bekannt als „Minus-Symbol“ (-).

Aber eine Variable wie user-agent ist in Python ungültig.

Daher wird Header standardmäßig die Zeichen des Parameter-Namens von Unterstrich (_) zu Bindestrich (-) konvertieren, um die Header zu extrahieren und zu dokumentieren.

Außerdem ist Groß-/Klein­schrei­bung in HTTP-Headern nicht relevant, daher können Sie sie im Standard-Python-Stil (auch bekannt als „snake_case“) deklarieren.

Sie können also user_agent verwenden, wie Sie es normalerweise im Python-Code tun würden, anstatt die Anfangsbuchstaben wie bei User_Agent großzuschreiben oder Ähnliches.

Wenn Sie aus irgendeinem Grund die automatische Konvertierung von Unterstrichen zu Bindestrichen deaktivieren müssen, setzen Sie den Parameter convert_underscores von Header auf False:

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
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}

Achtung

Bevor Sie convert_underscores auf False setzen, bedenken Sie, dass manche HTTP-Proxys und Server die Verwendung von Headern mit Unterstrichen nicht erlauben.

Doppelte Header

Es ist möglich, doppelte Header zu empfangen. Damit ist gemeint, denselben Header mit mehreren Werten.

Sie können solche Fälle definieren, indem Sie in der Typdeklaration eine Liste verwenden.

Sie erhalten dann alle Werte von diesem doppelten Header als Python-list.

Um beispielsweise einen X-Token-Header zu deklarieren, der mehrmals vorkommen kann, können Sie schreiben:

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
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}

Wenn Sie mit dieser Pfadoperation kommunizieren und zwei HTTP-Header senden, wie:

X-Token: foo
X-Token: bar

Dann wäre die Response:

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

Zusammenfassung

Deklarieren Sie Header mit Header, wobei Sie dasselbe gängige Muster wie bei Query, Path und Cookie verwenden.

Und machen Sie sich keine Sorgen um Unterstriche in Ihren Variablen, FastAPI wird sich darum kümmern, sie zu konvertieren.