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.
Z. B. 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}
from fastapi import FastAPI, Form
from typing_extensions import Annotated
app = FastAPI()
@app.post("/login/")
async def login(username: Annotated[str, Form()], password: Annotated[str, Form()]):
return {"username": username}
Tipp
Bevorzugen Sie die Annotated-Version, falls möglich.
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}
from fastapi import FastAPI, Form
from typing_extensions import Annotated
app = FastAPI()
@app.post("/login/")
async def login(username: Annotated[str, Form()], password: Annotated[str, Form()]):
return {"username": username}
Tipp
Bevorzugen Sie die Annotated-Version, falls möglich.
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, welche 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.