Paramètres de requête FastAPI

Les paramètres de requête se trouvent dans l'URL?après, avec&Paires clé-valeur séparées. Lorsqu'un paramètre de fonction n'est ni un paramètre de chemin ni un corps de requête, FastAPI l'interprète automatiquement comme un paramètre de requête.


Utilisation de base

Déclarer des paramètres de requête nécessite uniquement d'ajouter des annotations de type et des valeurs par défaut aux paramètres de la fonction :

Exemple

from fastapi import FastAPI

app = FastAPI()

# skip et limit sont des paramètres de requête avec des valeurs par défaut
fake_items_db = [{"item_name": "Foo"}, {"item_name": "Bar"}, {"item_name": "Baz"}]


@app.get("/items/")
async def read_item(skip: int = 0, limit: int = 10):
    # Requête de pagination simulée
    return fake_items_db[skip : skip + limit]

Le format des paramètres de requête dans l'URL :

http://127.0.0.1:8000/items/?skip=0&limit=10

Valeurs des paramètres pour différentes méthodes d'accès :

URLLa valeur de skipvaleur de limitDescription
/items/010Utiliser la valeur par défaut
/items/?skip=202010skip utilise la valeur transmise, limit utilise la valeur par défaut
/items/?skip=20&limit=5205Les deux paramètres utilisent les valeurs transmises

Paramètres optionnels

Définissez la valeur par défaut surNoneVous pouvez déclarer des paramètres de requête optionnels :

Exemple

from fastapi import FastAPI

app = FastAPI()


@app.get("/items/{item_id}")
async def read_item(item_id: str, q: str | None = None):
    # item_id est un paramètre de chemin (requis), q est un paramètre de requête (optionnel)
    if q:
        return {"item_id": item_id, "q": q}
    return {"item_id": item_id}

Iciq: str | None = NoneReprésenteqPeut être une chaîne ouNone, la valeur par défaut estNone。

FastAPI utilise des valeurs par défaut= NoneDétermine si un paramètre est requis, plutôt que par le biais d'annotations de type.str | None. Les annotations de type aident principalement les éditeurs à fournir un meilleur support.


Conversion de type des paramètres de requête

FastAPI prend en charge la conversion automatique des paramètres de requête enboolType :

Exemple

from fastapi import FastAPI

app = FastAPI()


@app.get("/items/{item_id}")
async def read_item(item_id: str, short: bool = False):
    # Le paramètre short est automatiquement converti en booléen
    if short:
        return {"item_id": item_id}
    return {"item_id": item_id, "description": "This is a very long description"}

Dans l'URL suivante, lesshortparamètres seront convertis enTrue:

/items/foo?short=1
/items/foo?short=True
/items/foo?short=true
/items/foo?short=on
/items/foo?short=yes

Les autres valeurs seront converties enFalse。


Paramètre de requête requis

Les paramètres de requête sans valeur par défaut sont des paramètres requis :

Exemple

from fastapi import FastAPI

app = FastAPI()


@app.get("/items/{item_id}")
async def read_item(item_id: str, needy: str):
    # needy n'a pas de valeur par défaut, c'est un paramètre de requête requis
    return {"item_id": item_id, "needy": needy}

Si on y accède/items/foolorsqu'il n'est pas fournineedyparamètre, FastAPI renverra une erreur semblable à la suivante :

{
  "detail": [
    {
      "type": "missing",
      "loc": ["query", "needy"],
      "msg": "Field required",
      "input": null
    }
  ]
}

Mélange de paramètres requis, avec valeur par défaut et optionnels

Vous pouvez mélanger différents types de paramètres de requête dans la même fonction :

Exemple

from fastapi import FastAPI

app = FastAPI()


@app.get("/items/{item_id}")
async def read_item(
    item_id: str,           # Paramètres de chemin (requis)
    needy: str,             # Paramètres de requête requis
    skip: int = 0,          # Paramètres de requête avec valeurs par défaut
    limit: int | None = None,  # Paramètres de requête optionnels
):
    item = {"item_id": item_id, "needy": needy, "skip": skip}
    if limit:
        item.update({"limit": limit})
    return item

Récapitulatif des types de paramètres :

ParamètreMéthode de déclarationObligatoire ?Description
item_iditem_id: strRequisParamètres de chemin, apparaissant dans le chemin de l'URL
needyneedy: strRequisParamètre de requête, sans valeur par défaut
skipskip: int = 0OptionalParamètre de requête, avec valeur par défaut 0
limitlimit: int | None = NoneOptionalParamètre de requête, la valeur par défaut est None

Plusieurs paramètres de chemin et de requête

FastAPI peut reconnaître simultanément plusieurs paramètres de chemin et de requête ; l'ordre de déclaration des paramètres n'affecte pas la reconnaissance :

Exemple

from fastapi import FastAPI

app = FastAPI()


@app.get("/users/{user_id}/items/{item_id}")
async def read_user_item(
    user_id: int,       # Paramètres de chemin
    item_id: str,       # Paramètres de chemin
    q: str | None = None,  # Paramètres de requête facultatifs
    short: bool = False,   # Paramètres de requête avec valeurs par défaut
):
    item = {"item_id": item_id, "owner_id": user_id}
    if q:
        item.update({"q": q})
    if not short:
        item.update({"description": "Ceci est une description très longue"})
    return item

FastAPI associe les variables du chemin par nom de paramètre, donc l'ordre des paramètres de fonction n'a pas d'importance.


Résumé

Points clés des paramètres de requête :

  • Les paramètres avec des valeurs par défaut sont facultatifs, et ceux sans valeur par défaut sont obligatoires.
  • FastAPI convertit automatiquement les chaînes dans l'URL vers le type déclaré.
  • boolPrend en charge plusieurs syntaxes (true、1、on、yesetc.)
  • Les paramètres de requête peuvent être mélangés avec les paramètres de chemin ; l'ordre n'a pas d'importance.
autres extensions