Paramètres de 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.

Quand vous déclarez d'autres paramètres de fonction qui ne font pas partie des paramètres de chemin, ils sont automatiquement interprétés comme des paramètres de « query ».

Python 3.9+

from fastapi import FastAPI

app = FastAPI()

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):
    return fake_items_db[skip : skip + limit]

La query est l'ensemble des paires clé-valeur placées après le ? dans une URL, séparées par des caractères &.

Par exemple, dans l'URL :

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

... les paramètres de requête sont :

skip : avec une valeur de 0
limit : avec une valeur de 10

Comme ils font partie de l'URL, ce sont « naturellement » des chaînes de caractères.

Mais lorsque vous les déclarez avec des types Python (dans l'exemple ci-dessus, en tant que int), ils sont convertis vers ce type et validés par rapport à celui-ci.

Tous les mêmes processus qui s'appliquaient aux paramètres de chemin s'appliquent aussi aux paramètres de requête :

Prise en charge de l'éditeur (évidemment)
« parsing » des données
Validation des données
Documentation automatique

Valeurs par défaut¶

Comme les paramètres de requête ne sont pas une partie fixe d'un chemin, ils peuvent être optionnels et avoir des valeurs par défaut.

Dans l'exemple ci-dessus, ils ont des valeurs par défaut skip=0 et limit=10.

Donc, accéder à l'URL :

http://127.0.0.1:8000/items/

serait équivalent à accéder à :

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

Mais si vous accédez, par exemple, à :

http://127.0.0.1:8000/items/?skip=20

Les valeurs des paramètres dans votre fonction seront :

skip=20 : car vous l'avez défini dans l'URL
limit=10 : car c'était la valeur par défaut

Paramètres optionnels¶

De la même façon, vous pouvez déclarer des paramètres de requête optionnels, en définissant leur valeur par défaut à None :

Python 3.10+

from fastapi import FastAPI

app = FastAPI()


@app.get("/items/{item_id}")
async def read_item(item_id: str, q: str | None = None):
    if q:
        return {"item_id": item_id, "q": q}
    return {"item_id": item_id}

🤓 Other versions and variants

Python 3.9+

from typing import Union

from fastapi import FastAPI

app = FastAPI()


@app.get("/items/{item_id}")
async def read_item(item_id: str, q: Union[str, None] = None):
    if q:
        return {"item_id": item_id, "q": q}
    return {"item_id": item_id}

Dans ce cas, le paramètre de fonction q sera optionnel et vaudra None par défaut.

Vérifications

Notez également que FastAPI est suffisamment intelligent pour remarquer que le paramètre de chemin item_id est un paramètre de chemin et que q ne l'est pas, c'est donc un paramètre de requête.

Conversion des types des paramètres de requête¶

Vous pouvez aussi déclarer des types bool, ils seront convertis :

Python 3.10+

from fastapi import FastAPI

app = FastAPI()


@app.get("/items/{item_id}")
async def read_item(item_id: str, q: str | None = None, short: bool = False):
    item = {"item_id": item_id}
    if q:
        item.update({"q": q})
    if not short:
        item.update(
            {"description": "This is an amazing item that has a long description"}
        )
    return item

🤓 Other versions and variants

Python 3.9+

from typing import Union

from fastapi import FastAPI

app = FastAPI()


@app.get("/items/{item_id}")
async def read_item(item_id: str, q: Union[str, None] = None, short: bool = False):
    item = {"item_id": item_id}
    if q:
        item.update({"q": q})
    if not short:
        item.update(
            {"description": "This is an amazing item that has a long description"}
        )
    return item

Dans ce cas, si vous allez sur :

http://127.0.0.1:8000/items/foo?short=1

ou

http://127.0.0.1:8000/items/foo?short=True

ou

http://127.0.0.1:8000/items/foo?short=true

ou

http://127.0.0.1:8000/items/foo?short=on

ou

http://127.0.0.1:8000/items/foo?short=yes

ou n'importe quelle autre variation de casse (tout en majuscules, uniquement la première lettre en majuscule, etc.), votre fonction verra le paramètre short avec une valeur bool à True. Sinon la valeur sera à False.

Multiples paramètres de chemin et de requête¶

Vous pouvez déclarer plusieurs paramètres de chemin et paramètres de requête en même temps, FastAPI sait lequel est lequel.

Et vous n'avez pas besoin de les déclarer dans un ordre spécifique.

Ils seront détectés par leur nom :

Python 3.10+

from fastapi import FastAPI

app = FastAPI()


@app.get("/users/{user_id}/items/{item_id}")
async def read_user_item(
    user_id: int, item_id: str, q: str | None = None, short: bool = False
):
    item = {"item_id": item_id, "owner_id": user_id}
    if q:
        item.update({"q": q})
    if not short:
        item.update(
            {"description": "This is an amazing item that has a long description"}
        )
    return item

🤓 Other versions and variants

Python 3.9+

from typing import Union

from fastapi import FastAPI

app = FastAPI()


@app.get("/users/{user_id}/items/{item_id}")
async def read_user_item(
    user_id: int, item_id: str, q: Union[str, None] = None, short: bool = False
):
    item = {"item_id": item_id, "owner_id": user_id}
    if q:
        item.update({"q": q})
    if not short:
        item.update(
            {"description": "This is an amazing item that has a long description"}
        )
    return item

Paramètres de requête requis¶

Quand vous déclarez une valeur par défaut pour des paramètres qui ne sont pas des paramètres de chemin (pour l'instant, nous n'avons vu que les paramètres de requête), alors ils ne sont pas requis.

Si vous ne voulez pas leur donner de valeur spécifique mais simplement les rendre optionnels, définissez la valeur par défaut à None.

Mais si vous voulez rendre un paramètre de requête obligatoire, vous pouvez simplement ne déclarer aucune valeur par défaut :

Python 3.9+

from fastapi import FastAPI

app = FastAPI()


@app.get("/items/{item_id}")
async def read_user_item(item_id: str, needy: str):
    item = {"item_id": item_id, "needy": needy}
    return item

Ici, le paramètre de requête needy est un paramètre de requête requis de type str.

Si vous ouvrez dans votre navigateur une URL comme :

http://127.0.0.1:8000/items/foo-item

... sans ajouter le paramètre requis needy, vous verrez une erreur comme :

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

Comme needy est un paramètre requis, vous devez le définir dans l'URL :

http://127.0.0.1:8000/items/foo-item?needy=sooooneedy

... cela fonctionnerait :

{
    "item_id": "foo-item",
    "needy": "sooooneedy"
}

Et bien sûr, vous pouvez définir certains paramètres comme requis, certains avec une valeur par défaut et certains entièrement optionnels :

Python 3.10+

from fastapi import FastAPI

app = FastAPI()


@app.get("/items/{item_id}")
async def read_user_item(
    item_id: str, needy: str, skip: int = 0, limit: int | None = None
):
    item = {"item_id": item_id, "needy": needy, "skip": skip, "limit": limit}
    return item

🤓 Other versions and variants

Python 3.9+

from typing import Union

from fastapi import FastAPI

app = FastAPI()


@app.get("/items/{item_id}")
async def read_user_item(
    item_id: str, needy: str, skip: int = 0, limit: Union[int, None] = None
):
    item = {"item_id": item_id, "needy": needy, "skip": skip, "limit": limit}
    return item

Dans ce cas, il y a 3 paramètres de requête :

needy, un str requis.
skip, un int avec une valeur par défaut de 0.
limit, un int optionnel.

Astuce

Vous pourriez aussi utiliser des Enums de la même façon qu'avec les Paramètres de chemin.