tiangolo.fastapi/docs/de/docs/tutorial/body.md

Requestbody

Wenn Sie Daten von einem Client (sagen wir, einem Browser) zu Ihrer API senden müssen, senden Sie sie als Requestbody.

Ein Requestbody sind Daten, die vom Client zu Ihrer API gesendet werden. Ein Responsebody sind Daten, die Ihre API zum Client sendet.

Ihre API muss fast immer einen Responsebody senden. Aber Clients müssen nicht unbedingt immer Requestbodys senden, manchmal fordern sie nur einen Pfad an, vielleicht mit einigen Query-Parametern, aber senden keinen Body.

Um einen Requestbody zu deklarieren, verwenden Sie Pydantic-Modelle mit all deren Fähigkeiten und Vorzügen.

/// info | Info

Um Daten zu senden, sollten Sie eines von: POST (meistverwendet), PUT, DELETE oder PATCH verwenden.

Das Senden eines Bodys mit einem GET-Request hat ein undefiniertes Verhalten in den Spezifikationen, wird aber dennoch von FastAPI unterstützt, nur für sehr komplexe/extreme Anwendungsfälle.

Da davon abgeraten wird, zeigt die interaktive Dokumentation mit Swagger-Benutzeroberfläche die Dokumentation für den Body nicht an, wenn GET verwendet wird, und zwischengeschaltete Proxys unterstützen es möglicherweise nicht.

///

Pydantics BaseModel importieren

Zuerst müssen Sie BaseModel von pydantic importieren:

{* ../../docs_src/body/tutorial001_py310.py hl[2] *}

Ihr Datenmodell erstellen

Dann deklarieren Sie Ihr Datenmodell als eine Klasse, die von BaseModel erbt.

Verwenden Sie Standard-Python-Typen für alle Attribute:

{* ../../docs_src/body/tutorial001_py310.py hl[5:9] *}

Wie auch bei der Deklaration von Query-Parametern gilt: Wenn ein Modellattribut einen Defaultwert hat, ist das Attribut nicht erforderlich. Andernfalls ist es erforderlich. Verwenden Sie None, um es einfach optional zu machen.

Zum Beispiel deklariert das obige Modell ein JSON "object" (oder Python-dict) wie dieses:

{
    "name": "Foo",
    "description": "An optional description",
    "price": 45.2,
    "tax": 3.5
}

Da description und tax optional sind (mit None als Defaultwert), wäre folgendes JSON "object" auch gültig:

{
    "name": "Foo",
    "price": 45.2
}

Als Parameter deklarieren

Um es zu Ihrer Pfadoperation hinzuzufügen, deklarieren Sie es auf die gleiche Weise, wie Sie Pfad- und Query-Parameter deklariert haben:

{* ../../docs_src/body/tutorial001_py310.py hl[16] *}

... und deklarieren Sie dessen Typ als das Modell, welches Sie erstellt haben, Item.

Resultate

Mit nur dieser Python-Typdeklaration wird FastAPI:

• Den Requestbody als JSON lesen.
• Die entsprechenden Typen konvertieren (falls nötig).
• Diese Daten validieren.
  • Wenn die Daten ungültig sind, wird ein klar lesbarer Fehler zurückgegeben, der genau anzeigt, wo und was die inkorrekten Daten sind.
• Ihnen die erhaltenen Daten im Parameter item übergeben.
  • Da Sie ihn in der Funktion als vom Typ Item deklariert haben, erhalten Sie auch die volle Unterstützung des Editors (Autovervollständigung, usw.) für alle Attribute und deren Typen.
• JSON Schema-Definitionen für Ihr Modell generieren, die Sie auch überall sonst verwenden können, wenn es für Ihr Projekt Sinn macht.
• Diese Schemas werden Teil des generierten OpenAPI-Schemas und werden von den UIs der automatischen Dokumentation genutzt.

Automatische Dokumentation

Die JSON-Schemas Ihrer Modelle werden Teil Ihres OpenAPI-generierten Schemas und in der interaktiven API-Dokumentation angezeigt:

Und werden auch in der API-Dokumentation innerhalb jeder Pfadoperation, die sie benötigt, verwendet:

Editor-Unterstützung

In Ihrem Editor erhalten Sie innerhalb Ihrer Funktion Typhinweise und Code-Vervollständigung überall (was nicht der Fall wäre, wenn Sie ein dict anstelle eines Pydantic-Modells erhalten hätten):

Sie bekommen auch Fehlermeldungen für inkorrekte Typoperationen:

Das ist nicht zufällig so, das ganze Framework wurde um dieses Design herum aufgebaut.

Und es wurde in der Designphase gründlich getestet, bevor irgendeine Implementierung stattfand, um sicherzustellen, dass es mit allen Editoren funktioniert.

Es gab sogar einige Änderungen an Pydantic selbst, um dies zu unterstützen.

Die vorherigen Screenshots wurden mit Visual Studio Code aufgenommen.

Aber Sie würden die gleiche Editor-Unterstützung in PyCharm und den meisten anderen Python-Editoren erhalten:

/// tip | Tipp

Wenn Sie PyCharm als Ihren Editor verwenden, können Sie das Pydantic PyCharm Plugin ausprobieren.

Es verbessert die Editor-Unterstützung für Pydantic-Modelle, mit:

• Code-Vervollständigung
• Typüberprüfungen
• Refaktorisierung
• Suche
• Inspektionen

///

Das Modell verwenden

Innerhalb der Funktion können Sie alle Attribute des Modellobjekts direkt verwenden:

{* ../../docs_src/body/tutorial002_py310.py *}

Requestbody- + Pfad-Parameter

Sie können Pfad-Parameter und den Requestbody gleichzeitig deklarieren.

FastAPI erkennt, dass Funktionsparameter, die mit Pfad-Parametern übereinstimmen, vom Pfad genommen werden sollen, und dass Funktionsparameter, welche Pydantic-Modelle sind, vom Requestbody genommen werden sollen.

{* ../../docs_src/body/tutorial003_py310.py hl[15:16] *}

Requestbody- + Pfad- + Query-Parameter

Sie können auch zur gleichen Zeit Body-, Pfad- und Query-Parameter deklarieren.

FastAPI wird jeden von ihnen korrekt erkennen und die Daten vom richtigen Ort holen.

{* ../../docs_src/body/tutorial004_py310.py hl[16] *}

Die Funktionsparameter werden wie folgt erkannt:

• Wenn der Parameter auch im Pfad deklariert wurde, wird er als Pfad-Parameter verwendet.
• Wenn der Parameter ein einfacher Typ ist (wie int, float, str, bool, usw.), wird er als Query-Parameter interpretiert.
• Wenn der Parameter vom Typ eines Pydantic-Modells ist, wird er als Requestbody interpretiert.

/// note | Hinweis

FastAPI weiß, dass der Wert von q nicht erforderlich ist, aufgrund des definierten Defaultwertes = None.

Das str | None (Python 3.10+) oder Union in Union[str, None] (Python 3.8+) wird von FastAPI nicht verwendet, um zu bestimmen, dass der Wert nicht erforderlich ist. FastAPI weiß, dass er nicht erforderlich ist, weil er einen Standardwert von = None hat.

Das Hinzufügen der Typannotationen ermöglicht jedoch Ihrem Editor, Ihnen eine bessere Unterstützung zu bieten und Fehler zu erkennen.

///

Ohne Pydantic

Wenn Sie keine Pydantic-Modelle verwenden möchten, können Sie auch Body-Parameter verwenden. Siehe die Dokumentation unter Body – Mehrere Parameter: Einfache Werte im Body{.internal-link target=_blank}.