Aller au contenu

Corps de la requête

🌐 Translation by AI and humans

This translation was made by AI guided by humans. 🤝

It could have mistakes of misunderstanding the original meaning, or looking unnatural, etc. 🤖

You can improve this translation by helping us guide the AI LLM better.

English version

Quand vous avez besoin d'envoyer de la donnée depuis un client (comme un navigateur) vers votre API, vous l'envoyez en tant que corps de requête.

Le corps d'une requête est de la donnée envoyée par le client à votre API. Le corps d'une réponse est la donnée envoyée par votre API au client.

Votre API aura presque toujours à envoyer un corps de réponse. Mais un client n'a pas toujours à envoyer un corps de requête : parfois il demande seulement un chemin, peut-être avec quelques paramètres de requête, mais n'envoie pas de corps.

Pour déclarer un corps de requête, on utilise les modèles de Pydantic en profitant de tous leurs avantages et fonctionnalités.

Info

Pour envoyer de la donnée, vous devriez utiliser : POST (le plus populaire), PUT, DELETE ou PATCH.

Envoyer un corps dans une requête GET a un comportement non défini dans les spécifications, cela est néanmoins supporté par FastAPI, seulement pour des cas d'utilisation très complexes/extrêmes.

Ceci étant découragé, la documentation interactive générée par Swagger UI ne montrera pas de documentation pour le corps d'une requête GET, et les proxys intermédiaires risquent de ne pas le supporter.

Importer le BaseModel de Pydantic

Commencez par importer la classe BaseModel du module pydantic :

from fastapi import FastAPI
from pydantic import BaseModel


class Item(BaseModel):
    name: str
    description: str | None = None
    price: float
    tax: float | None = None


app = FastAPI()


@app.post("/items/")
async def create_item(item: Item):
    return item
🤓 Other versions and variants 
from typing import Union

from fastapi import FastAPI
from pydantic import BaseModel


class Item(BaseModel):
    name: str
    description: Union[str, None] = None
    price: float
    tax: Union[float, None] = None


app = FastAPI()


@app.post("/items/")
async def create_item(item: Item):
    return item

Créer votre modèle de données

Déclarez ensuite votre modèle de données en tant que classe qui hérite de BaseModel.

Utilisez les types Python standard pour tous les attributs :

from fastapi import FastAPI
from pydantic import BaseModel


class Item(BaseModel):
    name: str
    description: str | None = None
    price: float
    tax: float | None = None


app = FastAPI()


@app.post("/items/")
async def create_item(item: Item):
    return item
🤓 Other versions and variants 
from typing import Union

from fastapi import FastAPI
from pydantic import BaseModel


class Item(BaseModel):
    name: str
    description: Union[str, None] = None
    price: float
    tax: Union[float, None] = None


app = FastAPI()


@app.post("/items/")
async def create_item(item: Item):
    return item

Tout comme pour la déclaration de paramètres de requête, quand un attribut de modèle a une valeur par défaut, il n'est pas nécessaire. Sinon, cet attribut doit être renseigné dans le corps de la requête. Utilisez None pour le rendre simplement optionnel.

Par exemple, le modèle ci-dessus déclare un JSON « object » (ou dict Python) tel que :

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

... description et tax étant des attributs optionnels (avec None comme valeur par défaut), ce JSON « object » serait aussi valide :

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

Le déclarer comme paramètre

Pour l'ajouter à votre opération de chemin, déclarez-le comme vous déclareriez des paramètres de chemin ou de requête :

from fastapi import FastAPI
from pydantic import BaseModel


class Item(BaseModel):
    name: str
    description: str | None = None
    price: float
    tax: float | None = None


app = FastAPI()


@app.post("/items/")
async def create_item(item: Item):
    return item
🤓 Other versions and variants 
from typing import Union

from fastapi import FastAPI
from pydantic import BaseModel


class Item(BaseModel):
    name: str
    description: Union[str, None] = None
    price: float
    tax: Union[float, None] = None


app = FastAPI()


@app.post("/items/")
async def create_item(item: Item):
    return item

... et déclarez que son type est le modèle que vous avez créé : Item.

Résultats

En utilisant uniquement les déclarations de type Python, FastAPI réussit à :

  • Lire le contenu de la requête en tant que JSON.
  • Convertir les types correspondants (si nécessaire).
  • Valider la donnée.
    • Si la donnée est invalide, une erreur propre et claire sera renvoyée, indiquant exactement où et quelle était la donnée incorrecte.
  • Passer la donnée reçue dans le paramètre item.
    • Ce paramètre ayant été déclaré dans la fonction comme étant de type Item, vous aurez aussi tout le support offert par l'éditeur (autocomplétion, etc.) pour tous les attributs de ce paramètre et les types de ces attributs.
  • Générer des définitions JSON Schema pour votre modèle ; vous pouvez également les utiliser partout ailleurs si cela a du sens pour votre projet.
  • Ces schémas participeront à la constitution du schéma généré OpenAPI, et seront utilisés par les documentations automatiques UIs.

Documentation automatique

Les schémas JSON de vos modèles seront intégrés au schéma OpenAPI global de votre application, et seront donc affichés dans la documentation interactive de l'API :

Et seront aussi utilisés dans chaque opération de chemin de la documentation utilisant ces modèles :

Support de l'éditeur

