Header-Parameter¶
So wie Query-, Path-, und Cookie-Parameter können Sie auch Header-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}
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}
Tipp
Bevorzugen Sie die Annotated-Version, falls möglich.
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}
Tipp
Bevorzugen Sie die Annotated-Version, falls möglich.
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¶
Dann deklarieren Sie Ihre Header-Parameter, auf die gleiche Weise, wie Sie auch Path-, Query-, und Cookie-Parameter deklarieren.
Der erste Wert ist der Typ. Sie können Header die gehabten Extra Validierungs- und Beschreibungsparameter hinzufügen. Danach können Sie einen Defaultwert vergeben:
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}
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}
Tipp
Bevorzugen Sie die Annotated-Version, falls möglich.
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}
Tipp
Bevorzugen Sie die Annotated-Version, falls möglich.
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 Schwesterklasse von Path, Query und Cookie. Sie erbt von derselben gemeinsamen Param-Elternklasse.
Aber erinnern Sie sich, dass, wenn Sie Query, Path, Header und andere von fastapi importieren, diese tatsächlich Funktionen sind, welche spezielle Klassen zurückgeben.
Info
Um Header zu deklarieren, müssen Sie Header verwenden, da diese Parameter sonst als Query-Parameter interpretiert werden würden.
Automatische Konvertierung¶
Header hat weitere Funktionalität, zusätzlich zu der, die Path, Query und Cookie bereitstellen.
Die meisten Standard-Header benutzen als Trennzeichen einen Bindestrich, auch bekannt als das „Minus-Symbol“ (-).
Aber eine Variable wie user-agent ist in Python nicht gültig.
Darum wird Header standardmäßig in Parameternamen den Unterstrich (_) zu einem Bindestrich (-) konvertieren.
HTTP-Header sind außerdem unabhängig von Groß-/Kleinschreibung, darum können Sie sie mittels der Standard-Python-Schreibweise deklarieren (auch bekannt als "snake_case").
Sie können also user_agent schreiben, wie Sie es normalerweise in Python-Code machen würden, statt etwa die ersten Buchstaben groß zu schreiben, wie in User_Agent.
Wenn Sie aus irgendeinem Grund das automatische Konvertieren von Unterstrichen zu Bindestrichen abschalten möchten, setzen Sie den Parameter convert_underscores 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}
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}
Tipp
Bevorzugen Sie die Annotated-Version, falls möglich.
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}
Tipp
Bevorzugen Sie die Annotated-Version, falls möglich.
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. Also den gleichen Header mit unterschiedlichen Werten.
Sie können solche Fälle deklarieren, indem Sie in der Typdeklaration eine Liste verwenden.
Sie erhalten dann alle Werte von diesem doppelten Header als Python-liste.
Um zum Beispiel einen Header X-Token zu deklarieren, der mehrmals vorkommen kann, schreiben Sie:
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}
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}
Tipp
Bevorzugen Sie die Annotated-Version, falls möglich.
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}
Tipp
Bevorzugen Sie die Annotated-Version, falls möglich.
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}
Tipp
Bevorzugen Sie die Annotated-Version, falls möglich.
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 einer Pfadoperation kommunizieren, die zwei HTTP-Header sendet, wie:
X-Token: foo
X-Token: bar
Dann wäre die Response:
{
"X-Token values": [
"bar",
"foo"
]
}
Zusammenfassung¶
Deklarieren Sie Header mittels Header, auf die gleiche Weise wie bei Query, Path und Cookie.
Machen Sie sich keine Sorgen um Unterstriche in ihren Variablen, FastAPI wird sich darum kümmern, diese zu konvertieren.