Корень общей части каталога межсерверной синхронизации (syncroot/common)

Обзор

Предоставляет административный доступ к файлам и каталогам, размещаемым в общем разделе каталога межсерверной синхронизации :SYNC.

Различные разделы этого каталога (conf, cacerts, waitonhold, и т.д.) имеют отдельные API эндпойнты. А данный эндпойнт позволяет администратору мастер-домена оперировать произвольными путями внутри каталога, в том числе к системым файлам, размещенным в ходе установки.

Каталог располагается в категории автоматически синхронизирующихся каталогов :SYNC.

Доступ к каталогу из сценариев происходит с помощью префикса категории каталогов ":SYNC_COMMON/".

Доступно только в мастер-домене.

Запросы

HTTP verb Endpoint Описание

POST

/rest/v1/fs/targets/syncroot/common

Заливка группы файлов

GET

/rest/v1/fs/targets/syncroot/common

Получение списка файлов

GET

/rest/v1/fs/targets/syncroot/common/<filename>

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

PUT

/rest/v1/fs/targets/syncroot/common/<filename>

Перезаливка существующего файла

DELETE

/rest/v1/fs/targets/syncroot/common/<filename>

Удаление файла

HEAD

/rest/v1/fs/targets/syncroot/common/<filename>

Получение мета-информации о файле

METADATA

/rest/v1/fs/targets/syncroot/common/<filename>

Получение мета-информации о файле (METADATA)

PUT

/rest/v1/fs/targets/syncroot/common/<filename>

Перемещение и переименование файла

PUT

/rest/v1/fs/targets/syncroot/common/<path>/

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

DELETE

/rest/v1/fs/targets/syncroot/common/<path>/

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

CLEAR

/rest/v1/fs/targets/syncroot/common/<path>/

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

DOWNLOADZIP

/rest/v1/fs/targets/syncroot/common

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

UPLOADZIP

/rest/v1/fs/targets/syncroot/common

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

METADATA

/rest/v1/fs/targets/syncroot/common

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

CLEAR

/rest/v1/fs/targets/syncroot/common

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

Заливка группы файлов

Загрузка в коллекцию производится с помощью Content-Type: multipart/formdata.

В запросе может быть один или несколько файлов. Файлы размещаются под именами, указанными в заголовках Content-Disposition каждой части.

Если файл с указанным именем уже существует, то он не сохраняется и возвращает ошибку. В зависимости от Content-Type и наличия успешно размещенных файлов в запросе может быть возвращен неудачный HTTP-ответ, либо информация о неудаче в теле HTTP-ответа 200 OK.

Каталог, в который производится заливка, должен существовать: при обращении к несуществующему каталогу возвращается 405 Method Not Allowed. Чтобы разместить файл вместе с недостающими каталогами пути, используется метод PUT.

Запрос

Пример запроса
POST /rest/v1/fs/targets/syncroot/common HTTP/1.1
Content-Type: multipart/form-data; boundary=-----------boundary_69df8120352a996e

-----------boundary_69df8120352a996e
Content-Type: application/octet-stream
Content-Disposition: form-data; name="filename"; filename="somefile.txt"
Content-Transfer-Encoding: binary

BINARY BODY OF 'somefile.txt'
-----------boundary_69df8120352a996e--

Ответ

Пример ответа
[
  {
    "name": "somefile.txt",
    "size": 12345,
    "last_modified": "2026-07-20 10:39:10"
  }
]

Получение списка файлов

Запрос

Table 1. Параметры запроса
Имя Тип Описание

filter

object

Фильтр по значениям полей.

mask

str

Список полей для вывода. Доступные поля для выдачи: name, size, last_modified.

offset

int

Смещение в списке файлов, подлежащих выдаче.

limit

int

Максимальное количество файлов в списке.

order

array<object|str>

Порядок сортировки файлов в списке.

countonly

bool

При значении true возвращается только количество файлов.

Считается после применения фильтра: с параметром filter возвращается количество подходящих под фильтр файлов, а не общее количество файлов в каталоге.

Подробно про формат параметров GET-запроса

Пример запроса
GET /rest/v1/fs/targets/syncroot/common HTTP/1.1

Ответ

Время в поле last_modified возвращается в UTC.

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

