Movatterモバイル変換

[0]ホーム
URL:

Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly

 Sign up
Appearance settings

🌐 Add Ukrainian translation fordocs/uk/docs/tutorial/body-nested-models.md#13409

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to ourterms of service andprivacy statement. We’ll occasionally send you account related emails.

Already on GitHub?Sign in to your account

Merged
Changes fromall commits
Commits
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
245 changes: 245 additions & 0 deletionsdocs/uk/docs/tutorial/body-nested-models.md
View file
Open in desktop
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,245 @@
# Тіло запиту - Вкладені моделі

З **FastAPI** Ви можете визначати, перевіряти, документувати та використовувати моделі, які можуть бути вкладені на будь-яку глибину (завдяки Pydantic).

## Поля списку

Ви можете визначити атрибут як підтип. Наприклад, Python-список (`list`):

{* ../../docs_src/body_nested_models/tutorial001_py310.py hl[12] *}

Це зробить `tags` списком, хоча не визначається тип елементів списку.

## Поля списку з параметром типу

Але Python має специфічний спосіб оголошення списків з внутрішніми типами або "параметрами типу":
### Імпортуємо `List` з модуля typing

У Python 3.9 і вище можна використовувати стандартний `list` для оголошення таких типів, як ми побачимо нижче. 💡

Але в Python версії до 3.9 (від 3.6 і вище) спочатку потрібно імпортувати `List` з модуля стандартної бібліотеки Python `typing`:

{* ../../docs_src/body_nested_models/tutorial002.py hl[1] *}

### Оголошення `list` з параметром типу

Щоб оголосити типи з параметрами типу (внутрішніми типами), такими як `list`, `dict`, `tuple`:

* Якщо Ви використовуєте версію Python до 3.9, імпортуйте їх відповідну версію з модуля `typing`.
* Передайте внутрішні типи як "параметри типу", використовуючи квадратні дужки: `[` and `]`.

У Python 3.9 це буде виглядати так:

```Python
my_list: list[str]
```

У версіях Python до 3.9 це виглядає так:

```Python
from typing import List

my_list: List[str]
```

Це стандартний синтаксис Python для оголошення типів.

Використовуйте той самий стандартний синтаксис для атрибутів моделей з внутрішніми типами.

Отже, у нашому прикладі, ми можемо зробити `tags` саме "списком рядків":

{* ../../docs_src/body_nested_models/tutorial002_py310.py hl[12] *}

## Типи множин

Але потім ми подумали, що теги не повинні повторюватися, вони, ймовірно, повинні бути унікальними рядками.

І Python має спеціальний тип даних для множин унікальних елементів — це `set`.

Тому ми можемо оголосити `tags` як множину рядків:

{* ../../docs_src/body_nested_models/tutorial003_py310.py hl[12] *}

Навіть якщо Ви отримаєте запит з дубльованими даними, він буде перетворений у множину унікальних елементів.

І коли Ви будете виводити ці дані, навіть якщо джерело містить дублікати, вони будуть виведені як множина унікальних елементів.

І це буде анотовано/документовано відповідно.

## Вкладені моделі

Кожен атрибут моделі Pydantic має тип.

Але цей тип сам може бути іншою моделлю Pydantic.

Отже, Ви можете оголосити глибоко вкладені JSON "об'єкти" з конкретними іменами атрибутів, типами та перевірками.

Усе це, вкладене без обмежень.

### Визначення підмоделі

Наприклад, ми можемо визначити модель `Image`:

{* ../../docs_src/body_nested_models/tutorial004_py310.py hl[7:9] *}

### Використання підмоделі як типу

А потім ми можемо використовувати її як тип атрибута:

{* ../../docs_src/body_nested_models/tutorial004_py310.py hl[18] *}

Це означатиме, що **FastAPI** очікуватиме тіло запиту такого вигляду:

```JSON
{
"name": "Foo",
"description": "The pretender",
"price": 42.0,
"tax": 3.2,
"tags": ["rock", "metal", "bar"],
"image": {
"url": "http://example.com/baz.jpg",
"name": "The Foo live"
}
}
```

Завдяки такій декларації у **FastAPI** Ви отримуєте:

* Підтримку в редакторі (автозавершення тощо), навіть для вкладених моделей
* Конвертацію даних
* Валідацію даних
* Автоматичну документацію

