Процесс загрузки

Загрузка и скачивание данных через REST API выполняются по строгому протоколу для обеспечения целостности каждого байта.

Общая схема загрузки

Процесс передачи файла в облако разделен на три последовательных шага:

1. Шаг 1: клиент отправляет запрос на получение тикета загрузки POST /files/upload-ticket с метаданными и хэшем SHA-256.
2. Шаг 2: бинарное содержимое файла передается методом PUT по полученной ссылке загрузки. Для больших файлов передача выполняется по отдельным ссылкам для каждой части.
3. Шаг 3: клиент вызывает POST /files/complete для фиксации загрузки и ожидает статус ready через периодический опрос GET /files/{file_id}.

Шаг 1: Запрос тикета (POST /files/upload-ticket)

Запрос создает запись в хранилище и возвращает временные ссылки для передачи данных:

POST /files/upload-ticket HTTP/1.1
Host: api.mmwcloud.tech
Authorization: Bearer mmwc_<prefix>_<secret>
Content-Type: application/json

{
  "name": "backup-archive.tar.gz",
  "size_bytes": 15728640,
  "sha256": "4b68e210ac124b868e826b5278c5208fe3b0c44298fc1c149afbf4c8996fb924",
  "kind": "tar.gz"
}

Требуемое право: files:write.

Параметры тела запроса

• name (обязательно): имя файла, не содержащее управляющих символов (\r, \n, \0).
• size_bytes (обязательно): точный размер файла в байтах.
• sha256 (обязательно): контрольная сумма SHA-256 всего файла в шестнадцатеричном формате.
• kind (опционально): строковое обозначение расширения или типа файла (до 64 символов).
• is_media (опционально): логический признак медиафайла.
• taken_at (опционально): дата и время создания медиафайла (до 64 символов).
• agent_sync_enabled: через Developer API передавать запрещено (значение должно быть false или отсутствовать, иначе возвращается 400).

Ответ для небольшого файла (до 8 МиБ)

Сервер возвращает единую прямую ссылку upload_url:

{
  "id": "file_01h8upload123",
  "upload_url": "https://storage.mmwcloud.tech/v1/upload/file_01h8upload123?capability=token123"
}

Ответ для составного файла (от 8 МиБ)

Сервер возвращает массив частей parts с отдельными ссылками:

{
  "id": "file_01h8upload456",
  "parts": [
    {
      "part_number": 1,
      "upload_url": "https://storage.mmwcloud.tech/v1/upload-part/file_01h8upload456/1?capability=tokenPart1"
    },
    {
      "part_number": 2,
      "upload_url": "https://storage.mmwcloud.tech/v1/upload-part/file_01h8upload456/2?capability=tokenPart2"
    }
  ]
}

Шаг 2: Бинарная передача данных

• Для небольшого файла: отправьте бинарное содержимое методом PUT по полученной ссылке upload_url с заголовком Content-Type: application/octet-stream.
• Для составного файла: отправьте каждый фрагмент методом PUT по соответствующей ссылке upload_url из списка частей. В ответе на загрузку части сервер возвращает JSON с полем etag. Сохраните полученное значение etag для каждого номера части part_number.

Шаг 3: Завершение загрузки (POST /files/complete)

После передачи всех данных отправьте запрос на завершение:

POST /files/complete HTTP/1.1
Host: api.mmwcloud.tech
Authorization: Bearer mmwc_<prefix>_<secret>
Content-Type: application/json

{
  "id": "file_01h8upload456",
  "parts": [
    { "part_number": 1, "etag": "\"etag-part-1\"" },
    { "part_number": 2, "etag": "\"etag-part-2\"" }
  ]
}

Требуемое право: files:write.

Для небольшого файла массив parts можно опустить или передать пустым. Сервер возвращает HTTP 202 Accepted.

Ожидание готовности (Ready)

После подтверждения завершения сервер выполняет сборку и проверку целостности данных. Клиент периодически опрашивает статус файла через запрос GET /files/{file_id}. Когда поле status принимает значение ready, файл готов к скачиванию.

Скачивание файла

Скачивание выполняется в два шага:

1. Запрос ссылки на скачивание: выполните GET /files/{file_id}/download с правом files:read. Сервер вернет JSON с адресом download_url:

{
  "download_url": "https://storage.mmwcloud.tech/v1/download/file_01h8upload456?capability=tokenDownload"
}

2. Получение содержимого: выполните стандартный GET-запрос по полученному адресу download_url. Временная ссылка действует ограниченное время и сгорает автоматически.