[
  {
    "last_modified" : "2025-04-20 10:24:13",
    "name" : "autoprovision",
    "type" : "directory"
  },
  {
    "last_modified" : "2026-07-11 14:38:57",
    "name" : "cacerts",
    "type" : "directory"
  },
  {
    "last_modified" : "2026-01-22 22:38:49",
    "name" : "cert",
    "type" : "directory"
  },
  {
    "last_modified" : "2025-07-30 15:57:56",
    "name" : "cmd",
    "type" : "directory"
  },
  {
    "last_modified" : "2025-08-20 00:17:44",
    "name" : "conf",
    "type" : "directory"
  },
  {
    "last_modified" : "2025-06-20 17:54:04",
    "name" : "cpd",
    "type" : "directory"
  },
  {
    "last_modified" : "2026-06-29 15:05:44",
    "name" : "domain_custom_public_www",
    "type" : "directory"
  },
  {
    "last_modified" : "2025-03-20 20:36:03",
    "name" : "dtmftones",
    "type" : "directory"
  },
  {
    "last_modified" : "2025-01-19 16:07:43",
    "name" : "hotdesking",
    "type" : "directory"
  },
  {
    "last_modified" : "2025-01-19 16:00:11",
    "name" : "parking",
    "type" : "directory"
  },
  {
    "last_modified" : "2026-06-29 15:05:03",
    "name" : "patch",
    "type" : "directory"
  },
  {
    "last_modified" : "2026-07-01 15:53:06",
    "name" : "product",
    "type" : "directory"
  },
  {
    "last_modified" : "2025-07-16 21:10:26",
    "name" : "silence",
    "type" : "directory"
  },
  {
    "last_modified" : "2025-06-29 22:32:25",
    "name" : "snmp",
    "type" : "directory"
  },
  {
    "last_modified" : "2025-04-07 17:44:38",
    "name" : "standardexpressions",
    "type" : "directory"
  },
  {
    "last_modified" : "2026-06-26 20:59:35",
    "name" : "test",
    "type" : "directory"
  },
  {
    "last_modified" : "2025-08-30 17:12:05",
    "name" : "voicemail",
    "type" : "directory"
  },
  {
    "last_modified" : "2025-07-13 14:54:20",
    "name" : "waitonhold",
    "type" : "directory"
  },
  {
    "last_modified" : "2025-11-22 14:54:59",
    "name" : "waitonqueue",
    "type" : "directory"
  },
  {
    "last_modified" : "2026-05-29 16:17:43",
    "name" : "wakeup",
    "type" : "directory"
  },
  {
    "last_modified" : "2025-04-06 17:59:46",
    "name" : "www",
    "type" : "directory"
  }
]

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

Запрос

Table 2. Параметры запроса
Имя Тип Описание

attachment

bool

Тип выдачи. По умолчанию false.

true – выдаётся с заголовком Content-Disposition: attachment; filename=filename.ext либо Content-Disposition: attachment; filename*=UTF-8''%d1%84%d0%b0%d0%b9%d0%bb.ext, где файл.ext – имя файла в кодировке UTF-8 и URLencoded.

false – выдается без заголовка Content-Disposition.
Пример запроса
GET /rest/v1/fs/targets/syncroot/common/somefile.txt?attachment=true HTTP/1.1

Ответ

Пример ответа
HTTP/1.1 200 OK
Content-Type: application/octet-stream; charset=utf-8
Content-Disposition: attachment; filename*=UTF-8''somefile.txt

BINARY BODY OF 'somefile.txt'

Перезаливка существующего файла

Производит замену файла.

Загрузка одного файла производится либо с помощью Content-Type: multipart/formdata, либо с произвольным Content-Type не являющимся мультипартом.

Если загрузка происходит с Content-Type: multipart/formdata, то будет сохранён только первый файл (первая часть имеющая поле filename в заголовке Content-Disposition), а само название файла будет проигнорировано.

Имя файла всегда берётся из URL.

Если файла по указанному пути нет, он создаётся вместе с недостающими каталогами пути.

Запрос с Content-Type: application/octet-stream и нулевой длиной тела создаёт пустой файл. Запрос без тела, без Content-Type и без заголовка X-Era-Source отвергается с кодом 400: по такому запросу невозможно определить намерение.

Метод PUT имеет ещё одно значение, отличающееся формой запроса: Перемещение и переименование файла.

В разделах с вложенной структурой PUT по пути с завершающим слешем создаёт каталог, см. Операции над каталогами.

Запрос

Пример запроса (octet-stream)
PUT /rest/v1/fs/targets/syncroot/common/somefile.txt HTTP/1.1
Content-Type: application/octet-stream

BINARY BODY OF 'somefile.txt'
Пример запроса (multipart)
PUT /rest/v1/fs/targets/syncroot/common/somefile.txt HTTP/1.1
Content-Type: multipart/form-data; boundary=-----------boundary_69df8120352a996e

-----------boundary_69df8120352a996e
Content-Type: application/octet-stream
Content-Disposition: form-data; name="somefile.txt"; filename="somefile.txt"
Content-Transfer-Encoding: binary

BINARY BODY OF 'somefile.txt'
-----------boundary_69df8120352a996e--

Ответ

Пример ответа
HTTP/1.1 204 No Content

Удаление файла

Запрос

Пример запроса
DELETE /rest/v1/fs/targets/syncroot/common/somefile.txt HTTP/1.1

