Нестандартные методы в пути

Обзор

Кроме стандартных методов HTTP, разделы fs/targets поддерживают нестандартные: METADATA, CLEAR, DOWNLOADZIP, UPLOADZIP. Набор методов, доступных в разделе, приходит в поле methods описания разделов.

Нестандартный метод можно вызвать двумя равнозначными способами:

  • собственно методом — METADATA /path;

  • методом POST по пути с суффиксом !<метод> — POST /path!metadata.

Вторая форма пригодна там, где клиент или промежуточный узел не пропускает нестандартные методы. Она работает на любой глубине вложенности, для файлов и для каталогов.

Две формы вызова

Оба запроса ниже возвращают одинаковый ответ.

Вызов методом METADATA
METADATA /rest/v1/fs/targets/files/certificates/x.local.pem HTTP/1.1
Вызов методом POST с суффиксом
POST /rest/v1/fs/targets/files/certificates/x.local.pem!metadata HTTP/1.1
Ответ
HTTP/1.1 200 OK
Content-Type: application/json

{
  "size" : 3836,
  "mtime" : "2026-07-01T16:47:31Z"
}

Подробно о методе: Мета-информация (METADATA).

Как отделяется суффикс

Суффикс отделяется по последнему восклицательному знаку в последней части пути.

Часть после него считается методом, только если она совпадает с методом, возможным на этом маршруте. Всё остальное — часть имени файла или каталога.

Последняя часть пути Как трактуется

notes!draft.txt

Файл notes!draft.txt: draft.txt не является методом.

notes!draft.txt!metadata

Метод METADATA для файла notes!draft.txt.

tail!

Файл tail!: после восклицательного знака ничего нет.

report!metadata

Метод METADATA для файла report.

Имена файлов и каталогов с восклицательным знаком

Из правила отделения суффикса следует то, что нужно знать администратору.

  • Имена, содержащие !, допустимы. notes!draft.txt — обычный файл, скачивается и удаляется как любой другой.

  • Имя, заканчивающееся на !, безопасно. Например, tail!.

  • Имя, у которого часть после последнего ! совпадает с методом раздела, недопустимо — например, report!metadata или x!delete. Такой файл был бы недостижим по API: любое обращение к нему трактовалось бы как вызов метода для другого файла.

    • Если такое имя передаётся в теле запроса на заливку, запрос отвергается с кодом 409.

    • В адресе запроса такой суффикс трактуется как вызов метода, поэтому файл с таким именем не создаётся и методом PUT.

Пример отказа при заливке файла с недопустимым именем
HTTP/1.1 409 Conflict
Content-Type: application/json; charset=utf-8

{
  "error_message" : "Name 'report!metadata' is not allowed: the part after '!' ('METADATA') is a reserved verb on this section, so the file would be unreachable. Rename it without that '!<verb>' suffix.",
  "error_code" : 1406
}

Записи архива

При распаковке архива в раздел со структурой tree структура архива сохраняется: запись sub/report.pdf ложится в подкаталог sub. Поэтому правило применяется к каждому сегменту пути записи, а не только к имени файла.

  • Файл sub/report!metadata недопустим: последний сегмент оканчивается на !metadata.

  • Каталог sub!clear/ недопустим так же: сам каталог был бы недостижим, потому что обращение к sub!clear/ трактовалось бы как вызов метода CLEAR для каталога sub.

  • Запись notes!draft/report.pdf допустима: draft не является методом.

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

См. также

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