Файлы проекта и логические бакеты

Логический бакет — отдельное пространство файлов внутри проекта и одного окружения. Он хранит понятный адрес и правила загрузок, но не раскрывает устройство облачного хранилища или служебные ключи.

На странице «Файлы» можно создавать, просматривать, настраивать и удалять логические бакеты, загружать файлы и явно включать профили анонимной загрузки для доверенных адресов сайтов. Те же действия доступны через Platform API.

Публичная форма может получить защищённую session, загрузить один файл по короткой POST-форме и завершить проверку без Platform или Runtime token в браузере.

Backend приложения может безопасно и повторяемо привязать завершённую anonymous session к одному заказу через Runtime SDK. Public status, проверка содержимого и выдача файла выполняются через короткую защищённую ссылку.

• Нужно заранее разделить файлы production и development.
• Для разных групп файлов нужны разные ограничения размера или форматов.
• Нужно загрузить файл без передачи платформенного токена сервису хранения.
• Нужно принять файл из формы заказа или лендинга без привилегированного токена в браузере.

• Раздел «Файлы» включается для организаций поэтапно. Если пункта нет в навигации проекта или прямая ссылка показывает страницу 404, организация ещё не подключена к бете; дополнительных действий от пользователя не требуется.
• Выберите проект и окружение.
• Для просмотра нужна роль участника платформы, разработчика или администратора проекта.
• Для создания, изменения и удаления нужна роль разработчика или администратора проекта.
• Для загрузки подходит роль участника платформы, разработчика или администратора проекта.
• Профили анонимной загрузки создают, изменяют и отключают разработчики и администраторы проекта; участник платформы может их просматривать.
• Обычный максимальный размер одного файла — 100 МБ.
• Для обычной, не анонимной PUT-загрузки заранее вычислите SHA-256 файла в нижнем регистре.

1. Откройте проект, выберите окружение в меню слева и перейдите в раздел «Файлы».
2. Нажмите «Создать бакет». Укажите короткий адрес, доступ по умолчанию, максимальный размер и при необходимости правила форматов и хранения. Адрес после создания не меняется.
3. Выберите бакет слева и нажмите «Загрузить файл». Перетащите один файл в окно или выберите его, задайте доступ и подтвердите загрузку. Индикатор показывает подготовку, передачу и проверку. При ошибке нажмите «Повторить загрузку»: выбранный файл и параметры сохраняются. Если сменить файл или доступ, начинается новая попытка.
4. После передачи дождитесь готовности в списке. Уведомление «Файл передан на проверку» ещё не означает, что его можно скачать. Пустой файл, превышение размера и запрещённый формат отмечаются до отправки.
5. Используйте поиск по названию, фильтр типа и сортировку по дате, имени или размеру. Нажмите название файла, чтобы открыть сведения: размер, доступ, статус, дату загрузки и срок хранения. Для готовых публичных изображений доступен предпросмотр; остальные готовые файлы можно скачать.
6. Для готового публичного файла скопируйте стабильную ссылку. Короткая ссылка для скачивания запрашивается при нажатии и открывается сразу.
7. Нажмите «Использование», чтобы открыть данные хранения и доставки за расчётный период организации. Хранение показывается по ставке 8 ₽ за ГиБ·месяц как предварительная оценка. Доставка пока отображается справочно по будущей ставке 4 ₽ за ГиБ без списания. Фактические расходы смотрите в разделе «Баланс и расходы».
8. Откройте «Настройки бакета», чтобы изменить ограничения. Если закрыть изменённую форму, появится выбор: продолжить редактирование или закрыть без сохранения. При ошибке сохранения введённые значения остаются в форме.
9. Для удаления файла подтвердите действие в отдельном окне. Удалить бакет можно только после удаления его файлов и отключения активных профилей; интерфейс сначала проверяет эти условия.

Участник платформы может просматривать и загружать файлы. Управлять бакетами, удалять файлы и изменять профили могут разработчики и администраторы проекта, а также владелец организации.

Приватные файлы выдаёт backend приложения, файлы для пользователей — активная сессия пользователя приложения, командные — участник проекта, публичные — любой получатель ссылки на конкретный готовый файл. Публичного списка файлов нет.

1. Откройте Swagger вашего Agnostic API и авторизуйтесь токеном Platform Auth.
2. В разделе Files выберите создание бакета для нужного проекта.
3. Укажите окружение и короткий адрес латиницей, цифрами и дефисами.
4. Выберите режим доступа по умолчанию: приватный, для вошедших пользователей приложения, для команды проекта или публичный.
5. При необходимости добавьте разрешённые и заблокированные MIME-типы, уменьшите максимальный размер файла и задайте срок хранения готовых файлов.
6. Используйте операции Files для просмотра или изменения бакета. Всегда передавайте то же окружение, в котором он создан.

