# Загрузка и скачивание

Используйте веб-интерфейс для быстрой передачи одного файла, REST через шлюз — для небольших программных передач, а presigned URL — для крупных объектов или передачи байтов в обход шлюза.

## Перед началом[​](#before-you-begin "Прямая ссылка на Перед началом")

Хранилище аккаунта должно быть включено. Также нужен один из вариантов:

* аутентифицированная сессия веб-интерфейса;
* bearer-токен с доступом к активному аккаунту;
* `JR_STORAGE_URL` и `JR_STORAGE_TOKEN` внутри песочницы с доступом `ro` или `rw`.

Для загрузки нужен доступ на запись. Для скачивания достаточно доступа только на чтение.

Перед передачей выберите ключ:

```
FILE="./result.bin"
KEY="artifacts/2026-07-27/result.bin"
DOWNLOADED_FILE="./downloaded-result.bin"
```

Ключи задаются относительно пространства аккаунта. `/` создает видимую иерархию папок, но объект остается значением «ключ → байты». При самостоятельной сборке пути REST URL-кодируйте необычные символы ключа.

## Выбор способа передачи[​](#choose-a-transfer-path "Прямая ссылка на Выбор способа передачи")

| Способ                     | Для чего подходит                                   | Путь данных                                         |
| -------------------------- | --------------------------------------------------- | --------------------------------------------------- |
| Загрузка в веб-интерфейсе  | Один локальный файл в пределах ограничения браузера | Браузер → шлюз → объектное хранилище                |
| `PUT` или `GET` через шлюз | Небольшие файлы и простые API-клиенты               | Клиент → шлюз → объектное хранилище                 |
| Presigned `PUT` или `GET`  | Крупные файлы и прямая передача                     | Клиент → объектное хранилище                        |
| `jr-storage put/get`       | Передача из песочницы с выданным доступом           | Песочница → объектное хранилище через presigned URL |

Размер передачи через шлюз, срок presigned URL и максимальный размер одного объекта настраиваются в инсталляции. Не фиксируйте в коде значение по умолчанию, увиденное в одной инсталляции.

## Передача файла через веб-интерфейс[​](#transfer-through-the-web-ui "Прямая ссылка на Передача файла через веб-интерфейс")

1. Откройте *Хранилище* в активном аккаунте.
2. Перейдите в нужный префикс по цепочке папок, которая начинается с *Все файлы*.
3. Нажмите *Загрузить* и выберите один файл.
4. Дождитесь уведомления об успехе и проверьте имя и размер объекта.
5. Используйте действие *Скачать* у объекта, чтобы сохранить его локально.

Текущая загрузка из браузера принимает по одному файлу и до отправки отказывается от файлов больше 128 МиБ. Инсталляция может настроить меньший предел на сервере, тогда запрос вернет `413`. Скачивание в интерфейсе использует presigned GET URL и не ограничено пределом передачи через шлюз.

Для крупных загрузок из браузера через presigned URL нужна CORS-настройка объектного хранилища, и текущий интерфейс не предоставляет такую операцию. Используйте API, командную строку или вспомогательную утилиту внутри песочницы.

## Загрузка объекта через REST API в теле запроса[​](#upload-inline-through-the-rest-api "Прямая ссылка на Загрузка объекта через REST API в теле запроса")

Отправьте файл как сырое тело запроса, а не JSON или multipart-форму:

```
UPLOAD_RESPONSE="$(
  curl --fail-with-body --silent --show-error \
    --request PUT \
    "$JUSTRUN_API/v1/storage/objects/$KEY" \
    --header "Authorization: Bearer $JUSTRUN_PAT" \
    --header "Content-Type: application/octet-stream" \
    --data-binary @"$FILE"
)"

jq '{key, size, etag}' <<<"$UPLOAD_RESPONSE"
```

Успешная загрузка возвращает HTTP `201` с ключом относительно аккаунта, сохраненным размером и необязательным ETag. Загрузка по тому же ключу перезаписывает существующий объект. Контроль квоты при загрузке в теле запроса учитывает разницу размеров, поэтому замена объекта меньшим освобождает место.

Проверьте объект без скачивания:

```
curl --fail --silent --show-error \
  --head "$JUSTRUN_API/v1/storage/objects/$KEY" \
  --header "Authorization: Bearer $JUSTRUN_PAT"
```

Ответ содержит `Content-Length` и, когда доступны, `ETag` и `Last-Modified`.

При неопределенном ответе объектного хранилища на `PUT` или `DELETE` через шлюз сервер повторяет ту же операцию еще до двух раз. Успешный повтор учитывает потребление один раз. Если исход остался неопределенным, сохраните локальный файл и обратитесь к оператору для сверки ключа перед новой попыткой. Отключение клиента не отменяет уже отправленную запись; штатное завершение сервера ждет ее окончания.

## Скачивание объекта через REST API в теле ответа[​](#download-inline-through-the-rest-api "Прямая ссылка на Скачивание объекта через REST API в теле ответа")