## Спеціальні типи та валідація

Окрім звичайних типів, таких як `str`, `int`, `float`, та ін. Ви можете використовувати складніші типи, які наслідують `str`.

Щоб побачити всі доступні варіанти, ознайомтеся з оглядом <a href="https://docs.pydantic.dev/latest/concepts/types/" class="external-link" target="_blank">типів у Pydantic</a>. Деякі приклади будуть у наступних розділах.

Наприклад, у моделі `Image` є поле `url`, тому ми можемо оголосити його як `HttpUrl` від Pydantic замість `str`:

{* ../../docs_src/body_nested_models/tutorial005_py310.py hl[2,8] *}

Рядок буде перевірено як дійсну URL-адресу і задокументовано в JSON Schema / OpenAPI як URL.

## Атрибути зі списками підмоделей

У Pydantic Ви можете використовувати моделі як підтипи для `list`, `set` тощо:

{* ../../docs_src/body_nested_models/tutorial006_py310.py hl[18] *}

Це означає, що **FastAPI** буде очікувати (конвертувати, валідувати, документувати тощо) JSON тіло запиту у вигляді:

```JSON hl_lines="11"
{
"name": "Foo",
"description": "The pretender",
"price": 42.0,
"tax": 3.2,
"tags": [
"rock",
"metal",
"bar"
],
"images": [
{
"url": "http://example.com/baz.jpg",
"name": "The Foo live"
},
{
"url": "http://example.com/dave.jpg",
"name": "The Baz"
}
]
}
```

/// info | Інформація

Зверніть увагу, що тепер ключ `images` містить список об'єктів зображень.

///

## Глибоко вкладені моделі

Ви можете визначати вкладені моделі довільної глибини:

{* ../../docs_src/body_nested_models/tutorial007_py310.py hl[7,12,18,21,25] *}

/// info | Інформація

Зверніть увагу, що в моделі `Offer` є список `Item`ів, які, своєю чергою, можуть мати необов'язковий список `Image`ів.

///

## Тіла запитів, що складаються зі списків

Якщо верхній рівень JSON тіла, яке Ви очікуєте, є JSON `масивом` (у Python — `list`), Ви можете оголосити тип у параметрі функції, як і в моделях Pydantic:

```Python
images: List[Image]
```
або в Python 3.9 і вище:

```Python
images: list[Image]
```

наприклад:

{* ../../docs_src/body_nested_models/tutorial008_py39.py hl[13] *}

## Підтримка в редакторі всюди

Ви отримаєте підтримку в редакторі всюди.

Навіть для елементів у списках:

<img src="/img/tutorial/body-nested-models/image01.png">

Ви не змогли б отримати таку підтримку в редакторі, якби працювали напряму зі `dict`, а не з моделями Pydantic.

Але Вам не потрібно турбуватися про це: вхідні dict'и автоматично конвертуються, а вихідні дані автоматично перетворюються в JSON.

## Тіла з довільними `dict`

Ви також можете оголосити тіло як `dict` з ключами одного типу та значеннями іншого типу.

Це корисно, якщо Ви не знаєте наперед, які імена полів будуть дійсними (як у випадку з моделями Pydantic).

Це буде корисно, якщо Ви хочете приймати ключі, які заздалегідь невідомі.

---

Це також зручно, якщо Ви хочете мати ключі іншого типу (наприклад, `int`).

Ось що ми розглянемо далі.

У цьому випадку Ви можете приймати будь-який `dict`, якщо його ключі — це `int`, а значення — `float`:

{* ../../docs_src/body_nested_models/tutorial009_py39.py hl[7] *}

/// tip | Порада

Майте на увазі, що в JSON тілі ключі можуть бути лише рядками (`str`).

Але Pydantic автоматично конвертує дані.

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

Тобто `dict`, який Ви отримаєте як `weights`, матиме ключі типу `int` та значення типу `float`.

///

## Підсумок

З **FastAPI** Ви маєте максимальну гнучкість завдяки моделям Pydantic, зберігаючи при цьому код простим, коротким та елегантним.

А також отримуєте всі переваги:

* Підтримка в редакторі (автодоповнення всюди!)
* Конвертація даних (парсинг/сериалізація)
* Валідація даних
* Документація схем
* Автоматичне створення документації
[8]ページ先頭
©2009-2026 Movatter.jp