Операции над каталогами

Обзор

Разделы со структурой tree поддерживают вложенные каталоги произвольной глубины. Для них доступны создание каталога, удаление и очистка.

Структура раздела указана в его статье и приходит в поле structure описания разделов. В разделах со структурой flat операции над каталогами не поддерживаются.

Удаление и очистка непустого каталога выполняются двумя запросами. Первый запрос ничего не удаляет: он возвращает ключ подтверждения и объём предстоящей операции. Второй выполняет операцию с этим ключом. Смысл такого порядка описан в разделе Подтверждение операции ключом.

Запросы

HTTP verb Endpoint Описание

PUT

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

Создание каталога

DELETE

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

Удаление каталога

CLEAR

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

Очистка каталога

Создание каталога

Создаёт каталог по указанному пути вместе с недостающими промежуточными каталогами.

Особенности

  • Путь указывается с завершающим слешем: именно он отличает создание каталога от заливки файла.

  • Тело запроса отсутствует и игнорируется.

  • Отдельно создавать каталоги для заливки файлов не требуется: метод PUT по пути файла создаёт весь путь самостоятельно. Операция нужна там, где каталог должен существовать сам по себе — например, чтобы подготовить структуру заранее.

Запрос

Пример запроса
PUT /rest/v1/fs/targets/files/certificates/2026/ HTTP/1.1
Content-Length: 0

Ответ

Код Условие

201

Каталог создан.

204

Каталог уже существовал.

409

По указанному пути находится файл.

405

Раздел не поддерживает вложенные каталоги.

Удаление каталога

Особенности

  • Без параметра recursive удаляется только пустой каталог; непустой возвращает 409.

  • Корень раздела удалить нельзя: DELETE по пути коллекции всегда возвращает 405. Чтобы удалить содержимое раздела, используется Очистка каталога.

  • Завершающий слеш в пути допускается и означает утверждение «цель обязана быть каталогом»: если по пути окажется файл, возвращается 409, а не удаление. Без слеша тип цели определяется по файловой системе.

  • Опустевшие вышестоящие каталоги удаляются автоматически, как и при удалении файла.

Запрос

Удаление пустого каталога
DELETE /rest/v1/fs/targets/files/certificates/2026 HTTP/1.1
Удаление каталога с содержимым, первый запрос
DELETE /rest/v1/fs/targets/files/certificates?recursive=true HTTP/1.1
Удаление каталога с содержимым, второй запрос
DELETE /rest/v1/fs/targets/files/certificates?recursive=true&key=493769f214f028c0a415888026352bbf HTTP/1.1

Ответ

Код Условие

204

Каталог удалён.

409

Каталог не пуст, а параметр recursive не указан; либо ключ не подошёл; либо объём превышает границы.

428

Требуется подтверждение: в теле ключ и объём операции.

404

Каталога не существует.

405

Указан корень раздела.

Очистка каталога

Удаляет всё содержимое каталога, оставляя сам каталог существующим.

Особенности

  • Операция всегда рекурсивна и параметра recursive не принимает: вложенные каталоги удаляются вместе с файлами.

  • Применима и к корню раздела: содержимое раздела очищается, сам раздел остаётся.

  • Требует подтверждения ключом наравне с рекурсивным удалением.

Запрос

Первый запрос
CLEAR /rest/v1/fs/targets/files/certificates HTTP/1.1
Второй запрос
CLEAR /rest/v1/fs/targets/files/certificates?key=493769f214f028c0a415888026352bbf HTTP/1.1

Подтверждение операции ключом

Рекурсивное удаление и очистка необратимы и за один запрос способны уничтожить содержимое целого раздела. Поэтому они разделены на два зависимых шага.

Первый запрос

Возвращает 428 Precondition Required и ничего не удаляет:

HTTP/1.1 428 Precondition Required
Content-Type: application/json; charset=utf-8

{
  "error_code" : 1428,
  "error_message" : "Confirmation required",
  "confirmation_key" : "493769f214f028c0a415888026352bbf",
  "expires_in" : 97,
  "entries" : {
    "files" : 128,
    "directories" : 3,
    "bytes" : 41207332,
    "truncated" : false
  }
}

Поле entries описывает объём предстоящей операции — его следует показать пользователю до подтверждения. Поле expires_in содержит точное число секунд, оставшихся до истечения ключа, и пригодно для отображения таймера.

Второй запрос

Тот же запрос с параметром key. При совпадении ключа операция выполняется и возвращается 204 No Content.

Свойства ключа

  • Ключ вычисляется, а не хранится: сервер не держит выданные ключи в памяти и не накапливает их.

  • Ключ привязан к сессии, разделу, пути, методу и содержимому каталога. Ключ, выданный на удаление, не подойдёт для очистки, а ключ от одного каталога — для другого.

  • Срок действия — от 60 до 120 секунд, точное оставшееся время приходит в expires_in.

  • Если содержимое каталога изменилось между запросами, ключ перестаёт подходить. Это сделано намеренно: подтверждение, полученное на 128 файлов, не должно удалять выросшую за это время тысячу.

Обработка отказа на втором запросе

Второй запрос может вернуть 409 либо снова 428. Оба случая обрабатываются одинаково: следует повторить первый запрос, показать пользователю обновлённый объём и запросить подтверждение заново.

Повторный 428 не является ошибкой: он приходит, в частности, после активации новой конфигурации платформы, которая меняет основу вычисления ключей.

Ограничения объёма

Рекурсивные операции ограничены величинами, приходящими в limits.recursive_delete описания разделов: по умолчанию 10 000 файлов и 10 ГБ.

Пределы упаковки и распаковки архивов задаются отдельно и ниже — см. Скачивание и заливка каталога архивом. Каталог, который нельзя скачать архивом, по-прежнему можно удалить либо очистить: удаление содержимое не читает.

При превышении возвращается 409, и удаление не выполняется вовсе — частичного удаления не происходит. Признак "truncated": true в ответе первого запроса означает, что каталог заведомо превышает границу: такой каталог придётся удалять по частям.

Ограничение защищает и от продолжительной блокировки соединения: операция выполняется синхронно.

См. также

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