```
curl --fail-with-body --silent --show-error \
  "$JUSTRUN_API/v1/storage/objects/$KEY" \
  --header "Authorization: Bearer $JUSTRUN_PAT" \
  --output "$DOWNLOADED_FILE"

cmp "$FILE" "$DOWNLOADED_FILE"
```

Скачивание в теле ответа передает байты через шлюз. Если сохраненный объект превышает предел передачи через шлюз в инсталляции, шлюз возвращает `413` и направляет клиент к пути через presigned URL.

## Загрузка объекта через presigned URL[​](#upload-with-a-presigned-url "Прямая ссылка на Загрузка объекта через presigned URL")

Сначала укажите точное количество байтов и запросите у шлюза прямой PUT URL:

```
SIZE="$(wc -c <"$FILE" | tr -d ' ')"

PRESIGN_RESPONSE="$(
  jq -n \
    --arg key "$KEY" \
    --argjson content_length "$SIZE" \
    '{key:$key, method:"PUT", upload_protocol:"multipart_v1", content_length:$content_length}' |
  curl --fail-with-body --silent --show-error \
    --request POST "$JUSTRUN_API/v1/storage/presign" \
    --header "Authorization: Bearer $JUSTRUN_PAT" \
    --header "Content-Type: application/json" \
    --data @-
)"

PUT_URL="$(jq -er '.url' <<<"$PRESIGN_RESPONSE")"
UPLOAD_ID="$(jq -er '.upload_id' <<<"$PRESIGN_RESPONSE")"
jq '{expires_at, complete_before}' <<<"$PRESIGN_RESPONSE"
```

Затем загрузите неопубликованную часть напрямую. Не передавайте bearer-токен Just Run на адрес presigned URL:

```
curl --fail-with-body --silent --show-error \
  --request PUT \
  --upload-file "$FILE" \
  "$PUT_URL"
```

Начните передачу части до `expires_at`. Запросите завершение на сервере до `complete_before` — на 300 секунд позже. Этот запас сохраняет сессию и резерв квоты, не продлевая срок жизни ссылки. Передача может продолжаться после истечения срока URL, но должна закончиться вовремя для запроса завершения.

После успешного PUT опубликуйте объект через шлюз. Для этого требуется действующее право записи; одна загрузка части еще не означает успех:

```
curl --fail-with-body --silent --show-error \
  --request POST "$JUSTRUN_API/v1/storage/uploads/$UPLOAD_ID/complete" \
  --header "Authorization: Bearer $JUSTRUN_PAT"
```

`content_length` входит в подпись. Если передано другое количество байтов, объектное хранилище отклоняет запрос, обычно с `403`. Не сжимайте и не преобразуйте тело между запросом presigned URL и загрузкой.

Запрос presigned URL резервирует только положительный рост байтов и слот нового объекта. Ключом владеет одна незавершенная сессия или запись; конкуренты получают `409 storage.operation_in_progress`. Для повтора используйте исходную сессию. Завершение атомарно заменяет резерв учтенным потреблением. Повтор завершенной сессии возвращает исходный результат без повторной публикации. Истекшая сессия, не начавшая завершение, больше не может публиковать и освобождает резерв. Если завершение вернуло 503 из-за неопределенного результата, сохраните идентификатор загрузки и локальный файл и обратитесь к оператору для сверки; одного истечения срока недостаточно.

Определенный отказ S3 при попытке публикации возвращает 422, а отсутствие загрузки — 409. Сервер выполняет прерывание загрузки и проверяет видимые на этот момент части перед освобождением резерва. При неудачной очистке ответ 503 сохраняет резерв для повтора. После успешной очистки можно создать новую сессию. Ошибки проверки до публикации оставляют сессию незавершенной до ее крайнего срока. Неопределенное завершение возвращает 503 и сохраняет резерв до сверки.

Чтобы отменить неиспользуемую незавершенную загрузку, вызовите `DELETE /v1/storage/uploads/$UPLOAD_ID` с правом записи. Ответ `204` подтверждает прерывание загрузки в S3 и пустой `ListParts` либо `NoSuchUpload`, после чего освобождаются резерв и ключ. Публикация и новые передачи частей запрещены, но это не доказывает физическое удаление части, уже находившейся в передаче. Фоновая очистка повторяет прерывание после исходного окна загрузки; правило жизненного цикла бакета остается последним механизмом очистки оставшихся частей. При неудачном прерывании ответ `503` сохраняет резерв даже после истечения срока. Повторите DELETE; фоновая очистка тоже повторяет прерывание. Опубликованная сессия отвечает `409`, а неопределенная публикация — `503` и сохраняет резерв.

## Скачивание объекта через presigned URL[​](#download-with-a-presigned-url "Прямая ссылка на Скачивание объекта через presigned URL")

Запросите прямой GET URL:

