Header-Parameter-Modelle¶

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:

fromtypingimport Annotated
fromfastapiimport FastAPI, Header
frompydanticimport BaseModel
app = FastAPI()
classCommonHeaders(BaseModel):
 host: str
 save_data: bool
 if_modified_since: str | None = None
 traceparent: str | None = None
 x_tag: list[str] = []
@app.get("/items/")
async defread_items(headers: Annotated[CommonHeaders, Header()]):
 return headers

fromfastapiimport FastAPI, Header
frompydanticimport BaseModel
app = FastAPI()
classCommonHeaders(BaseModel):
 host: str
 save_data: bool
 if_modified_since: str | None = None
 traceparent: str | None = None
 x_tag: list[str] = []
@app.get("/items/")
async defread_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):

fromtypingimport Annotated
fromfastapiimport FastAPI, Header
frompydanticimport BaseModel
app = FastAPI()
classCommonHeaders(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 defread_items(headers: Annotated[CommonHeaders, Header()]):
 return headers

fromfastapiimport FastAPI, Header
frompydanticimport BaseModel
app = FastAPI()
classCommonHeaders(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 defread_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.

fromtypingimport Annotated
fromfastapiimport FastAPI, Header
frompydanticimport BaseModel
app = FastAPI()
classCommonHeaders(BaseModel):
 host: str
 save_data: bool
 if_modified_since: str | None = None
 traceparent: str | None = None
 x_tag: list[str] = []
@app.get("/items/")
async defread_items(
 headers: Annotated[CommonHeaders, Header(convert_underscores=False)],
):
 return headers

fromfastapiimport FastAPI, Header
frompydanticimport BaseModel
app = FastAPI()
classCommonHeaders(BaseModel):
 host: str
 save_data: bool
 if_modified_since: str | None = None
 traceparent: str | None = None
 x_tag: list[str] = []
@app.get("/items/")
async defread_items(headers: CommonHeaders = Header(convert_underscores=False)):
 return headers

Zusammenfassung¶

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