tiangolo.fastapi/docs/ru/docs/tutorial/query-params.md

Query-параметры

Когда вы объявляете параметры функции, которые не являются частью path-параметров, они автоматически интерпретируются как "query"-параметры.

{* ../../docs_src/query_params/tutorial001_py310.py hl[9] *}

Query — это набор пар ключ-значение, которые идут после знака ? в URL-адресе, разделенные символами &.

Например, в этом URL-адресе:

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

...query-параметры такие:

• skip: со значением 0
• limit: со значением 10

Будучи частью URL-адреса, они "естественным образом" являются строками.

Но когда вы объявляете их с использованием типов Python (в примере выше, как int), они конвертируются в указанный тип данных и проходят проверку на соответствие ему.

Все те же процессы, которые применяются к path-параметрам, также применяются и к query-параметрам:

• Поддержка от редактора кода (очевидно)
• "Парсинг" данных
• Валидация данных
• Автоматическая документация

Значения по умолчанию

Поскольку query-параметры не являются фиксированной частью пути, они могут быть необязательными и иметь значения по умолчанию.

В примере выше значения по умолчанию равны skip=0 и limit=10.

Таким образом, результат перехода по URL-адресу:

http://127.0.0.1:8000/items/

будет таким же, как если перейти по:

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

Но если вы перейдёте, например, по:

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

Значения параметров в вашей функции будут:

• skip=20: потому что вы установили это в URL-адресе
• limit=10: потому что это было значение по умолчанию

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

Аналогично, вы можете объявлять необязательные query-параметры, установив их значение по умолчанию, равное None:

{* ../../docs_src/query_params/tutorial002_py310.py hl[7] *}

В этом случае параметр функции q будет необязательным и будет иметь значение None по умолчанию.

/// tip | Подсказка

Также обратите внимание, что FastAPI достаточно умён, чтобы заметить, что path-параметр item_id является path-параметром, а q — нет, поэтому это query-параметр.

///

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

Вы также можете объявлять типы bool, и они будут преобразованы:

{* ../../docs_src/query_params/tutorial003_py310.py hl[7] *}

В этом случае, если вы перейдёте по:

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

или

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

или

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

или

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

или

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

или в любом другом варианте написания (в верхнем регистре, с заглавной буквой и т.п.), внутри вашей функции параметр short будет иметь значение True типа данных bool. В противном случае — False.

Несколько path-параметров и query-параметров

Вы можете объявлять несколько path-параметров и query-параметров одновременно, FastAPI знает, что чем является.

И вы не обязаны объявлять их в каком-либо определенном порядке.

Они будут обнаружены по именам:

{* ../../docs_src/query_params/tutorial004_py310.py hl[6,8] *}

Обязательные query-параметры

Когда вы объявляете значение по умолчанию для параметра, который не является path-параметром (в этом разделе мы пока что рассмотрели только query-параметры), то он не является обязательным.

Если вы не хотите задавать конкретное значение, но хотите просто сделать параметр необязательным, установите значение по умолчанию равным None.

Но если вы хотите сделать query-параметр обязательным, вы можете просто не указывать значение по умолчанию:

{* ../../docs_src/query_params/tutorial005_py310.py hl[6:7] *}

Здесь query-параметр needy является обязательным query-параметром с типом данных str.

Если вы откроете в браузере URL-адрес вроде:

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

...без добавления обязательного параметра needy, вы увидите ошибку вроде:

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

Поскольку needy является обязательным параметром, вам необходимо указать его в URL-адресе:

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

...это будет работать:

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

И, конечно, вы можете определить некоторые параметры как обязательные, некоторые — со значением по умолчанию, а некоторые — полностью необязательные:

{* ../../docs_src/query_params/tutorial006_py310.py hl[8] *}

В этом случае есть 3 query-параметра:

• needy, обязательный str.
• skip, int со значением по умолчанию 0.
• limit, необязательный int.

/// tip | Подсказка

Вы можете использовать Enum так же, как ранее применяли его с Path-параметрами.

///