```
PRESIGN_RESPONSE="$(
  jq -n \
    --arg key "$KEY" \
    '{key:$key, method:"GET"}' |
  curl --fail-with-body --silent --show-error \
    --request POST "$JUSTRUN_API/v1/storage/presign" \
    --header "Authorization: Bearer $JUSTRUN_PAT" \
    --header "Content-Type: application/json" \
    --data @-
)"

GET_URL="$(jq -er '.url' <<<"$PRESIGN_RESPONSE")"
jq '{expires_at}' <<<"$PRESIGN_RESPONSE"

curl --fail-with-body --silent --show-error \
  "$GET_URL" \
  --output "$DOWNLOADED_FILE"

cmp "$FILE" "$DOWNLOADED_FILE"
```

Шлюз также может подписать необязательное значение `content_disposition`, переданное клиентом, если браузер должен скачать файл с выбранным именем. Сформируйте значение, безопасное для заголовка, без управляющих символов. Сам URL дает временный bearer-доступ: любой получивший его сможет использовать URL до `expires_at`.

## Проверка результата и очистка[​](#verify-and-clean-up "Прямая ссылка на Проверка результата и очистка")

Сравните криптографическую контрольную сумму, если источник и место назначения находятся на разных машинах:

```
sha256sum "$FILE" "$DOWNLOADED_FILE"
```

После проверки удалите временный объект и локально скачанный файл:

```
STATUS="$(
  curl --silent --show-error \
    --output /dev/null \
    --write-out '%{http_code}' \
    --request DELETE "$JUSTRUN_API/v1/storage/objects/$KEY" \
    --header "Authorization: Bearer $JUSTRUN_PAT"
)"

test "$STATUS" = "204"
rm -f "$DOWNLOADED_FILE"
```

Запрос DELETE к хранилищу идемпотентен: удаление отсутствующего ключа тоже возвращает `204`.

## Диагностика[​](#troubleshooting "Прямая ссылка на Диагностика")

| Статус или симптом                                                    | Причина и действие                                                                                                                                                     |
| --------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `400` от `/presign`                                                   | Проверьте `key`, `GET` или `PUT` заглавными буквами и обязательный числовой `content_length` для PUT; добавьте `upload_protocol: "multipart_v1"` (без протокола — 422) |
| `401` от шлюза                                                        | Обновите токен пользователя или замените ротированный или отозванный токен песочницы                                                                                   |
| `403` от шлюза                                                        | Песочница в режиме `ro` попыталась выполнить запись                                                                                                                    |
| `403` от адреса presigned URL                                         | URL истек, подписанный размер изменился или URL был модифицирован; запросите новый и повторите точные байты                                                            |
| `404` от `GET` объекта                                                | Ключ отсутствует в активном аккаунте; `404` для любого `/v1/storage` также может означать отключенное хранилище                                                        |
| `413` при передаче через шлюз                                         | Перейдите на передачу по presigned URL                                                                                                                                 |
| `413` от `/presign`                                                   | Заявленный объект превышает максимум инсталляции; протокол принимает ровно одну часть                                                                                  |
| `429`                                                                 | Запись превысит квоту хранилища с учетом `pending_bytes`; проверьте `/v1/storage/usage`                                                                                |
| `503`                                                                 | Сохраните локальный источник и идентификатор загрузки; неопределенное завершение требует сверки оператором                                                             |
| Presigned PUT из браузера не работает, а из командной строки работает | Политика CORS объектного хранилища не разрешает адрес браузера; используйте клиент вне браузера или обратитесь к оператору                                             |

## Для рабочей среды[​](#production-considerations "Прямая ссылка на Для рабочей среды")

* Никогда не логируйте и не передавайте bearer-токен или presigned URL.
* Добавляйте заголовок `Authorization` только к запросам к шлюзу. Presigned URL уже содержит собственную авторизацию.
* Используйте стабильные версионированные ключи и проверяйте контрольную сумму до удаления источника.
* Повтор `PUT` по тому же ключу перезаписывает этот ключ. Убедитесь, что каждый повтор использует нужные байты.
* Публичный API использует `PUT` одного объекта, а не возобновляемую многочастную загрузку. Разбивайте или сохраняйте во внешней промежуточной области объекты больше максимума инсталляции.
* Изоляция аккаунтов определяется аутентифицированным аккаунтом. Перед передачей чувствительных данных проверьте активный аккаунт.

## Связанные разделы[​](#related "Прямая ссылка на Связанные разделы")

* [Доступ к хранилищу из песочницы](/storage/access-from-sandboxes.md)
* [Объекты и ключи](/storage/objects-and-keys.md)
* [Квоты и потребление](/storage/quotas-and-usage.md)
* [Безопасность и жизненный цикл данных](/storage/security-and-data-lifecycle.md)
* [Постоянные данные и хранилище](/sandboxes/persistence-and-storage.md)
* [Справочник REST API](/api-reference/rest.md)
