Параметры строки запроса

Параметры строки запроса представляют еще один способ передать в приложение некоторые значения в запросе типа 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

Дополнительно для работы с параметрами строки запроса фреймворк предоставляет класс 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