Corps de requête FastAPI
Le corps de requête correspond aux données envoyées par le client à l'API. Lorsque vous devez recevoir des données JSON du client, utilisez le corps de requête pour les transmettre. FastAPI utilise des modèles Pydantic pour déclarer la structure du corps de requête, en effectuant automatiquement la validation des données, la conversion et la génération de documentation.
La différence entre le corps de requête et les paramètres de requête
| Méthodes de transfert de données | Position | Scénarios applicables | Méthodes HTTP |
|---|---|---|---|
| Paramètre de chemin | Chemin d'URL/items/5 | Identifier la ressource | GET, PUT, DELETE, etc. |
| Paramètre de requête | Dans l'URL?key=value | Paramètres optionnels tels que le filtrage et la pagination | Principalement GET |
| corps de requête | Les données JSON de la requête | Soumission de données complexes | POST, PUT, PATCH |
L'envoi de données doit utiliser
POST(le plus courant),PUT、DELETEouPATCHBien que FastAPI prenne techniquement en charge les requêtes GET transportant un corps de requête, cela ne respecte pas les spécifications HTTP, et Swagger UI n'affichera pas la documentation du corps de requête pour les requêtes GET.
Déclarer le corps de la requête avec un modèle Pydantic
Importer BaseModel
from pydantic import BaseModel
2. Créer un modèle de données
Définir une classe héritantBaseModelPour la classe, déclarez tous les attributs en utilisant les types standard de Python :
Exemple
from pydantic import BaseModel
app = FastAPI()
# Définir le modèle de données du corps de la requête
class Item(BaseModel):
name: str # Requis : Nom du produit
description: str | None = None # Facultatif : description du produit
price: float # Obligatoire : prix du produit
tax: float | None = None # Facultatif : taxe
@app.post("/items/")
async def create_item(item: Item):
return item
Les règles pour déterminer si les attributs sont requis sont les mêmes que pour les paramètres de requête :
- Les attributs avec des valeurs par défaut sont facultatifs (par ex.,
description、tax) - Les attributs sans valeur par défaut sont requis (par ex.,
name、price)
Les JSON suivants sont tous des corps de requête valides :
// 包含所有字段
{
"name": "Foo",
"description": "可选描述",
"price": 45.2,
"tax": 3.5
}
// 省略可选字段
{
"name": "Foo",
"price": 45.2
}
La gestion du corps de la requête par FastAPI
Rien qu'en déclarant les types Python, FastAPI peut automatiquement faire ce qui suit :
| Fonctionnalités | Description |
|---|---|
| Lire le corps de la requête | Lire les données de la requête au format JSON |
| Conversion de type | Convertir les données vers les types déclarés (par exemple, chaîne en float) |
| Vérification des données | Valider les données et renvoyer des messages d'erreur clairs lorsqu'elles sont invalides |
| Affecter le paramètre | Affecter les données validées aux paramètres de la fonction, en fournissant l'autocomplétion de l'éditeur |
| Générer la documentation | Générer automatiquement un JSON Schema, qui apparaît dans la documentation de l'API |
Utiliser les attributs du modèle
À l'intérieur de la fonction d'opération de chemin, vous pouvez accéder à tous les attributs du modèle comme vous le feriez sur un objet Python normal :
Exemple
from pydantic import BaseModel
app = FastAPI()
class Item(BaseModel):
name: str
description: str | None = None
price: float
tax: float | None = None
@app.post("/items/")
async def create_item(item: Item):
# Accéder directement aux attributs du modèle
item_dict = item.model_dump() # Pydantic v2 serialization method
if item.tax:
# Calculer le prix TTC
price_with_tax = item.price + item.tax
item_dict.update({"price_with_tax": price_with_tax})
return item_dict
Utilisation de Pydantic v2
model_dump()Remplace la v1dict()méthode pour sérialiser les données du modèle.model_dump()Renvoie un dictionnaire contenant tous les champs du modèle.
Corps de requête + paramètres de chemin
Vous pouvez déclarer des paramètres de chemin et un corps de requête en même temps, et FastAPI récupérera automatiquement les données aux bons endroits :
Exemple
from pydantic import BaseModel
app = FastAPI()
class Item(BaseModel):
name: str
description: str | None = None
price: float
tax: float | None = None
# Utilisation à la fois des paramètres de chemin et du corps de requête
@app.put("/items/{item_id}")
async def update_item(item_id: int, item: Item):
return {"item_id": item_id, "item_name": item.name}
Règles de reconnaissance de FastAPI :
item_iddans le chemin{item_id}apparaît dans -> paramètre de cheminitemLe type est un modèle Pydantic -> corps de la requête
Corps de la requête + paramètres de chemin + paramètres de requête
Les trois peuvent être utilisés simultanément :
Exemple
from pydantic import BaseModel
app = FastAPI()
class Item(BaseModel):
name: str
description: str | None = None
price: float
tax: float | None = None
# Utilisation simultanée des paramètres de chemin, des paramètres de requête et du corps de la requête
@app.put("/items/{item_id}")
async def update_item(item_id: int, item: Item, q: str | None = None):
result = {"item_id": item_id, **item.model_dump()}
if q:
result.update({"q": q})
return result
Règles complètes de reconnaissance des paramètres de FastAPI :
| Condition de reconnaissance | Source du paramètre |
|---|---|
Noms des paramètres dans le chemin{}déclaré dans | Paramètre de chemin |
Le paramètre est d'un type simple (int、str、booletc.) | Paramètre de requête |
| Si le type du paramètre est un modèle Pydantic | corps de requête |
Résumé
Points clés du corps de la requête :
- En utilisant Pydantic
BaseModelDéfinir la structure du corps de la requête - Les champs avec des valeurs par défaut sont facultatifs ; les champs sans valeur par défaut sont obligatoires.
- Le corps de la requête peut être utilisé conjointement avec les paramètres de chemin et les paramètres de requête.
- FastAPI effectue automatiquement la validation des données, la conversion de type et la génération de la documentation.
- Utilisation de Pydantic v2
model_dump()Effectuer la sérialisation