Скачивание и заливка каталога архивом

Обзор

Методы DOWNLOADZIP и UPLOADZIP позволяют работать с каталогом целиком: скачать его одним архивом и залить структуру файлов из архива. Это избавляет от необходимости выполнять по запросу на каждый файл.

Методы доступны в разделах со структурой tree — там, где есть вложенные каталоги. Структура раздела приходит в поле structure описания разделов.

Те же методы применяются к вложениям сценариев, см. Вложения сценариев IVR.

Запросы

HTTP verb Endpoint Описание

DOWNLOADZIP

/rest/v1/fs/targets/<target>/<path>

Скачивание каталога архивом

UPLOADZIP

/rest/v1/fs/targets/<target>/<path>

Заливка каталога архивом

Скачивание каталога архивом

Упаковывает каталог со всем содержимым и отдаёт архив.

Особенности

  • Применимо и к корню раздела, и к любому его подкаталогу.

  • Имя архива формируется из имени раздела и пути каталога: cacerts.zip, files-certificates-2026.zip.

  • Объём каталога проверяется до упаковки. Отказ 409 наступает, когда в каталоге 10 000 файлов и больше либо объём достигает 2 000 000 000 байт: предел здесь — первый отклоняемый размер. Временный архив при отказе не создаётся.

  • Имена файлов в кодировке UTF-8 сохраняются.

  • Символические ссылки, ведущие за пределы упаковываемого каталога, в архив не попадают. Внутренние ссылки сохраняются как ссылки.

Запрос

Пример запроса
DOWNLOADZIP /rest/v1/fs/targets/files/certificates HTTP/1.1

Ответ

Пример ответа
HTTP/1.1 200 OK
Content-Type: application/zip
Content-Disposition: attachment; filename=files-certificates.zip

BINARY BODY OF 'files-certificates.zip'

Заливка каталога архивом

Распаковывает содержимое архива в указанный каталог.

Особенности

  • Предельный размер тела запроса — 2 000 000 000 байт. Запрос такого размера и больше отвергается с кодом 413: предел здесь — первый отклоняемый размер, а не последний допустимый. Запрос с телом, но без заголовка Content-Length, отвергается с кодом 411: объём нечем проверить до приёма.

  • Суммарный объём распакованных данных не должен превышать 2 000 000 000 байт. Он вычисляется по оглавлению архива, до записи на диск, поэтому слишком большой архив отвергается сразу, а не после частичной распаковки. В отличие от предела на тело запроса, здесь отказ наступает при превышении: ровно предельный объём допускается.

  • Отдельный файл внутри архива не должен превышать общий предел размера файла — 512 МБ. Запись сверх него отвергает архив целиком, с указанием её имени.

  • В разделах со структурой tree структура архива сохраняется: запись sub/report.pdf ложится в подкаталог sub, недостающие каталоги создаются.

  • В разделах со структурой flat подкаталогов не бывает, поэтому иерархия архива отбрасывается и все записи ложатся в один уровень. Так же ведёт себя заливка вложений сценариев.

  • Существующие файлы с совпадающими именами перезаписываются.

  • Содержимое каталога, не затронутое архивом, сохраняется.

  • Архив проверяется на безопасность до и после распаковки, см. Требования к содержимому архива. Небезопасный архив отвергается целиком, до целевого каталога не доходит ничего.

Запрос

Пример запроса
UPLOADZIP /rest/v1/fs/targets/files/certificates HTTP/1.1
Content-Type: application/zip

BINARY BODY OF ARCHIVE

Ответ

Пример ответа
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

[
  { "name" : "1789660649498", "status" : "ok" }
]

Ответ содержит по элементу на каждый принятый архив, а не на каждый файл внутри него: name — внутренний идентификатор архива, status — итог его распаковки. Состав распакованного узнаётся листингом каталога.

Пример ответа при отвергнутом архиве
HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json; charset=utf-8

{
  "error_code" : 1406,
  "error_message" : "Archive rejected: entries must stay inside the archive"
}

Требования к содержимому архива

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

Архив отвергается целиком и в том случае, если превышает пределы объёма: суммарный распакованный размер сверх 2 ГБ либо отдельная запись сверх max_file_size раздела. Оба случая определяются по оглавлению, до распаковки.

Недопустимы:

  • записи с сегментами .. в пути;

  • записи с абсолютными путями;

  • символические ссылки, цель которых находится за пределами архива;

  • записи, имя которых сервер не сможет адресовать: если любой сегмент пути записи оканчивается на !<метод>, где <метод> — метод, поддерживаемый разделом, такой файл или каталог оказался бы недостижим. См. Нестандартные методы в пути.

Внутренние символические ссылки допускаются и сохраняются при распаковке.

Правило действует во всех режимах распаковки и для всех потребителей архивов на платформе, включая вложения сценариев. Отдельного «нестрогого» режима нет.

Архивы, полученные через DOWNLOADZIP, этим правилам удовлетворяют по построению: каталог, скачанный архивом и залитый обратно, воспроизводится вместе со структурой подкаталогов.

Пределы упаковки и распаковки согласованы так, чтобы всё, что можно скачать архивом, можно было и залить обратно: упаковка отклоняет каталог объёмом 2 000 000 000 байт, а распаковка такой объём ещё принимает. Если бы соотношение было обратным, нашёлся бы каталог, который можно скачать и нельзя вернуть.

См. также

  • Персонализация
  • Увеличить шрифт
  • Уменьшить шрифт