Ответ

Пример ответа
HTTP/1.1 204 No Content

Получение мета-информации о файле

Возвращает мета-информацию о файле, содержащую в том числе размер в заголовке Content-Length.

Особенности

  • HTTP-ответ не содержит тела, несмотря на наличие заголовка Content-Length.

Запрос

Table 3. Параметры запроса
Имя Тип Описание

attachment

bool

Тип выдачи. По умолчанию false.

true – выдаётся с заголовком Content-Disposition: attachment; filename=filename.ext либо Content-Disposition: attachment; filename*=UTF-8''%d1%84%d0%b0%d0%b9%d0%bb.ext, где файл.ext – имя файла в кодировке UTF-8 и URLencoded.

false – выдается без заголовка Content-Disposition.
Пример запроса
HEAD /rest/v1/fs/targets/syncroot/common/somefile.txt?attachment=true HTTP/1.1

Ответ

Пример успешного ответа
HTTP/1.1 200 OK
Content-Type: application/octet-stream
Last-Modified: Mon, 20 Jul 2026 10:39:10 GMT
Content-Disposition: attachment; filename=somefile.txt
Content-Length: 12345
Пример неуспешного ответа
HTTP/1.1 404 Not Found

Получение мета-информации о файле (METADATA)

Возвращает размер и время изменения файла в формате JSON. В отличие от метода HEAD, сведения приходят в теле ответа и не требуют разбора заголовков.

Метод нестандартный и принимается в двух равнозначных формах: собственно методом (METADATA /rest/v1/fs/targets/syncroot/common/somefile.txt) и методом POST по пути с суффиксом (POST /rest/v1/fs/targets/syncroot/common/somefile.txt!metadata). Подробно — Нестандартные методы в пути.

Запрос не должен содержать тела ни в одной из форм: запрос с телом трактуется как заливка файла.

Особенности

  • Время в поле mtime возвращается в UTC в формате RFC 3339.

  • Контрольная сумма содержимого возвращается только по запросу с параметром hasha=true. Без параметра содержимое файла не читается, поэтому запрос дёшев независимо от размера файла.

Запрос

Table 4. Параметры запроса
Имя Тип Описание

hasha

bool

Добавить в ответ контрольную сумму содержимого. По умолчанию false.

Вычисление требует чтения файла целиком, поэтому на больших файлах параметр следует указывать только по явной необходимости.
Пример запроса
POST /rest/v1/fs/targets/syncroot/common/somefile.txt!metadata HTTP/1.1

Ответ

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

{
  "size" : 3836,
  "mtime" : "2026-07-01T16:47:31Z"
}
Пример ответа с параметром hasha=true
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "size" : 3836,
  "mtime" : "2026-07-01T16:47:31Z",
  "hasha" : "md5;9f86d081884c7d659a2feaa0c55ad015"
}

Подробно: Мета-информация о файлах, каталогах и разделах.

Перемещение и переименование файла

Перемещает или переименовывает файл в пределах раздела, не передавая его содержимое.

Выполняется методом PUT по пути назначения с заголовком X-Era-Source и пустым телом. В заголовке указывается путь источника относительно корня раздела.

Запрос

Table 5. Параметры запроса
Имя Тип Описание

overwrite

bool

Разрешить перезапись занятого пути назначения. По умолчанию false.
Пример запроса
PUT /rest/v1/fs/targets/syncroot/common/<filename> HTTP/1.1
X-Era-Source: inbox/somefile.txt
Content-Length: 0

Ответ

Пример ответа
HTTP/1.1 204 No Content

Подробно: Перемещение и переименование файла.

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

Раздел поддерживает вложенные каталоги произвольной глубины, поэтому в нём доступны операции над каталогами.

Запрос Действие

PUT <path>/

Создать каталог. Путь указывается с завершающим слешем, тело запроса отсутствует.

DELETE <path>

Удалить пустой каталог.

DELETE <path>?recursive=true

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

CLEAR <path>

Очистить каталог, оставив его самого. Требует подтверждения ключом.

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

Корень раздела удалить нельзя (405), очистить — можно.

Подробно, вместе с описанием ключа подтверждения и ограничений: Операции над каталогами.

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

Запрос Действие

DOWNLOADZIP <path>

Скачать каталог одним архивом.

UPLOADZIP <path>

Залить в каталог структуру файлов из архива.

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

Подробно: Скачивание и заливка каталога архивом.

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

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

Запрос Действие

METADATA /rest/v1/fs/targets/syncroot/common

Описание раздела и сведения о его корне: поддерживаемые операции, ограничения, число элементов верхнего уровня.

CLEAR /rest/v1/fs/targets/syncroot/common

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

Удалить раздел нельзя: DELETE по пути корня всегда возвращает 405.

Подробно: Мета-информация и Операции над каталогами.

См. также

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