Параметры строки запроса представляют еще один способ передать в приложение некоторые значения в запросе типа GET. Для начала надо понимать, что такое строка запроса. Например, возьмем следующий адрес
http://127.0.0.1:8000/users/add?name=Tom&age=38
Здесь та часть, которая идет после адреса сервера и порта и до вопросительного знака ?, то есть users/add
, представляет путь запроса (path). А та часть, которая
идет после вопросительного знака, то есть name=Tom&age=38
, представляет строку запроса (query string). В данной статье нас будет интересовать прежде всего строка запроса.
Строка запроса состоит из параметров. Каждый параметр определяется в форме
имя_параметра=значение_параметра
Если строка запроса содержит несколько параметров, то они одтеляются друг от друга знаком амперсанда &. Так, в примере в адресом http://127.0.0.1:8000/users/add?name=Tom&age=38
строка запроса состоит из двух параметров: параметр name
имеет значение "Tom", а параметр age
имеет значение 38.
Для получения значений параметров строки запроса мы можем в функции определить одноименные параметры:
from fastapi import FastAPI app = FastAPI() @app.get("/users") def get_model(name, age): return {"user_name": name, "user_age": age}
Вполне может быть, что при обращении к приложению пользователь не передаст значения для какого-либо параметра или даже для всех параметров строки запроса. В примере выше все параметры строки запроса являются обязательными. И если мы не передадим хотя бы один из параметров, то мы получим ошибку.
Чтобы ошибки не было, можно задать для параметров значения по умолчанию:
from fastapi import FastAPI app = FastAPI() @app.get("/users") def get_model(name = "Undefined", age = 18): return {"user_name": name, "user_age": age}
Параметры со значению по умолчанию должны идти после обязательных параметров.
Также для параметров строки запроса можно задать ограничения по типу:
from fastapi import FastAPI app = FastAPI() @app.get("/users") def get_model(name: str, age: int = 18): return {"user_name": name, "user_age": age}
В данном случае параметр name должен представлять тип str, то есть строку, а параметр age - целое число. Если параметру age передать нечисловое значение, то мы получим ошибку.
Дополнительно для работы с параметрами строки запроса фреймворк предоставляет класс Query из пакета fastapi
. Класс Query позволяет прежде всего
валидировать значения параметров строки запроса. В частности, через конструктор Query можно установить следующие параметры для валидации значений:
min_length: устанавливает минимальное количество символов в значении параметра
max_length: устанавливает максимальное количество символов в значении параметра
pattern: устанавливает регулярное выражение, которому должно соответствовать значение параметра
lt: значение параметра должно быть меньше определенного значения
le: значение параметра должно быть меньше или равно определенному значению
gt: значение параметра должно быть больше определенного значения
ge: значение параметра должно быть больше или равно определенному значению
Применим некотрые параметры:
from fastapi import FastAPI, Query app = FastAPI() @app.get("/users") def users(name:str = Query(min_length=3, max_length=20)): return {"name": name}
В данном случае через строку запроса получаем параметр name
. Причем его значение должно иметь не меньше 3 и не больше 20 символов.
Подобным образом можно использовать другие параметры валидации:
from fastapi import FastAPI, Query app = FastAPI() @app.get("/users") def users(name:str = Query(min_length=3, max_length=20), age: int = Query(ge=18, lt=111)): return {"name": name, "age": age}
В данном случае добавляется параметр "age", который должен представлять число в диапазоне от 18 (включительно) до 111 (не включая)
Валидация с помощью регулярного значения:
from fastapi import FastAPI, Query app = FastAPI() @app.get("/users") def users(phone:str = Query(pattern=r"^\d{11}$")): return {"phone": phone}
Здесь параметр phone должен состоять из 11 цифр.
Query позволяет установить значение по умолчанию с помощью параметра default
:
from fastapi import FastAPI, Query app = FastAPI() @app.get("/users") def users(name: str = Query(default="Undefined", min_length=2)): return {"name": name}
Здесь, если в запрошенном адресе отстуствует параметр name, то по умолчанию он будет равен строке "Undefined"
Если параметры должны быть необязательными, то параметру default передается значение None
:
from fastapi import FastAPI, Query app = FastAPI() @app.get("/users") def users(name:str | None = Query(default=None, min_length=2)): if name==None: return {"name": "Undefined"} else: return {"name": name}
Использование класса Query позволяет получать через строку запроса списки. В общем случае списки значений передаются, когда в строке запроса одному параметру несколько раз передаются разные значения. Например, как в запросе по следующему адресу:
http://127.0.0.1:8000/users?people=tom&people=Sam&people=Bob
Здесь параметру people передаются три разных значения, соответственно мы ожидаем, что список people будет содержать три элемента.
Определим следующее приложение:
from fastapi import FastAPI, Query app = FastAPI() @app.get("/users") def users(people: list[str] = Query()): return {"people": people}
Здесь функция users имеет один параметр - people
, который должен представлять список строк - тип list[str]
.
Передадим через строку запроса список значений в виде параметра people, например, с помощью запроса http://127.0.0.1:8000/users?people=tom&people=Sam
:
При необходимости можно сочетать параметры пути и строки запроса:
from fastapi import FastAPI, Path, Query app = FastAPI() @app.get("/users/{name}") def users(name:str = Path(min_length=3, max_length=20), age: int = Query(ge=18, lt=111)): return {"name": name, "age": age}
В данном случае параметр name представляет параметр пути, а age - параметр строки запроса. И в данном случае мы могли бы обратиться к функции users, например, посредством адреса http://127.0.0.1:8000/users/Tom?age=38