1. Создайте profile операцией POST .../buckets/{bucketId}/anonymous-upload-profiles в нужном проекте и окружении.
2. Укажите только точные HTTP/HTTPS origins без пути, query, fragment и wildcard. Например, https://shop.example.com, но не https://shop.example.com/upload.
3. Задайте разрешённые MIME-типы и лимиты одного файла, количества файлов и общего размера session. Они не могут быть шире правил бакета.
4. Выберите claim policy: ready_only для обязательной готовности всех файлов или allow_processing, если заказ можно принять во время проверки.
5. Проверьте ответ: CAPTCHA всегда обязательна, а начальный доступ всегда приватный. Для отключения profile используйте DELETE; повторное отключение безопасно.

Стартовые значения: до 15 МБ на файл, пять файлов и 50 МБ на session, session TTL 30 минут, grant TTL 5 минут, хранение незаявленных файлов до 24 часов. Grant TTL можно выбрать только от 2 до 5 минут.

Публичный идентификатор profile не является секретной ссылкой и сам по себе не разрешает загрузку. Загрузку разрешает только короткая session после CAPTCHA и проверки точного origin.

1. Выберите способ создания session. Для управляемого варианта браузер вызывает POST /api/v1/files/public/anonymous/profiles/{publicId}/sessions с точным заголовком Origin и токеном CAPTCHA. Для BFF-варианта backend приложения вызывает POST /api/v1/runtime/files/buckets/{bucketId}/anonymous-upload-sessions; Runtime token остаётся только на backend и никогда не попадает в браузер.
2. Получите sessionToken и claimToken. Они показываются один раз. Держите их только в памяти текущего сценария, не помещайте в URL, логи, аналитику или постоянное хранилище браузера.
3. Для каждого файла вызовите POST /api/v1/files/public/anonymous/profiles/{publicId}/grants. Передайте sessionToken как Bearer token, тот же точный Origin, имя, MIME-тип, размер и уникальный idempotencyKey.
4. Создайте multipart/form-data из всех выданных fields без изменений и добавьте ровно один file последней частью. Отправьте форму на uploadUrl. Не добавляйте redirect и не меняйте приватный режим, MIME-тип, ключ или размер.
5. После ответа 204 вызовите POST /api/v1/files/public/anonymous/profiles/{publicId}/uploads/{uploadId}/complete с теми же Origin и Bearer sessionToken. Считайте файл готовым только после ответа status: ready.
6. Если запрос проверки оборвался, прочитайте безопасный статус через GET /api/v1/files/public/anonymous/profiles/{publicId}/uploads/{uploadId}/status с теми же Origin и Bearer token. Ответ содержит только processing, ready или rejected и публичные идентификаторы файла.

Grant действует от 2 до 5 минут и разрешает только один файл точного размера на запрос. Повтор create с тем же idempotencyKey и теми же параметрами безопасен; использование ключа с другими параметрами отклоняется. Не переиспользуйте уже отправленную форму.

Complete сверяет выданную загрузку, фактический размер и целостность байтов, определяет MIME-тип по содержимому и применяет правила бакета и profile, затем переносит файл в неизменяемое закрытое хранилище. Его можно безопасно повторить с теми же параметрами: после успеха API вернёт тот же результат. Если файл изменился во время проверки, complete отклонит загрузку; создайте новую session и не пытайтесь продолжить со старой. ready на этом шаге подтверждает фактический формат, правила содержимого, целостность, malware/archive проверку и неизменяемое закрепление файла.

1. Сначала создайте заказ или другой business object в backend приложения.
2. На server-side вызовите agnostic.storage.bucket('order-files').anonymousUploads.claim(...) с capability files.write.
3. Передайте полученный один раз claimToken как token, ссылку на созданный заказ как externalRef и стабильный idempotencyKey. Для повторной попытки после сбоя используйте те же три значения.
4. Сохраните только возвращённые Files handles. Не принимайте отдельные fileId из browser и не смешивайте их со списком из claim response.

Exact retry возвращает тот же результат. Попытка повторно привязать session к другому заказу или использовать тот же idempotency key для другой session отклоняется. Handle ready уже прошёл current complete-проверку; processing означает, что заказ привязан, но файл ещё обрабатывается. Claim token и Runtime token должны оставаться на backend: не помещайте их в URL, логи, аналитику или browser storage.

CSV загружайте с MIME-типом text/csv и кодировкой UTF-8. Бакет должен разрешать этот тип. Проверка формата отклоняет бинарные данные и запрещённые управляющие символы; дальнейший импорт отдельно проверяет весь CSV, его структуру и значения. Для импорта через Agent выберите доступ team, дождитесь готовности файла и укажите его название и окружение в запросе.

