Multipart Upload: загрузка больших файлов

Multipart Upload позволяет загрузить один S3-объект отдельными частями, а затем собрать их в единый объект. Рекомендуем использовать multipart-загрузку для объектов от 100 МБ, в PC-Storage она применяется автоматически для объектов от 500 МБ.

 

1. Как работает Multipart Upload

Составная загрузка состоит из трех основных этапов: инициализации, передачи частей и завершения. При инициализации PC-Storage возвращает UploadId (параметр —upload-id) – идентификатор, который используется во всех последующих запросах этой загрузки.

ЭтапМетодРезультат
1. Инициализацияcreate-multipart-uploadПолучить UploadId и задать ключ будущего объекта.
2. Передача частейupload-partЗагрузить части с номерами PartNumber и сохранить ETag каждой части.
3. Проверкаlist-partsПри необходимости получить список уже переданных частей.
4. Завершениеcomplete-multipart-uploadПередать список PartNumber + ETag и собрать единый объект.
Отменаabort-multipart-uploadУдалить незавершенную загрузку и уже переданные части.

ETag нужно сохранить: для каждой успешно загруженной части S3 возвращает ETag. Номер части и соответствующий ему ETag нужны при завершении multipart-загрузки.

Важные особенности

  • Метаданные объекта передаются на этапе инициализации multipart-загрузки.
  • Каждая часть имеет порядковый номер. Если повторно отправить часть с тем же номером, PC-Storage сохранит последнюю загруженную часть.
  • Пока загрузка не завершена, части существуют отдельно, занимают место и не доступны как готовый S3-объект.
  • Незавершенные multipart-загрузки учитываются при расчете занятого объема.
  • После завершения или отмены UploadId больше нельзя использовать.
  • Одновременно можно выполнять несколько multipart-загрузок с разными UploadId.

 

2. Multipart Upload через S3 API

Ниже запросы к S3 API PlatformCraft выполняются через AWS CLI. AWS CLI должен быть заранее настроен с вашими S3 Access Key и S3 Secret Key.

Что заменить в примерах:

  • example-bucket – имя вашего бакета;
  • archive/large-file.bin – ключ будущего объекта;
  • UPLOAD_ID – идентификатор из ответа create-multipart-upload;
  • пути вида /path/to/… – реальные пути к файлам на вашем компьютере;
  • endpoint https://eu-s3.platformcraft.com – оставляйте без изменений.

Шаг 1. Инициализировать загрузку

Создайте multipart-загрузку для нужного бакета и ключа объекта. В ответе сохраните значение UploadId.

aws s3api create-multipart-upload --bucket example-bucket --key archive/large-file.bin --endpoint-url=https://eu-s3.platformcraft.com

Пример ответа:

{
  "Bucket": "example-bucket",
  "Key": "archive/large-file.bin",
  "UploadId": "UPLOAD_ID"
}

 

Шаг 2. Загрузить части

Файл передается отдельными частями. Конкретный способ предварительного разделения локального файла на части в исходной документации не задан; клиент должен подготовить файлы-части самостоятельно.

aws s3api upload-part --bucket example-bucket --key archive/large-file.bin --part-number 1 --upload-id UPLOAD_ID --body /path/to/part-001.bin --endpoint-url=https://eu-s3.platformcraft.com

Успешный ответ содержит ETag части:

{
  "ETag": "\"ETAG_PART_1\""
}

Для следующей части повторите запрос с другим значением —part-number и другим локальным файлом. Сохраняйте ETag каждой части.

Шаг 3. Получить список загруженных частей

Если нужно проверить, какие части уже приняты хранилищем, используйте list-parts.

aws s3api list-parts --bucket example-bucket --key archive/large-file.bin --upload-id UPLOAD_ID --endpoint-url=https://eu-s3.platformcraft.com

В ответе для каждой части возвращаются, в частности, PartNumber, ETag, размер и время последнего изменения.

Шаг 4. Завершить загрузку

