Описание разделов (targets)

Содержание

Обзор
Запросы
- Получение описания разделов
Состав описания
См. также

Обзор

Возвращает машиночитаемое описание разделов fs/targets, доступных учётной записи в текущем домене: их устройство, набор поддерживаемых операций и ограничения.

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

Обратите внимание на различие двух адресов:

Эндпойнт Что возвращает

Эндпойнт	Что возвращает
`/rest/v1/fs/targets/`	Перечень имён разделов. Общий механизм листинга регионов, см. Назначения (targets).
`/rest/v1/fs/targets`	Описание разделов. Настоящая статья.

/rest/v1/fs/targets/

Перечень имён разделов. Общий механизм листинга регионов, см. Назначения (targets).

/rest/v1/fs/targets

Описание разделов. Настоящая статья.

Различие — в завершающем слеше.

Запросы

HTTP verb Endpoint Описание

HTTP verb	Endpoint	Описание
`GET`	`/rest/v1/fs/targets`	Получение описания разделов

GET

/rest/v1/fs/targets

Получение описания разделов

Особенности

Состав списка фильтруется теми же правилами, что и перечень имён: учитываются ролевая политика и тип домена.
Часть разделов в описание не попадает, оставаясь в перечне имён и сохраняя доступ по своим маршрутам: websocktemp — служебный, привязан к вебсокет-подключению сессии; alertcall — устаревший, сервис оповещений, использовавший его, более не применяется.
Приложение, не получившее описания (ответ 404 либо массив строк от сервера прежней версии), должно продолжать работать на собственных сведениях о разделах.

Запрос

Пример запроса

GET /rest/v1/fs/targets HTTP/1.1

Ответ

Пример ответа

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "schema" : 1,
  "version" : "1.11.0",
  "domain" : "example.local",
  "domain_type" : "master",
  "limits" : {
    "max_file_size" : 536870912,
    "recursive_delete" : { "files" : 10000, "bytes" : 10737418240 }
  },
  "groups" : [
    { "id" : "sounds", "title" : "Sounds" },
    { "id" : "certs", "title" : "Certificates" },
    { "id" : "domain_files", "title" : "Domain files" },
    { "id" : "publish", "title" : "Publishing" },
    { "id" : "provisioning", "title" : "Auto-provisioning" },
    { "id" : "storage", "title" : "Storage roots" },
    { "id" : "system", "title" : "System" }
  ],
  "targets" : [
    {
      "name" : "cacerts",
      "url" : "/rest/v1/fs/targets/cacerts",
      "title" : "Root certificates",
      "summary" : "Additional root certificates used to verify external services",
      "structure" : "tree",
      "params" : [],
      "methods" : {
        "collection" : [ "GET", "POST", "METADATA", "CLEAR", "DOWNLOADZIP", "UPLOADZIP" ],
        "item" : [ "GET", "HEAD", "POST", "PUT", "DELETE", "METADATA" ],
        "directory" : [ "GET", "METADATA", "PUT", "DELETE", "CLEAR", "DOWNLOADZIP", "UPLOADZIP" ]
      },
      "writable" : true,
      "max_file_size" : 536870912,
      "doc" : "/docs/era/latest/api/rest/v1/fs/targets/cacerts.html",
      "group" : null,
      "storage" : null,
      "macro" : null,
      "public_url" : null,
      "caution" : "normal",
      "actions" : [
        { "id" : "reload",
          "method" : "RELOAD",
          "url" : "/rest/v1/master/logicalroles/all/cacerts",
          "label_key" : "actions.cacerts.reload" }
      ]
    },
    {
      "name" : "syncroot",
      "root_suffix" : "common",
      "url" : "/rest/v1/fs/targets/syncroot/common",
      "title" : "Synchronization root",
      "structure" : "tree",
      "params" : [],
      "methods" : { "collection" : [ "GET", "POST", "METADATA", "CLEAR", "DOWNLOADZIP", "UPLOADZIP" ],
                    "item" : [ "GET", "HEAD", "POST", "PUT", "DELETE", "METADATA" ],
                    "directory" : [ "GET", "METADATA", "PUT", "DELETE", "CLEAR", "DOWNLOADZIP", "UPLOADZIP" ] },
      "writable" : true,
      "doc" : "/docs/era/latest/api/rest/v1/fs/targets/syncroot_common.html"
    },
    {
      "name" : "cpd_templates",
      "url" : "/rest/v1/fs/targets/cpd_templates/{type}",
      "title" : "CPD templates",
      "structure" : "flat",
      "params" : [
        { "name" : "type", "in" : "path", "required" : true, "values" : [ "ivr", "queue" ] }
      ],
      "methods" : { "collection" : [ "GET", "POST", "METADATA" ],
                    "item" : [ "GET", "HEAD", "POST", "PUT", "DELETE", "METADATA" ] },
      "writable" : true
    }
  ]
}

