Zum Inhalt

Formulardaten

Wenn Sie Felder aus Formularen statt JSON empfangen mĂŒssen, können Sie Form verwenden.

Info

Um Formulare zu verwenden, installieren Sie zuerst python-multipart.

Erstellen Sie unbedingt eine virtuelle Umgebung, aktivieren Sie diese und installieren Sie dann das Paket, zum Beispiel:

$ pip install python-multipart

Form importieren

Importieren Sie Form von fastapi:

from typing import Annotated

from fastapi import FastAPI, Form

app = FastAPI()


@app.post("/login/")
async def login(username: Annotated[str, Form()], password: Annotated[str, Form()]):
    return {"username": username}
đŸ€“ Other versions and variants

Tip

Prefer to use the Annotated version if possible.

from fastapi import FastAPI, Form

app = FastAPI()


@app.post("/login/")
async def login(username: str = Form(), password: str = Form()):
    return {"username": username}

Form-Parameter definieren

Erstellen Sie Formular-Parameter, so wie Sie es auch mit Body und Query machen wĂŒrden:

from typing import Annotated

from fastapi import FastAPI, Form

app = FastAPI()


@app.post("/login/")
async def login(username: Annotated[str, Form()], password: Annotated[str, Form()]):
    return {"username": username}
đŸ€“ Other versions and variants

Tip

Prefer to use the Annotated version if possible.

from fastapi import FastAPI, Form

app = FastAPI()


@app.post("/login/")
async def login(username: str = Form(), password: str = Form()):
    return {"username": username}

Zum Beispiel stellt eine der Möglichkeiten, die OAuth2-Spezifikation zu verwenden (genannt „password flow“), die Bedingung, einen username und ein password als Formularfelder zu senden.

Die Spec erfordert, dass die Felder exakt username und password genannt werden und als Formularfelder, nicht JSON, gesendet werden.

Mit Form haben Sie die gleichen Konfigurationsmöglichkeiten wie mit Body (und Query, Path, Cookie), inklusive Validierung, Beispielen, einem Alias (z. B. user-name statt username), usw.

Info

Form ist eine Klasse, die direkt von Body erbt.

Tipp

Um Formularbodys zu deklarieren, verwenden Sie explizit Form, da diese Parameter sonst als Query-Parameter oder Body (JSON)-Parameter interpretiert werden wĂŒrden.

Über „Formularfelder“

HTML-Formulare (<form></form>) senden die Daten in einer „speziellen“ Kodierung zum Server, die sich von JSON unterscheidet.

FastAPI stellt sicher, dass diese Daten korrekt ausgelesen werden, statt JSON zu erwarten.

Technische Details

Daten aus Formularen werden normalerweise mit dem „media type“ application/x-www-form-urlencoded kodiert.

Wenn das Formular stattdessen Dateien enthĂ€lt, werden diese mit multipart/form-data kodiert. Im nĂ€chsten Kapitel erfahren Sie mehr ĂŒber die Handhabung von Dateien.

Wenn Sie mehr ĂŒber Formularfelder und ihre Kodierungen lesen möchten, besuchen Sie die MDN-Webdokumentation fĂŒr POST.

Achtung

Sie können mehrere Form-Parameter in einer Pfadoperation deklarieren, aber Sie können nicht gleichzeitig auch Body-Felder deklarieren, welche Sie als JSON erwarten, da der Request den Body mittels application/x-www-form-urlencoded statt application/json kodiert.

Das ist keine Limitation von FastAPI, sondern Teil des HTTP-Protokolls.

Zusammenfassung

Verwenden Sie Form, um Eingabe-Parameter fĂŒr Formulardaten zu deklarieren.