Query-параметры FastAPI

Query-параметры находятся в URL?после, с&Разделённые пары ключ-значение. Когда параметр функции не является ни параметром пути, ни телом запроса, FastAPI автоматически интерпретирует его как query-параметр.

Базовое использование

Для объявления параметров запроса достаточно добавить аннотации типов и значения по умолчанию к параметрам функции:

Пример

from fastapi import FastAPI

app = FastAPI()

# skip и limit — параметры запроса со значениями по умолчанию
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):
    # Mock-запрос пагинации
    return fake_items_db[skip : skip + limit]

Формат параметров запроса в URL:

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

Значения параметров для разных способов доступа:

URLЗначение skipзначение limitОписание
/items/010Использовать значение по умолчанию
/items/?skip=202010skip использует переданное значение, limit использует значение по умолчанию
/items/?skip=20&limit=5205Оба параметра используют переданные значения

Необязательные параметры

Установите значение по умолчанию равнымNoneВы можете объявить необязательные параметры запроса:

Пример

from fastapi import FastAPI

app = FastAPI()


@app.get("/items/{item_id}")
async def read_item(item_id: str, q: str | None = None):
    # item_id — параметр пути (обязательный), q — параметр запроса (необязательный)
    if q:
        return {"item_id": item_id, "q": q}
    return {"item_id": item_id}

Здесьq: str | None = NoneПредставляетqМожет быть строкой илиNone, значение по умолчанию —None。

FastAPI использует значения по умолчанию= NoneОпределяет, является ли параметр обязательным, а не через аннотации типов.str | None. Аннотации типов в основном помогают редакторам обеспечивать лучшую поддержку.

Преобразование типов параметров запроса

FastAPI поддерживает автоматическое преобразование параметров запроса вboolТип:

Пример

from fastapi import FastAPI

app = FastAPI()


@app.get("/items/{item_id}")
async def read_item(item_id: str, short: bool = False):
    # Параметр short автоматически преобразуется в логическое значение
    if short:
        return {"item_id": item_id}
    return {"item_id": item_id, "description": "Это очень длинное описание"}

В следующем URLshortпараметры будут преобразованы вTrue：

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

Другие значения будут преобразованы вFalse。

Обязательный параметр запроса

Параметры запроса без значений по умолчанию являются обязательными параметрами:

Пример

from fastapi import FastAPI

app = FastAPI()


@app.get("/items/{item_id}")
async def read_item(item_id: str, needy: str):
    # needy не имеет значения по умолчанию, это обязательный параметр запроса
    return {"item_id": item_id, "needy": needy}

Если обратиться/items/fooесли не указанneedyпараметр, FastAPI вернёт ошибку, подобную следующей:

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

Смешивание обязательных, параметров со значениями по умолчанию и необязательных параметров

Вы можете смешивать различные типы параметров запроса в одной функции:

Пример

from fastapi import FastAPI

app = FastAPI()


@app.get("/items/{item_id}")
async def read_item(
    item_id: str,           # Параметры пути (обязательные)
    needy: str,             # Обязательные параметры запроса
    skip: int = 0,          # Параметры запроса со значениями по умолчанию
    limit: int | None = None,  # Необязательные параметры запроса
):
    item = {"item_id": item_id, "needy": needy, "skip": skip}
    if limit:
        item.update({"limit": limit})
    return item

Сводка по типам параметров:

ПараметрСпособ объявленияОбязательно?Описание
item_iditem_id: strОбязательныйПараметры пути, появляющиеся в URL-пути
needyneedy: strОбязательныйПараметр запроса, без значения по умолчанию
skipskip: int = 0OptionalПараметр запроса со значением по умолчанию 0
limitlimit: int | None = NoneOptionalПараметр запроса, значение по умолчанию — None

Несколько параметров пути и параметров запроса

FastAPI может распознавать несколько параметров пути и параметров запроса одновременно; порядок объявления параметров не влияет на распознавание:

Пример

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 a very long description"})
    return item

FastAPI сопоставляет переменные в пути по имени параметра, поэтому порядок параметров функции не имеет значения.

Итог

Ключевые моменты параметров запроса:

  • Параметры со значениями по умолчанию необязательны, а без значений по умолчанию — обязательны.
  • FastAPI автоматически преобразует строки в URL к объявленному типу.
  • boolТип поддерживает несколько синтаксисов (true、1、on、yesи т.д.)
  • Параметры запроса можно смешивать с параметрами пути; порядок не имеет значения.
Другие расширения