> ## Documentation Index
> Fetch the complete documentation index at: https://docs.yume.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# Вложения: Прямая загрузка крупных файлов

> Прямая одношаговая загрузка крупных файлов в облачном хранилище через временную ссылку: инициализация, загрузка одним запросом, завершение с созданием вложения.

Когда нужно прикрепить к объекту большой файл, передавать его через сервер приложения неэффективно и ненадёжно. Для
таких случаев предусмотрена прямая загрузка в облачное хранилище: сам файл минует сервер приложения и уходит
напрямую в хранилище одним запросом, а сервер лишь координирует процесс — выдаёт временную ссылку в начале и
закрепляет уже загруженный файл записью-вложением в конце. Результатом успешной загрузки становится обычный
[прикреплённый файл](/ru/logic/attachments/files).

<Info>
  Файл не проходит через сервер приложения. Клиент отправляет его напрямую в хранилище по временной ссылке одним
  запросом — без разбиения на части. Это снимает нагрузку с сервера и позволяет загружать файлы, размер которых
  значительно превышает обычные лимиты запроса.
</Info>

## Логика

Весь процесс доступен только авторизованным пользователям и состоит из двух шагов.

**Шаг 1. Инициализация.** Клиент передаёт имя файла. Система извлекает расширение из имени (в нижнем регистре),
формирует уникальный ключ хранения в папке для файлов, где имя заменяется на случайный идентификатор с сохранением
расширения (так исходное имя в хранилище не фигурирует и коллизии имён исключены), и выдаёт временную ссылку на
прямую загрузку файла в хранилище. В ответ клиент получает саму ссылку и ключ хранения.

<Note>
  Ссылка сознательно не подписывается на конкретный тип содержимого — так подписанным заголовком остаётся только адрес
  хранилища. Это позволяет клиенту не выставлять собственный заголовок типа содержимого, а значит не требует отдельной
  настройки разрешённых заголовков CORS на стороне хранилища.
</Note>

<Warning>
  Временная ссылка на загрузку действует **1 час**. Если загрузка не успевает начаться за это время, ссылку нужно
  запросить заново.
</Warning>

**Шаг 2. Завершение и создание вложения.** После успешной загрузки клиент вызывает завершение и передаёт:

| Поле                  | Тип    | Назначение                                      |
| --------------------- | ------ | ----------------------------------------------- |
| Ключ хранения         | строка | Путь файла в хранилище, полученный на шаге 1    |
| Тип объекта           | текст  | Имя вида родительского объекта                  |
| Идентификатор объекта | число  | Идентификатор конкретного родительского объекта |
| Категория             | текст  | Необязательная метка-категория файла            |
| Имя файла             | текст  | Необязательное название                         |

По имени типа объекта определяется вид родительского объекта, а расширение вычисляется из ключа хранения (если
определить не удалось — применяется значение по умолчанию для двоичных данных). Затем создаётся запись-вложение:
компания и автор берутся из контекста запроса, категория и название — из запроса (если указаны), а привязка
к объекту — из переданных типа и идентификатора объекта. Ссылка на сам файл устанавливается на уже загруженный объект
хранилища по его ключу — файл повторно не загружается.

<Info>
  На шаге завершения новый файл не передаётся — запись-вложение лишь «закрепляется» за уже загруженным в хранилище
  файлом. Вложение в системе появляется только после успешного завершения.
</Info>

## Особенности поведения

Прочие особенности:

* **Определение вида родительского объекта идёт только по имени вида** без учёта приложения — при совпадении имён в разных приложениях поиск завершится ошибкой из-за неоднозначности.
* **Обязательные поля берутся напрямую, без предварительной проверки** — отсутствие имени файла или ключа хранения приведёт к внутренней ошибке вместо аккуратного ответа о некорректном запросе.
* **Расширение вычисляется из ключа хранения** (то есть из исходного имени файла на шаге инициализации), а не из типа содержимого; при отсутствии расширения подставляется значение по умолчанию для двоичных данных.