Header-Parameter-Modelle¶

uvx library-skills

Wenn Sie eine Gruppe verwandter Header-Parameter haben, können Sie ein Pydantic-Modell erstellen, um diese zu deklarieren.

Dadurch können Sie das Modell an mehreren Stellen wiederverwenden und auch Validierungen und Metadaten für alle Parameter gleichzeitig deklarieren. 😎

Header-Parameter mit einem Pydantic-Modell¶

Deklarieren Sie die erforderlichen Header-Parameter in einem Pydantic-Modell und dann den Parameter als 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 wird die Daten für jedes Feld aus den Headern des Request extrahieren und Ihnen das von Ihnen definierte Pydantic-Modell geben.

Die Dokumentation testen¶

Sie können die erforderlichen Header in der Dokumentationsoberfläche unter /docs sehen:

Zusätzliche Header verbieten¶

In einigen speziellen Anwendungsfällen (wahrscheinlich nicht sehr häufig) möchten Sie möglicherweise die Header einschränken, die Sie erhalten möchten.

Sie können Pydantics Modellkonfiguration verwenden, um extra Felder zu verbieten (forbid):

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

Wenn ein Client versucht, einige zusätzliche Header zu senden, erhält er eine Error-Response.

Zum Beispiel, wenn der Client versucht, einen tool-Header mit einem Wert von plumbus zu senden, erhält er eine Error-Response, die ihm mitteilt, dass der Header-Parameter tool nicht erlaubt ist:

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

Automatische Umwandlung von Unterstrichen deaktivieren¶

Ähnlich wie bei regulären Header-Parametern werden bei der Verwendung von Unterstrichen in den Parameternamen diese automatisch in Bindestriche umgewandelt.

Wenn Sie beispielsweise einen Header-Parameter save_data im Code haben, wird der erwartete HTTP-Header save-data sein, und er wird auch so in der Dokumentation angezeigt.

Falls Sie aus irgendeinem Grund diese automatische Umwandlung deaktivieren müssen, können Sie dies auch für Pydantic-Modelle für Header-Parameter tun.

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

Parametermodelle kombinieren¶

Sie können mehrere Header-Parameter-Modelle mit einzelnen Header-Parametern und Abhängigkeiten kombinieren. Jedes Modell wird unabhängig extrahiert und validiert, wie für Query-Parameter-Modelle erklärt.

Die extra-Konfiguration jedes Modells gilt für alle Header-Parameter, einschließlich derjenigen, die in anderen Modellen oder Abhängigkeiten deklariert sind. Mit extra="forbid" wird jeder Header außerhalb dieses Modells abgelehnt. Mit extra="allow" werden diese Header als zusätzliche Felder des Modells aufgenommen.

Jedes Modell verwendet seine eigene Einstellung für Header(convert_underscores=...), sowohl beim Lesen des Requests als auch beim Generieren von OpenAPI. Explizite Feld-Aliasse bleiben unveränderte Headernamen.

Optionale Header-Parameter-Modelle¶

Deklarieren Sie ein Header-Parameter-Modell mit | None und einem Defaultwert von None, um die Gruppe optional zu machen.

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

Wenn weder x-client-name noch x-client-version gesendet wird, ist client gleich None. Wenn einer von beiden gesendet wird, validiert FastAPI das Modell und erfordert beide Felder.

Es gelten dieselben Regeln für Defaultwerte, zusätzliche Felder und OpenAPI wie für optionale Query-Parameter-Modelle.

Header wie Host folgen ebenfalls der extra-Konfiguration des Modells. Mit extra="allow" führen sie dazu, dass das Modell vorhanden ist, selbst wenn keines der beiden deklarierten Felder übermittelt wird.

Zusammenfassung¶

Sie können Pydantic-Modelle verwenden, um Header in FastAPI zu deklarieren. 😎