1. Создайте upload session операцией POST .../buckets/{bucketId}/uploads, передав имя файла, MIME-тип, точный размер, SHA-256, режим доступа и уникальный idempotencyKey.
2. Получите uploadUrl, uploadUrlExpiresAt и requiredHeaders. Отправьте один PUT с исходными байтами и всеми выданными заголовками без изменений. Размер HTTP-клиент выставит по телу автоматически; вручную добавлять Content-Length не нужно. Не добавляйте токен Platform Auth к этой ссылке.
3. Вызовите POST .../uploads/{uploadId}/complete в том же проекте, бакете и окружении. Complete можно безопасно повторить: он вернёт сохранённый результат.

Ссылка на загрузку обычно действует 10 минут, а session — 15 минут. Не публикуйте ссылку и обязательные заголовки, не сохраняйте их в логах и не пытайтесь использовать повторно. Перезапись уже загруженных байтов отклоняется.

Бакет сразу появляется в выбранном окружении. Один и тот же адрес можно использовать в другом окружении того же проекта, и это будут разные изолированные бакеты.

Для обычной PUT-загрузки complete возвращает metadata с фактическим размером и SHA-256 только после malware/archive проверки и immutable promotion. Для anonymous POST complete возвращает минимальный ready-result; загрузку можно привязывать к заказу. После проверки access policy можно получить короткую ссылку на скачивание.

Раздел может включаться поэтапно для выбранных организаций. Если «Файлы» ещё не доступны в проекте, не пытайтесь обходить ограничение прямым доступом к облачному хранилищу: обратитесь к владельцу workspace и дождитесь включения возможности. Доставка пока учитывается только для проверки качества измерений и не создаёт списаний.

Режим доступа выбирается при загрузке и открывается только через подходящую identity boundary:

• private — backend с Runtime token и capability files.read; файл должен

принадлежать тому же Runtime subject после claim;

• authenticated — активная App User session того же realm, проекта и

окружения;

• team — участник того же проекта через Platform Auth;
• public — проверка одного конкретного fileId без авторизации.

Операция access возвращает безопасную metadata и подтверждение решения, а операция download — ссылку на конкретную версию сроком 1–5 минут. Для public можно сохранить стабильный адрес GET /api/v1/files/public/objects/{fileId}: он повторно проверяет статус и перенаправляет на новую короткую ссылку. Публичного списка файлов нет. Файл не откроется, пока он не завершил проверку, после истечения срока хранения или после удаления; несовпадение проекта, окружения, владельца или режима также закрывается отказом. После удаления новые ссылки не выпускаются, а ранее выданные прекращают работать не позднее пяти минут. HTML, SVG и JavaScript скачиваются как вложение.

Для команды список и карточка объектов доступны в Platform API внутри project + environment + bucket. Администратор может отдельно выполнить break-glass для одного объекта; это действие всегда аудируется и не превращает его в обычный публичный доступ.

Если после загрузки через интерфейс нужно сверить файл с исходным снимком, откройте список объектов бакета через Platform API и карточку нужного объекта. Карточка содержит file ID, фактический размер, SHA-256 и выбранный режим доступа. Сверьте все четыре значения, прежде чем связывать файл с записью приложения. Приватный файл, загруженный участником команды через интерфейс, не принадлежит Runtime identity API-сервиса и не станет доступен ему только от добавления file ID в запись приложения. Такой пробный объект оставьте без связи и удалите после успешной загрузки через Runtime.

Удаление готового объекта через Platform API сразу скрывает его из list, detail и access и закрывает интервал хранения. Физические байты удаляются повторяемым cleanup не позднее чем через 24 часа; временная ошибка хранилища не возвращает логически удалённый файл в доступ.

Готовый обычный файл учитывается по ставке 8 ₽ за GiB·месяц пропорционально точному размеру и времени хранения. Для anonymous upload отсчёт начинается только после claim; проверенный, но ещё не привязанный к заказу файл не тарифицируется. Logical delete прекращает учёт сразу, даже если физическая очистка завершится позднее.

Доставка файлов пока измеряется в теневом режиме. Цена 4 ₽ за GiB показана как будущая ставка, но реальные списания за delivery выключены до отдельного подтверждения полноты журналов доставки и финансового gate.

Адрес и окружение бакета после создания не меняются. Если они выбраны неправильно, удалите пустой бакет и создайте новый. Удалённый пустой бакет скрывается сразу, после чего его адрес можно использовать снова.

• Как принять файлы с публичного лендинга
• Настройки проекта
• Безопасные границы Runtime SDK