Состав описания

Общие поля

Поле Тип Описание

Поле	Тип	Описание
`schema`	`int`	Версия формата описания. Приложение, встретившее незнакомое значение, должно игнорировать описание целиком и работать на собственных сведениях.
`version`	`str`	Версия платформы.
`domain, domain_type`	`str`	Текущий домен и его тип (`master` либо `worker`). Состав разделов и право записи от них зависят.
`limits.max_file_size`	`int`	Предельный размер тела запроса в байтах.
`limits.recursive_delete`	`object`	Границы рекурсивных операций: число файлов и суммарный объём. См. Операции над каталогами.
`groups`	`array<object>`	Каталог групп для отображения разделов в приложениях: `id` и название на английском языке. Раздел ссылается на группу полем `group`. Раздел без группы отдаёт `null` — приложение относит такие к «прочим» самостоятельно, отдельной группы для них в каталоге нет.
`targets`	`array<object>`	Описания разделов.

schema

int

Версия формата описания. Приложение, встретившее незнакомое значение, должно игнорировать описание целиком и работать на собственных сведениях.

version

str

Версия платформы.

domain, domain_type

str

Текущий домен и его тип (master либо worker). Состав разделов и право записи от них зависят.

limits.max_file_size

int

Предельный размер тела запроса в байтах.

limits.recursive_delete

object

Границы рекурсивных операций: число файлов и суммарный объём. См. Операции над каталогами.

groups

array<object>

Каталог групп для отображения разделов в приложениях: id и название на английском языке.

Раздел ссылается на группу полем group. Раздел без группы отдаёт null — приложение относит такие к «прочим» самостоятельно, отдельной группы для них в каталоге нет.

targets

array<object>

Описания разделов.

Поля раздела

Поле Тип Описание

Поле	Тип	Описание
`name`	`str`	Имя раздела. Совпадает с именем из перечня `/rest/v1/fs/targets/`, по нему описание и сопоставляется с перечнем.
`root_suffix`	`str`	Хвост корня у составных разделов. Присутствует у `syncroot` (`common`), `globalshare` и `siteshare` (`public`). Имя раздела при этом остаётся первым сегментом пути.
`url`	`str`	Полный путь коллекции, включая суффикс корня.
`title, summary`	`str`	Название раздела и краткое назначение на английском языке. Приложения отображают их как есть и не переводят.
`structure`	`str`	`tree` — раздел поддерживает вложенные каталоги произвольной глубины; `flat` — только файлы одного уровня. От этого зависит доступность операций над каталогами и архивов.
`params`	`array<object>`	Параметры пути. У `cpd_templates` это `type`, допустимые значения приходят в поле `values`.
`methods`	`object`	Фактически поддерживаемые методы, раздельно для коллекции (`collection`), файла (`item`) и каталога (`directory`). Набор зависит от раздела и от текущего домена, см. Как формируются наборы методов. Ключ `directory` присутствует только у разделов со структурой `tree`. `DELETE` коллекции не поддерживается ни одним разделом — корень раздела удалить нельзя, его можно только очистить.
`writable`	`bool`	Разрешена ли запись в текущем домене. Раздел `product` в рабочем домене доступен только для чтения.
`max_file_size`	`int`	Предельный размер файла для этого раздела.
`doc`	`str`	Адрес статьи справки о разделе на этом же сервере.
`storage`	`str`	Категория хранения каталога.
`macro`	`str`	Префикс доступа к разделу из сценариев.
`public_url`	`str`	Шаблон публичной ссылки для разделов с публикуемым содержимым.
`actions`	`array<object>`	Действия, которые администратор может выполнить над разделом. Каждый элемент: `id`, `method`, `url` и `label_key` — ключ подписи кнопки, которую локализует приложение. Например, у `cacerts` — перезагрузка списка сертификатов на нодах после изменения состава. Сервер эти действия никогда не вызывает сам. Поле описывает то, что приложение предлагает нажать пользователю: при загрузке нескольких файлов действие выполняется один раз, а не после каждого. У разделов без действий — пустой массив, а не `null`.
`caution`	`str`	Степень опасности операций над разделом: `normal` либо `high`. `high` означает, что содержимое раздела затрагивает работу всей установки либо все данные домена, и приложение должно требовать дополнительного подтверждения перед удалением и очисткой. Серверного поведения признак не меняет.