Создайте JSON-файл со списком успешно загруженных частей. Для каждой части укажите ее номер и ETag.

{
  "Parts": [
    {"ETag": "ETAG_PART_1", "PartNumber": 1},
    {"ETag": "ETAG_PART_2", "PartNumber": 2}
  ]
}

Например, сохраните этот файл как parts.json, затем передайте его в complete-multipart-upload:

aws s3api complete-multipart-upload --bucket example-bucket --key archive/large-file.bin --multipart-upload file:///path/to/parts.json --upload-id UPLOAD_ID --endpoint-url=https://eu-s3.platformcraft.com

После успешного завершения PC-Storage собирает части в единый объект. Дальнейшее использование этого UploadId невозможно.

 

3. Просмотр и отмена незавершенных загрузок

Чтобы получить список незавершенных multipart-загрузок в бакете, выполните:

aws s3api list-multipart-uploads --bucket example-bucket --endpoint-url=https://eu-s3.platformcraft.com

В ответе отображаются UploadId, ключ объекта, время инициализации и другие сведения. Если активных multipart-загрузок нет, список Uploads отсутствует.

Отменить multipart-загрузку

Если загрузку не нужно завершать, ее следует отменить. PC-Storage удалит саму multipart-загрузку и уже полученные части.

aws s3api abort-multipart-upload --bucket example-bucket --key archive/large-file.bin --upload-id UPLOAD_ID --endpoint-url=https://eu-s3.platformcraft.com

Освобождение места: незавершенные части занимают место в хранилище. Если загрузка больше не нужна, не оставляйте ее активной, а завершите или отмените ее.

 

4. Multipart Upload через веб-интерфейс

При загрузке объекта размером от 500 МБ веб-интерфейс PC-Storage использует multipart-загрузку автоматически. Файл можно выбрать на устройстве или перетащить в окно загрузки.

Окно загрузки объектов в PC-Storage
Окно загрузки объектов. Переключатель «S3 загрузка файлов» позволяет сохранить незавершенную multipart-загрузку для последующего возобновления.

Возобновление после ошибки

Для больших файлов рекомендуется включить переключатель «S3 загрузка файлов». Если передача прервется из-за сети или работы компьютера, уже успешно загруженные части сохранятся, а задачу можно будет продолжить позже.

  • Если переключатель включен, незавершенная загрузка появится в разделе «Просмотр задач».
  • Если переключатель выключен, при ошибке загруженные части и сама multipart-загрузка удаляются.
Возобновление после ошибки в PC-Storage
В «Просмотре задач» выберите тип «S3 мультипарт», чтобы перейти к multipart-загрузкам.

Просмотр состояния загрузки

Для выбранного бакета отображаются незавершенные multipart-загрузки с ключом объекта, UploadId и датой. Открыв загрузку, можно посмотреть ее статус, количество частей, общий размер и сведения о каждой части.

Карточка незавершенной multipart-загрузки
Карточка незавершенной multipart-загрузки.

Как возобновить загрузку

  1. Откройте «Просмотр задач» и выберите «S3 мультипарт».
  2. Выберите бакет и откройте незавершенную загрузку.
  3. Нажмите значок обновления в правом верхнем углу карточки загрузки.
  4. Выберите на локальном устройстве исходный файл.
  5. Система продолжит передачу с части, на которой загрузка была прервана.
  6. После успешного завершения задача исчезнет из списка незавершенных загрузок.

 

5. Параметры методов

Параметры методов следующие:

  • bucket – имя бакета.
  • key – ключ объекта. Во всех запросах одной multipart-загрузки должен использоваться тот же ключ.
  • upload-id – UploadId, полученный при инициализации загрузки.
  • part-number – порядковый номер передаваемой части.
  • body – локальный файл-часть, передаваемый через upload-part.
  • multipart-upload – JSON-файл со списком PartNumber и ETag для завершения загрузки.

Подпишитесь на наши новости,
чтобы быть в курсе всех событий

    Прокрутить вверх