yes0ng
2 months ago
38 changed files with 481 additions and 54 deletions
|
After Width: | Height: | Size: 9.3 KiB |
|
After Width: | Height: | Size: 20 KiB |
|
After Width: | Height: | Size: 6.2 KiB |
@ -0,0 +1,91 @@ |
|||
# Header-параметри |
|||
|
|||
Ви можете визначати параметри заголовків, так само як визначаєте `Query`, `Path` і `Cookie` параметри. |
|||
|
|||
## Імпорт `Header` |
|||
|
|||
Спочатку імпортуйте `Header`: |
|||
|
|||
{* ../../docs_src/header_params/tutorial001_an_py310.py hl[3] *} |
|||
|
|||
## Оголошення параметрів `Header` |
|||
|
|||
Потім оголосіть параметри заголовків, використовуючи ту ж структуру, що й для `Path`, `Query` та `Cookie`. |
|||
|
|||
Ви можете визначити значення за замовчуванням, а також усі додаткові параметри валідації або анотації: |
|||
|
|||
{* ../../docs_src/header_params/tutorial001_an_py310.py hl[9] *} |
|||
|
|||
/// note | Технічні деталі |
|||
|
|||
`Header`є "сестринським" класом для `Path`, `Query` і `Cookie`. Він також успадковується від загального класу `Param`. |
|||
|
|||
Але пам’ятайте, що при імпорті `Query`, `Path`, `Header` та інших із `fastapi`, то насправді вони є функціями, які повертають спеціальні класи. |
|||
|
|||
/// |
|||
|
|||
/// info | Інформація |
|||
|
|||
Щоб оголосити заголовки, потрібно використовувати `Header`, інакше параметри будуть інтерпретуватися як параметри запиту. |
|||
|
|||
/// |
|||
|
|||
## Автоматичне перетворення |
|||
|
|||
`Header` має додатковий функціонал порівняно з `Path`, `Query` та `Cookie`. |
|||
|
|||
Більшість стандартних заголовків розділяються символом «дефіс», також відомим як «мінус» (`-`). |
|||
|
|||
Але змінна, така як `user-agent`, є недійсною в Python. |
|||
|
|||
Тому, за замовчуванням, `Header` автоматично перетворює символи підкреслення (`_`) на дефіси (`-`) для отримання та документування заголовків. |
|||
|
|||
Оскільки заголовки HTTP не чутливі до регістру, Ви можете використовувати стандартний стиль Python ("snake_case"). |
|||
|
|||
Тому Ви можете використовувати `user_agent`, як зазвичай у коді Python, замість того щоб писати з великої літери, як `User_Agent` або щось подібне. |
|||
|
|||
Якщо Вам потрібно вимкнути автоматичне перетворення підкреслень у дефіси, встановіть `convert_underscores` в `Header` значення `False`: |
|||
|
|||
{* ../../docs_src/header_params/tutorial002_an_py310.py hl[10] *} |
|||
|
|||
/// warning | Увага |
|||
|
|||
Перед тим як встановити значення `False` для `convert_underscores` пам’ятайте, що деякі HTTP-проксі та сервери не підтримують заголовки з підкресленнями. |
|||
|
|||
/// |
|||
|
|||
## Дубльовані заголовки |
|||
|
|||
Можливо отримати дубльовані заголовки, тобто той самий заголовок із кількома значеннями. |
|||
|
|||
Це можна визначити, використовуючи список у типізації параметра. |
|||
|
|||
Ви отримаєте всі значення дубльованого заголовка у вигляді `list` у Python. |
|||
|
|||
Наприклад, щоб оголосити заголовок `X-Token`, який може з’являтися більше ніж один раз: |
|||
|
|||
{* ../../docs_src/header_params/tutorial003_an_py310.py hl[9] *} |
|||
|
|||
Якщо Ви взаємодієте з цією операцією шляху, надсилаючи два HTTP-заголовки, наприклад: |
|||
|
|||
``` |
|||
X-Token: foo |
|||
X-Token: bar |
|||
``` |
|||
|
|||
Відповідь буде така: |
|||
|
|||
```JSON |
|||
{ |
|||
"X-Token values": [ |
|||
"bar", |
|||
"foo" |
|||
] |
|||
} |
|||
``` |
|||
|
|||
## Підсумок |
|||
|
|||
Оголошуйте заголовки за допомогою `Header`, використовуючи той самий підхід, що й для `Query`, `Path` та `Cookie`. |
|||
|
|||
Не хвилюйтеся про підкреслення у змінних — **FastAPI** автоматично конвертує їх. |
|||
@ -0,0 +1,175 @@ |
|||
# Запит файлів |
|||
|
|||
Ви можете визначити файли, які будуть завантажуватися клієнтом, використовуючи `File`. |
|||
|
|||
/// info | Інформація |
|||
|
|||
Щоб отримувати завантажені файли, спочатку встановіть <a href="https://github.com/Kludex/python-multipart" class="external-link" target="_blank">python-multipart</a>. |
|||
|
|||
Переконайтеся, що Ви створили [віртуальне середовище](../virtual-environments.md){.internal-link target=_blank}, активували його та встановили пакет, наприклад: |
|||
|
|||
```console |
|||
$ pip install python-multipart |
|||
``` |
|||
|
|||
Це необхідно, оскільки завантажені файли передаються у вигляді "форматованих даних форми". |
|||
|
|||
/// |
|||
|
|||
## Імпорт `File` |
|||
|
|||
Імпортуйте `File` та `UploadFile` з `fastapi`: |
|||
|
|||
{* ../../docs_src/request_files/tutorial001_an_py39.py hl[3] *} |
|||
|
|||
## Визначення параметрів `File` |
|||
|
|||
Створіть параметри файлів так само як Ви б створювали `Body` або `Form`: |
|||
|
|||
{* ../../docs_src/request_files/tutorial001_an_py39.py hl[9] *} |
|||
|
|||
/// info | Інформація |
|||
|
|||
`File` — це клас, який безпосередньо успадковує `Form`. |
|||
|
|||
Але пам’ятайте, що коли Ви імпортуєте `Query`, `Path`, `File` та інші з `fastapi`, це насправді функції, які повертають спеціальні класи. |
|||
|
|||
/// |
|||
|
|||
/// tip | Підказка |
|||
|
|||
Щоб оголосити тіла файлів, Вам потрібно використовувати `File`, тому що інакше параметри будуть інтерпретовані як параметри запиту або параметри тіла (JSON). |
|||
|
|||
/// |
|||
|
|||
Файли будуть завантажені у вигляді "форматованих даних форми". |
|||
|
|||
Якщо Ви оголосите тип параметра функції обробника маршруту як `bytes`, **FastAPI** прочитає файл за Вас, і Ви отримаєте його вміст у вигляді `bytes`. |
|||
|
|||
Однак майте на увазі, що весь вміст буде збережено в пам'яті. Це працюватиме добре для малих файлів. |
|||
|
|||
Але в деяких випадках Вам може знадобитися `UploadFile`. |
|||
|
|||
## Параметри файлу з `UploadFile` |
|||
|
|||
Визначте параметр файлу з типом `UploadFile`: |
|||
|
|||
{* ../../docs_src/request_files/tutorial001_an_py39.py hl[14] *} |
|||
|
|||
Використання `UploadFile` має кілька переваг перед `bytes`: |
|||
|
|||
* Вам не потрібно використовувати `File()` у значенні за замовчуванням параметра. |
|||
* Використовується "буферизований" файл: |
|||
* Файл зберігається в пам'яті до досягнення певного обмеження, після чого він записується на диск. |
|||
* Це означає, що він добре працює для великих файлів, таких як зображення, відео, великі двійкові файли тощо, не споживаючи всю пам'ять. |
|||
Ви можете отримати метадані про завантажений файл. |
|||
* Він має <a href="https://docs.python.org/3/glossary.html#term-file-like-object" class="external-link" target="_blank">file-like</a> `асинхронний файловий інтерфейс` interface. |
|||
* Він надає фактичний об'єкт Python <a href="https://docs.python.org/3/library/tempfile.html#tempfile.SpooledTemporaryFile" class="external-link" target="_blank">`SpooledTemporaryFile`</a>, який можна передавати безпосередньо іншим бібліотекам. |
|||
|
|||
### `UploadFile` |
|||
|
|||
`UploadFile` має такі атрибути: |
|||
|
|||
* `filename`: Рядок `str` з оригінальною назвою файлу, який був завантажений (наприклад, `myimage.jpg`). |
|||
* `content_type`: Рядок `str` з MIME-типом (наприклад, `image/jpeg`). |
|||
* `file`: Об'єкт <a href="https://docs.python.org/3/library/tempfile.html#tempfile.SpooledTemporaryFile" class="external-link" target="_blank">SpooledTemporaryFile</a> (<a href="https://docs.python.org/3/glossary.html#term-file-like-object" class="external-link" target="_blank">файлоподібний</a> об'єкт). Це фактичний файловий об'єкт Python, який можна безпосередньо передавати іншим функціям або бібліотекам, що очікують "файлоподібний" об'єкт. |
|||
|
|||
`UploadFile` має такі асинхронні `async` методи. Вони викликають відповідні методи файлу під капотом (використовуючи внутрішній `SpooledTemporaryFile`). |
|||
|
|||
* `write(data)`: Записує `data` (`str` або `bytes`) у файл. |
|||
* `read(size)`: Читає `size` (`int`) байтів/символів з файлу. |
|||
* `seek(offset)`: Переміщується до позиції `offset` (`int`) у файлі. |
|||
* Наприклад, `await myfile.seek(0)` поверне курсор на початок файлу. |
|||
* This is especially useful if you run `await myfile.read()` once and then need to read the contents again. Це особливо корисно, якщо Ви виконуєте await `await myfile.read()` один раз, а потім потрібно знову прочитати вміст. |
|||
* `close()`: Закриває файл. |
|||
|
|||
Оскільки всі ці методи є асинхронними `async`, Вам потрібно використовувати "await": |
|||
|
|||
Наприклад, всередині `async` *функції обробки шляху* Ви можете отримати вміст за допомогою: |
|||
|
|||
```Python |
|||
contents = await myfile.read() |
|||
``` |
|||
Якщо Ви знаходитесь у звичайній `def` *функції обробки шляху*, Ви можете отримати доступ до `UploadFile.file` безпосередньо, наприклад: |
|||
|
|||
```Python |
|||
contents = myfile.file.read() |
|||
``` |
|||
|
|||
/// note | Технічні деталі `async` |
|||
|
|||
Коли Ви використовуєте `async` методи, **FastAPI** виконує файлові операції у пулі потоків та очікує їх завершення. |
|||
|
|||
/// |
|||
|
|||
/// note | Технічні деталі Starlette |
|||
|
|||
`UploadFile` у **FastAPI** успадковується безпосередньо від `UploadFile` у **Starlette**, але додає деякі необхідні частини, щоб зробити його сумісним із **Pydantic** та іншими компонентами FastAPI. |
|||
|
|||
/// |
|||
|
|||
## Що таке "Form Data" |
|||
|
|||
Спосіб, у який HTML-форми (`<form></form>`) надсилають дані на сервер, зазвичай використовує "спеціальне" кодування, відмінне від JSON. |
|||
|
|||
**FastAPI** забезпечує правильне зчитування цих даних з відповідної частини запиту, а не з JSON. |
|||
|
|||
/// note | Технічні деталі |
|||
|
|||
Дані з форм зазвичай кодуються за допомогою "media type" `application/x-www-form-urlencoded`, якщо вони не містять файлів. |
|||
|
|||
Але якщо форма містить файли, вона кодується у форматі `multipart/form-data`. Якщо Ви використовуєте `File`, **FastAPI** визначить, що потрібно отримати файли з відповідної частини тіла запиту. |
|||
|
|||
Щоб дізнатися більше про ці типи кодування та формові поля, ознайомтеся з <a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/POST" class="external-link" target="_blank"><abbr title="Mozilla Developer Network">документацією MDN</abbr> щодо <code>POST</code></a>. |
|||
|
|||
/// |
|||
|
|||
/// warning | Увага |
|||
|
|||
Ви можете оголосити кілька параметрів `File` і `Form` в *операції шляху*, але Ви не можете одночасно оголошувати поля `Body`, які мають надходити у форматі JSON, оскільки тіло запиту буде закодоване у форматі `multipart/form-data`, а не `application/json`. |
|||
|
|||
Це не обмеження **FastAPI**, а особливість протоколу HTTP. |
|||
|
|||
/// |
|||
|
|||
## Опціональне Завантаження Файлів |
|||
|
|||
Файл можна зробити необов’язковим, використовуючи стандартні анотації типів і встановлюючи значення за замовчуванням `None`: |
|||
|
|||
{* ../../docs_src/request_files/tutorial001_02_an_py310.py hl[9,17] *} |
|||
|
|||
## `UploadFile` із Додатковими Мета Даними |
|||
|
|||
Ви також можете використовувати `File()` разом із `UploadFile`, наприклад, для встановлення додаткових метаданих: |
|||
|
|||
{* ../../docs_src/request_files/tutorial001_03_an_py39.py hl[9,15] *} |
|||
|
|||
## Завантаження Кількох Файлів |
|||
|
|||
Можна завантажувати кілька файлів одночасно. |
|||
|
|||
Вони будуть пов’язані з одним і тим самим "form field", який передається у вигляді "form data". |
|||
|
|||
Щоб це реалізувати, потрібно оголосити список `bytes` або `UploadFile`: |
|||
|
|||
{* ../../docs_src/request_files/tutorial002_an_py39.py hl[10,15] *} |
|||
|
|||
Ви отримаєте, як і було оголошено, `list` із `bytes` або `UploadFile`. |
|||
|
|||
/// note | Технічні деталі |
|||
|
|||
Ви також можете використати `from starlette.responses import HTMLResponse`. |
|||
|
|||
**FastAPI** надає ті ж самі `starlette.responses`, що й `fastapi.responses`, для зручності розробників. Однак більшість доступних відповідей надходять безпосередньо від Starlette. |
|||
|
|||
/// |
|||
|
|||
### Завантаження декількох файлів із додатковими метаданими |
|||
|
|||
Так само як і раніше, Ви можете використовувати `File()`, щоб встановити додаткові параметри навіть для `UploadFile`: |
|||
|
|||
{* ../../docs_src/request_files/tutorial003_an_py39.py hl[11,18:20] *} |
|||
|
|||
## Підсумок |
|||
|
|||
Використовуйте `File`, `bytes`та `UploadFile`, щоб оголошувати файли для завантаження у запитах, які надсилаються у вигляді form data. |
|||
@ -0,0 +1,78 @@ |
|||
# Моделі форм (Form Models) |
|||
|
|||
У FastAPI Ви можете використовувати **Pydantic-моделі** для оголошення **полів форми**. |
|||
|
|||
/// info | Інформація |
|||
|
|||
Щоб використовувати форми, спочатку встановіть <a href="https://github.com/Kludex/python-multipart" class="external-link" target="_blank">python-multipart</a>. |
|||
|
|||
Переконайтеся, що Ви створили [віртуальне середовище](../virtual-environments.md){.internal-link target=_blank}, активували його, а потім встановили бібліотеку, наприклад: |
|||
|
|||
```console |
|||
$ pip install python-multipart |
|||
``` |
|||
|
|||
/// |
|||
|
|||
/// note | Підказка |
|||
|
|||
Ця функція підтримується, починаючи з FastAPI версії `0.113.0`. 🤓 |
|||
|
|||
/// |
|||
|
|||
## Використання Pydantic-моделей для форм |
|||
|
|||
Вам просто потрібно оголосити **Pydantic-модель** з полями, які Ви хочете отримати як **поля форми**, а потім оголосити параметр як `Form`: |
|||
|
|||
{* ../../docs_src/request_form_models/tutorial001_an_py39.py hl[9:11,15] *} |
|||
|
|||
**FastAPI** **витягне** дані для **кожного поля** з **формових даних** у запиті та надасть вам Pydantic-модель, яку Ви визначили. |
|||
|
|||
## Перевірка документації |
|||
|
|||
Ви можете перевірити це в UI документації за `/docs`: |
|||
|
|||
<div class="screenshot"> |
|||
<img src="/img/tutorial/request-form-models/image01.png"> |
|||
</div> |
|||
|
|||
## Заборона додаткових полів форми |
|||
|
|||
У деяких особливих випадках (ймовірно, рідко) Ви можете **обмежити** форму лише тими полями, які були оголошені в Pydantic-моделі, і **заборонити** будь-які **додаткові** поля. |
|||
|
|||
/// note | Підказка |
|||
|
|||
Ця функція підтримується, починаючи з FastAPI версії `0.114.0`. 🤓 |
|||
|
|||
/// |
|||
|
|||
Ви можете використати конфігурацію Pydantic-моделі, щоб заборонити `forbid` будь-які додаткові `extra` поля: |
|||
|
|||
{* ../../docs_src/request_form_models/tutorial002_an_py39.py hl[12] *} |
|||
|
|||
Якщо клієнт спробує надіслати додаткові дані, він отримає **відповідь з помилкою**. |
|||
|
|||
Наприклад, якщо клієнт спробує надіслати наступні поля форми: |
|||
|
|||
* `username`: `Rick` |
|||
* `password`: `Portal Gun` |
|||
* `extra`: `Mr. Poopybutthole` |
|||
|
|||
Він отримає відповідь із помилкою, яка повідомляє, що поле `extra` не дозволено: |
|||
|
|||
```json |
|||
{ |
|||
"detail": [ |
|||
{ |
|||
"type": "extra_forbidden", |
|||
"loc": ["body", "extra"], |
|||
"msg": "Extra inputs are not permitted", |
|||
"input": "Mr. Poopybutthole" |
|||
} |
|||
] |
|||
} |
|||
``` |
|||
|
|||
## Підсумок |
|||
|
|||
Ви можете використовувати Pydantic-моделі для оголошення полів форми у FastAPI. 😎 |
|||
@ -0,0 +1,41 @@ |
|||
# Запити з формами та файлами |
|||
|
|||
У FastAPI Ви можете одночасно отримувати файли та поля форми, використовуючи `File` і `Form`. |
|||
|
|||
/// info | Інформація |
|||
|
|||
Щоб отримувати завантажені файли та/або дані форми, спочатку встановіть <a href="https://github.com/Kludex/python-multipart" class="external-link" target="_blank">python-multipart</a>. |
|||
|
|||
Переконайтеся, що Ви створили [віртуальне середовище](../virtual-environments.md){.internal-link target=_blank}, активували його, а потім встановили бібліотеку, наприклад: |
|||
|
|||
```console |
|||
$ pip install python-multipart |
|||
``` |
|||
|
|||
/// |
|||
|
|||
## Імпорт `File` та `Form` |
|||
|
|||
{* ../../docs_src/request_forms_and_files/tutorial001_an_py39.py hl[3] *} |
|||
|
|||
## Оголошення параметрів `File` та `Form` |
|||
|
|||
Створіть параметри файлів та форми так само як і для `Body` або `Query`: |
|||
|
|||
{* ../../docs_src/request_forms_and_files/tutorial001_an_py39.py hl[10:12] *} |
|||
|
|||
Файли та поля форми будуть завантажені як формові дані, і Ви отримаєте як файли, так і введені користувачем поля. |
|||
|
|||
Ви також можете оголосити деякі файли як `bytes`, а деякі як `UploadFile`. |
|||
|
|||
/// warning | Увага |
|||
|
|||
Ви можете оголосити кілька параметрів `File` і `Form` в операції *шляху*, але не можете одночасно оголошувати `Body`-поля, які очікуєте отримати у форматі JSON, оскільки запит матиме тіло, закодоване за допомогою `multipart/form-data`, а не `application/json`. |
|||
|
|||
Це не обмеження **FastAPI**, а частина протоколу HTTP. |
|||
|
|||
/// |
|||
|
|||
## Підсумок |
|||
|
|||
Використовуйте `File` та `Form` разом, коли вам потрібно отримувати дані форми та файли в одному запиті. |
|||
Loading…
Reference in new issue