|
| 1 | +# Модели Header-параметров |
| 2 | + |
| 3 | +Если у вас есть группа связанных **header-параметров**, то вы можете объединить их в одну **Pydantic-модель**. |
| 4 | + |
| 5 | +Это позволит вам **переиспользовать модель** в **разных местах**, а также задать валидацию и метаданные сразу для всех параметров. 😎 |
| 6 | + |
| 7 | +/// note | Заметка |
| 8 | + |
| 9 | +Этот функционал доступен в FastAPI начиная с версии `0.115.0`. 🤓 |
| 10 | + |
| 11 | +/// |
| 12 | + |
| 13 | +## Header-параметры в виде Pydantic-модели |
| 14 | + |
| 15 | +Объявите нужные **header-параметры** в **Pydantic-модели** и затем аннотируйте параметр как `Header`: |
| 16 | + |
| 17 | +{* ../../docs_src/header_param_models/tutorial001_an_py310.py hl[9:14,18] *} |
| 18 | + |
| 19 | +**FastAPI** **извлечёт** данные для **каждого поля** из **заголовков** запроса и выдаст заданную вами Pydantic-модель. |
| 20 | + |
| 21 | +## Проверьте документацию |
| 22 | + |
| 23 | +Вы можете посмотреть нужные header-параметры в графическом интерфейсе сгенерированной документации по пути `/docs`: |
| 24 | + |
| 25 | +<div class="screenshot"> |
| 26 | +<img src="/img/tutorial/header-param-models/image01.png"> |
| 27 | +</div> |
| 28 | + |
| 29 | +## Как запретить дополнительные заголовки |
| 30 | + |
| 31 | +В некоторых случаях (не особо часто встречающихся) вам может понадобиться **ограничить** заголовки, которые вы хотите получать. |
| 32 | + |
| 33 | +Вы можете использовать возможности конфигурации Pydantic-модели для того, чтобы запретить (`forbid`) любые дополнительные (`extra`) поля: |
| 34 | + |
| 35 | +{* ../../docs_src/header_param_models/tutorial002_an_py310.py hl[10] *} |
| 36 | + |
| 37 | +Если клиент попробует отправить **дополнительные заголовки**, то в ответ он получит **ошибку**. |
| 38 | + |
| 39 | +Например, если клиент попытается отправить заголовок `tool` со значением `plumbus`, то в ответ он получит ошибку, сообщающую ему, что header-параметр `tool` не разрешен: |
| 40 | + |
| 41 | +```json |
| 42 | +{ |
| 43 | + "detail": [ |
| 44 | + { |
| 45 | + "type": "extra_forbidden", |
| 46 | + "loc": ["header", "tool"], |
| 47 | + "msg": "Extra inputs are not permitted", |
| 48 | + "input": "plumbus", |
| 49 | + } |
| 50 | + ] |
| 51 | +} |
| 52 | +``` |
| 53 | + |
| 54 | +## Как отключить автоматическое преобразование подчеркиваний |
| 55 | + |
| 56 | +Как и в случае с обычными заголовками, если у вас в именах параметров имеются символы подчеркивания, они **автоматически преобразовываются в дефис**. |
| 57 | + |
| 58 | +Например, если в коде есть header-параметр `save_data`, то ожидаемый HTTP-заголовок будет `save-data` и именно так он будет отображаться в документации. |
| 59 | + |
| 60 | +Если по каким-то причинам вам нужно отключить данное автоматическое преобразование, это можно сделать и для Pydantic-моделей для header-параметров. |
| 61 | + |
| 62 | +{* ../../docs_src/header_param_models/tutorial003_an_py310.py hl[19] *} |
| 63 | + |
| 64 | +/// warning | Внимание |
| 65 | + |
| 66 | +Перед тем как устанавливать для параметра `convert_underscores` значение `False`, имейте в виду, что некоторые HTTP-прокси и серверы не разрешают использовать заголовки с символами подчеркивания. |
| 67 | + |
| 68 | +/// |
| 69 | + |
| 70 | +## Резюме |
| 71 | + |
| 72 | +Вы можете использовать **Pydantic-модели** для объявления **header-параметров** в **FastAPI**. 😎 |
0 commit comments