Skip to content

Latest commit

 

History

History
213 lines (133 loc) · 11.2 KB

body.md

File metadata and controls

213 lines (133 loc) · 11.2 KB
Raw

Тіло запиту

Коли вам потрібно надіслати дані з клієнта (скажімо, браузера) до вашого API, ви надсилаєте їх як тіло запиту.

Тіло запиту — це дані, надіслані клієнтом до вашого API. Тіло відповіді — це дані, які ваш API надсилає клієнту.

Ваш API майже завжди має надсилати тіло відповіді. Але клієнтам не обов’язково потрібно постійно надсилати тіла запитів.

Щоб оголосити тіло запиту, ви використовуєте Pydantic моделі з усією їх потужністю та перевагами.

!!! info Щоб надіслати дані, ви повинні використовувати один із: POST (більш поширений), PUT, DELETE або PATCH.

Надсилання тіла із запитом `GET` має невизначену поведінку в специфікаціях, проте воно підтримується FastAPI лише для дуже складних/екстремальних випадків використання.

Оскільки це не рекомендується, інтерактивна документація з Swagger UI не відображатиме документацію для тіла запиту під час використання `GET`, і проксі-сервери в середині можуть не підтримувати її.

Імпортуйте BaseModel від Pydantic

Спочатку вам потрібно імпортувати BaseModel з pydantic:

=== "Python 3.8 і вище"

```Python hl_lines="4"
{!> ../../../docs_src/body/tutorial001.py!}
```

=== "Python 3.10 і вище"

```Python hl_lines="2"
{!> ../../../docs_src/body/tutorial001_py310.py!}
```

Створіть свою модель даних

Потім ви оголошуєте свою модель даних як клас, який успадковується від BaseModel.

Використовуйте стандартні типи Python для всіх атрибутів:

=== "Python 3.8 і вище"

```Python hl_lines="7-11"
{!> ../../../docs_src/body/tutorial001.py!}
```

=== "Python 3.10 і вище"

```Python hl_lines="5-9"
{!> ../../../docs_src/body/tutorial001_py310.py!}
```

Так само, як і при оголошенні параметрів запиту, коли атрибут моделі має значення за замовчуванням, він не є обов’язковим. В іншому випадку це потрібно. Використовуйте None, щоб зробити його необов'язковим.

Наприклад, ця модель вище оголошує JSON "об'єкт" (або Python dict), як:

{
    "name": "Foo",
    "description": "An optional description",
    "price": 45.2,
    "tax": 3.5
}

...оскільки description і tax є необов'язковими (зі значенням за замовчуванням None), цей JSON "об'єкт" також буде дійсним:

{
    "name": "Foo",
    "price": 45.2
}

Оголоси її як параметр

Щоб додати модель даних до вашої операції шляху, оголосіть її так само, як ви оголосили параметри шляху та запиту:

=== "Python 3.8 і вище"

```Python hl_lines="18"
{!> ../../../docs_src/body/tutorial001.py!}
```

=== "Python 3.10 і вище"

```Python hl_lines="16"
{!> ../../../docs_src/body/tutorial001_py310.py!}
```

...і вкажіть її тип як модель, яку ви створили, Item.

Результати

Лише з цим оголошенням типу Python FastAPI буде:

  • Читати тіло запиту як JSON.
  • Перетворювати відповідні типи (якщо потрібно).
  • Валідувати дані.
    • Якщо дані недійсні, він поверне гарну та чітку помилку, вказуючи, де саме і які дані були неправильними.
  • Надавати отримані дані у параметрі item.
    • Оскільки ви оголосили його у функції як тип Item, ви також матимете всю підтримку редактора (автозаповнення, тощо) для всіх атрибутів та їх типів.
  • Генерувати JSON Schema визначення для вашої моделі, ви також можете використовувати їх де завгодно, якщо це має сенс для вашого проекту.
  • Ці схеми будуть частиною згенерованої схеми OpenAPI і використовуватимуться автоматичною документацією інтерфейсу користувача.

Автоматична документація

Схеми JSON ваших моделей будуть частиною вашої схеми, згенерованої OpenAPI, і будуть показані в інтерактивній API документації:

А також використовуватимуться в API документації всередині кожної операції шляху, якій вони потрібні:

Підтримка редактора

У вашому редакторі, всередині вашої функції, ви будете отримувати підказки типу та завершення скрізь (це б не сталося, якби ви отримали dict замість моделі Pydantic):

Ви також отримуєте перевірку помилок на наявність операцій з неправильним типом:

Це не випадково, весь каркас був побудований навколо цього дизайну.

І він був ретельно перевірений на етапі проектування, перед будь-яким впровадженням, щоб переконатися, що він працюватиме з усіма редакторами.

Були навіть деякі зміни в самому Pydantic, щоб підтримати це.

Попередні скріншоти були зроблені у Visual Studio Code.

Але ви отримаєте ту саму підтримку редактора у PyCharm та більшість інших редакторів Python:

!!! tip Якщо ви використовуєте PyCharm як ваш редактор, ви можете використати Pydantic PyCharm Plugin.

Він покращує підтримку редакторів для моделей Pydantic за допомогою:

* автозаповнення
* перевірки типу
* рефакторингу
* пошуку
* інспекції

Використовуйте модель

Усередині функції ви можете отримати прямий доступ до всіх атрибутів об’єкта моделі:

=== "Python 3.8 і вище"

```Python hl_lines="21"
{!> ../../../docs_src/body/tutorial002.py!}
```

=== "Python 3.10 і вище"

```Python hl_lines="19"
{!> ../../../docs_src/body/tutorial002_py310.py!}
```

Тіло запиту + параметри шляху

Ви можете одночасно оголошувати параметри шляху та тіло запиту.

FastAPI розпізнає, що параметри функції, які відповідають параметрам шляху, мають бути взяті з шляху, а параметри функції, які оголошуються як моделі Pydantic, взяті з тіла запиту.

=== "Python 3.8 і вище"

```Python hl_lines="17-18"
{!> ../../../docs_src/body/tutorial003.py!}
```

=== "Python 3.10 і вище"

```Python hl_lines="15-16"
{!> ../../../docs_src/body/tutorial003_py310.py!}
```

Тіло запиту + шлях + параметри запиту

Ви також можете оголосити параметри тіло, шлях і запит одночасно.

FastAPI розпізнає кожен з них і візьме дані з потрібного місця.

=== "Python 3.8 і вище"

```Python hl_lines="18"
{!> ../../../docs_src/body/tutorial004.py!}
```

=== "Python 3.10 і вище"

```Python hl_lines="16"
{!> ../../../docs_src/body/tutorial004_py310.py!}
```

Параметри функції будуть розпізнаватися наступним чином:

  • Якщо параметр також оголошено в шляху, він використовуватиметься як параметр шляху.
  • Якщо параметр має сингулярний тип (наприклад, int, float, str, bool тощо), він буде інтерпретуватися як параметр запиту.
  • Якщо параметр оголошується як тип Pydantic моделі, він інтерпретується як тіло запиту.

!!! note FastAPI буде знати, що значення "q" не є обов'язковим через значення за замовчуванням "= None".

`Optional` у `Optional[str]` не використовується FastAPI, але дозволить вашому редактору надати вам кращу підтримку та виявляти помилки.

Без Pydantic

Якщо ви не хочете використовувати моделі Pydantic, ви також можете використовувати параметри Body. Перегляньте документацію для Тіло – Кілька параметрів: сингулярні значення в тілі{.internal-link target=_blank}.