Перейти до змісту

Дані форми

AI coding agents

Use the official FastAPI skill for your installed version. Install it from your project directory:

uvx library-skills

See Develop with AI.

🌐 Переклад ШІ та людьми

Цей переклад виконано ШІ під керівництвом людей. 🤝

Можливі помилки через неправильне розуміння початкового змісту або неприродні формулювання тощо. 🤖

Ви можете покращити цей переклад, допомігши нам краще спрямовувати AI LLM.

Англійська версія

Коли вам потрібно отримувати поля форми замість JSON, ви можете використовувати Form.

Примітка

Щоб використовувати форми, спочатку встановіть python-multipart.

Додайте його до вашого проєкту:

$ uv add python-multipart

Імпорт Form

Імпортуйте Form з fastapi:

from typing import Annotated

from fastapi import FastAPI, Form

app = FastAPI()


@app.post("/login/")
async def login(username: Annotated[str, Form()], password: Annotated[str, Form()]):
    return {"username": username}
🤓 Other versions and variants

Tip

Prefer to use the Annotated version if possible.

from fastapi import FastAPI, Form

app = FastAPI()


@app.post("/login/")
async def login(username: str = Form(), password: str = Form()):
    return {"username": username}

Оголошення параметрів Form

Створюйте параметри форми так само як ви б створювали Body або Query:

from typing import Annotated

from fastapi import FastAPI, Form

app = FastAPI()


@app.post("/login/")
async def login(username: Annotated[str, Form()], password: Annotated[str, Form()]):
    return {"username": username}
🤓 Other versions and variants

Tip

Prefer to use the Annotated version if possible.

from fastapi import FastAPI, Form

app = FastAPI()


@app.post("/login/")
async def login(username: str = Form(), password: str = Form()):
    return {"username": username}

Наприклад, один зі способів використання специфікації OAuth2 (так званий «потік паролю») вимагає надсилати username та password як поля форми.

специфікація вимагає, щоб ці поля мали точні назви username і password та надсилалися у вигляді полів форми, а не JSON.

З Form ви можете оголошувати ті ж конфігурації, що і з Body (та Query, Path, Cookie), включаючи валідацію, приклади, псевдоніми (наприклад, user-name замість username) тощо.

Примітка

Form - це клас, який безпосередньо наслідується від Body.

Порада

Щоб оголосити тіло форми, потрібно явно використовувати Form, оскільки без нього параметри будуть інтерпретуватися як параметри запиту або тіла (JSON).

Булеві поля форми

Браузери пропускають невстановлені прапорці під час надсилання HTML-форм. Оголосіть булевий параметр форми зі значенням за замовчуванням False, щоб отримувати False, коли прапорець не встановлено:

from typing import Annotated

from fastapi import FastAPI, Form

app = FastAPI()


@app.post("/preferences/")
async def update_preferences(subscribe: Annotated[bool, Form()] = False):
    return {"subscribe": subscribe}
🤓 Other versions and variants

Tip

Prefer to use the Annotated version if possible.

from fastapi import FastAPI, Form

app = FastAPI()


@app.post("/preferences/")
async def update_preferences(subscribe: bool = Form(default=False)):
    return {"subscribe": subscribe}

Встановлений прапорець надсилає своє значення, яке за замовчуванням дорівнює "on". FastAPI приймає "on" як True.

Про «поля форми»

HTML-форми (<form></form>) надсилають дані на сервер у «спеціальному» кодуванні, яке відрізняється від JSON.

FastAPI подбає про те, щоб зчитати ці дані з правильного місця, а не з JSON.

Технічні деталі

Дані з форм зазвичай кодуються за допомогою «типу медіа» application/x-www-form-urlencoded.

Але якщо форма містить файли, вона кодується як multipart/form-data. Ви дізнаєтеся про обробку файлів у наступному розділі.

Ви можете використовувати Form(media_type="multipart/form-data"), щоб описати багаточастинну форму в OpenAPI. Під час поєднання параметрів форми або моделей достатньо встановити це для одного параметра.

Якщо ви хочете дізнатися більше про ці кодування та поля форм, зверніться до MDN вебдокументації для POST.

Попередження

Ви можете оголосити кілька параметрів Form в операції шляху, але не можете одночасно оголосити поля Body, які ви очікуєте отримати у форматі JSON, оскільки запит матиме тіло, закодоване як application/x-www-form-urlencoded, а не application/json.

Це не обмеження FastAPI, а частина HTTP-протоколу.

Підсумок

Використовуйте Form для оголошення вхідних параметрів у вигляді даних форми.