Dans votre éditeur, vous aurez des annotations de type et de l'autocomplétion partout dans votre fonction (ce qui n'aurait pas été le cas si vous aviez reçu un dict plutôt qu'un modèle Pydantic) :

Et vous obtenez aussi des vérifications d'erreurs pour les opérations de types incorrectes :

Ce n'est pas un hasard, ce framework entier a été bâti avec ce design comme objectif.

Et cela a été rigoureusement testé durant la phase de design, avant toute implémentation, pour vous assurer que cela fonctionnerait avec tous les éditeurs.

Des changements sur Pydantic ont même été faits pour supporter cela.

Les captures d'écran précédentes ont été prises sur Visual Studio Code.

Mais vous auriez le même support de l'éditeur avec PyCharm et la majorité des autres éditeurs de code Python :

Astuce

Si vous utilisez PyCharm comme éditeur, vous pouvez utiliser le plug-in Pydantic PyCharm Plugin.

Ce qui améliore le support pour les modèles Pydantic avec :

  • de l'autocomplétion
  • des vérifications de type
  • du « refactoring » (ou remaniement de code)
  • de la recherche
  • des inspections

Utiliser le modèle

Dans la fonction, vous pouvez accéder à tous les attributs de l'objet du modèle directement :

from fastapi import FastAPI
from pydantic import BaseModel


class Item(BaseModel):
    name: str
    description: str | None = None
    price: float
    tax: float | None = None


app = FastAPI()


@app.post("/items/")
async def create_item(item: Item):
    item_dict = item.model_dump()
    if item.tax is not None:
        price_with_tax = item.price + item.tax
        item_dict.update({"price_with_tax": price_with_tax})
    return item_dict
🤓 Other versions and variants 
from typing import Union

from fastapi import FastAPI
from pydantic import BaseModel


class Item(BaseModel):
    name: str
    description: Union[str, None] = None
    price: float
    tax: Union[float, None] = None


app = FastAPI()


@app.post("/items/")
async def create_item(item: Item):
    item_dict = item.model_dump()
    if item.tax is not None:
        price_with_tax = item.price + item.tax
        item_dict.update({"price_with_tax": price_with_tax})
    return item_dict

Corps de la requête + paramètres de chemin

Vous pouvez déclarer des paramètres de chemin et un corps de requête pour la même opération de chemin.

FastAPI est capable de reconnaître que les paramètres de la fonction qui correspondent aux paramètres de chemin doivent être récupérés depuis le chemin, et que les paramètres de fonctions déclarés comme modèles Pydantic devraient être récupérés depuis le corps de la requête.

from fastapi import FastAPI
from pydantic import BaseModel


class Item(BaseModel):
    name: str
    description: str | None = None
    price: float
    tax: float | None = None


app = FastAPI()


@app.put("/items/{item_id}")
async def update_item(item_id: int, item: Item):
    return {"item_id": item_id, **item.model_dump()}
🤓 Other versions and variants 
from typing import Union

from fastapi import FastAPI
from pydantic import BaseModel


class Item(BaseModel):
    name: str
    description: Union[str, None] = None
    price: float
    tax: Union[float, None] = None


app = FastAPI()


@app.put("/items/{item_id}")
async def update_item(item_id: int, item: Item):
    return {"item_id": item_id, **item.model_dump()}

Corps de la requête + paramètres de chemin et de requête

Vous pouvez aussi déclarer un corps, et des paramètres de chemin et de requête dans la même opération de chemin.

FastAPI saura reconnaître chacun d'entre eux et récupérer la bonne donnée au bon endroit.

from fastapi import FastAPI
from pydantic import BaseModel


class Item(BaseModel):
    name: str
    description: str | None = None
    price: float
    tax: float | None = None


app = FastAPI()


@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
🤓 Other versions and variants 
from typing import Union

from fastapi import FastAPI
from pydantic import BaseModel


class Item(BaseModel):
    name: str
    description: Union[str, None] = None
    price: float
    tax: Union[float, None] = None


app = FastAPI()


@app.put("/items/{item_id}")
async def update_item(item_id: int, item: Item, q: Union[str, None] = None):
    result = {"item_id": item_id, **item.model_dump()}
    if q:
        result.update({"q": q})
    return result

Les paramètres de la fonction seront reconnus comme tel :

  • Si le paramètre est aussi déclaré dans le chemin, il sera utilisé comme paramètre de chemin.
  • Si le paramètre est d'un type singulier (comme int, float, str, bool, etc.), il sera interprété comme un paramètre de requête.
  • Si le paramètre est déclaré comme ayant pour type un modèle Pydantic, il sera interprété comme faisant partie du corps de la requête.

Remarque

FastAPI saura que la valeur de q n'est pas requise grâce à la valeur par défaut = None.

L'annotation de type str | None (Python 3.10+) ou Union dans Union[str, None] (Python 3.9+) n'est pas utilisée par FastAPI pour déterminer que la valeur n'est pas requise, il le saura parce qu'elle a une valeur par défaut = None.

Mais ajouter ces annotations de type permettra à votre éditeur de vous offrir un meilleur support et de détecter des erreurs.

Sans Pydantic

Si vous ne voulez pas utiliser des modèles Pydantic, vous pouvez aussi utiliser des paramètres de Body. Pour cela, allez voir la documentation sur Corps de la requête - Paramètres multiples : Valeurs singulières dans le corps.