name

str

Имя раздела. Совпадает с именем из перечня /rest/v1/fs/targets/, по нему описание и сопоставляется с перечнем.

root_suffix

str

Хвост корня у составных разделов. Присутствует у syncroot (common), globalshare и siteshare (public). Имя раздела при этом остаётся первым сегментом пути.

url

str

Полный путь коллекции, включая суффикс корня.

title, summary

str

Название раздела и краткое назначение на английском языке. Приложения отображают их как есть и не переводят.

structure

str

tree — раздел поддерживает вложенные каталоги произвольной глубины; flat — только файлы одного уровня. От этого зависит доступность операций над каталогами и архивов.

params

array<object>

Параметры пути. У cpd_templates это type, допустимые значения приходят в поле values.

methods

object

Фактически поддерживаемые методы, раздельно для коллекции (collection), файла (item) и каталога (directory).

Набор зависит от раздела и от текущего домена, см. Как формируются наборы методов. Ключ directory присутствует только у разделов со структурой tree. DELETE коллекции не поддерживается ни одним разделом — корень раздела удалить нельзя, его можно только очистить.

writable

bool

Разрешена ли запись в текущем домене. Раздел product в рабочем домене доступен только для чтения.

max_file_size

int

Предельный размер файла для этого раздела.

doc

str

Адрес статьи справки о разделе на этом же сервере.

storage

str

Категория хранения каталога.

macro

str

Префикс доступа к разделу из сценариев.

public_url

str

Шаблон публичной ссылки для разделов с публикуемым содержимым.

actions

array<object>

Действия, которые администратор может выполнить над разделом. Каждый элемент: id, method, url и label_key — ключ подписи кнопки, которую локализует приложение.

Например, у cacerts — перезагрузка списка сертификатов на нодах после изменения состава.

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

У разделов без действий — пустой массив, а не null.

caution

str

Степень опасности операций над разделом: normal либо high.

high означает, что содержимое раздела затрагивает работу всей установки либо все данные домена, и приложение должно требовать дополнительного подтверждения перед удалением и очисткой. Серверного поведения признак не меняет.

Как формируются наборы методов

Поле methods описывает то, что сервер примет в текущем домене для этого раздела, а не то, что объявлено обработчиком вообще. Базовый набор сужается тремя независимыми правилами.

Маршрут элемента отсутствует в этом домене. Тогда item — пустой массив. Так устроен раздел product: в рабочем домене доступен только перечень архивов, чтобы выбрать версию при установке продуктового слоя, а обращаться к отдельному файлу нельзя. Пустой item означает «файловые операции здесь недоступны», а не «раздел пуст».

Запись в разделе недоступна в этом домене. Тогда из всех наборов исключаются пишущие методы — POST, PUT, DELETE, CLEAR, UPLOADZIP. Читающие остаются: скачать каталог архивом из раздела, доступного только для чтения, можно. Значение writable при этом равно false; оно отвечает на тот же вопрос коротко, а methods — точно.

Раздел одноуровневый. Тогда ключа directory в methods нет вовсе. Это отличается от пустого массива: пустой набор означал бы, что каталоги здесь есть, но операций над ними не предусмотрено, тогда как в одноуровневом разделе подкаталогов не бывает.

Правила независимы и могут действовать одновременно. У product в рабочем домене выполняются все три сразу.

Приложению не нужно сверять methods со structure или с writable: набор уже учитывает и то и другое.

Поля storage, macro, public_url и group могут иметь значение null: сведения задаются для каждого раздела отдельно и заполнены не у всех. Приложение должно корректно работать при отсутствии значения — не показывать соответствующее действие, а не подставлять собственное.

См. также

Назначения (targets) — перечень разделов и статьи по каждому из них.
Мета-информация о файлах, каталогах и разделах.