'rest' capability для WebSocket User API

Содержание

Обзор
Построение запросов
- Примеры запросов к статическим и динамическим коллекциям
- Специальные коллекции
Настройка подключения для выполнения REST-запросов
Переповторы вместо 5хх
Ссылки

Обзор

Предоставляет интерфейс для проведения CRUD операций с сущностями статических и динамических классов. Для работы требует наличия у пользователя роли, разрешающей доступ к маршруту /ws#rest с методом WEBSOCKET.

При запросах осуществляет дополнительную ролевую авторизацию на доступ к конкретным endpoint REST-API на конкретную операцию. Различаются endpoint коллекции, конкретных элементов коллекции, а также свойств для доступа к вложениям. Так, если пользователю маршрутами в ролях разрешен лишь метод GET к коллекции класса, то он сможет читать коллекцию, но не сможет читать конкретную сущность и изменять и создавать сущности.

Каждое непустое изменение завершается генерацией уведомлений подписчикам.

Никаких событий этот rest-capability не генерирует.

Среди классов, к которым возможно обращение:

Статические коллекции доменного центра;
Динамические коллекции модели данных;
Специальные коллекции.

Построение запросов

Общий вид запроса:

[
  "rest",
  {
    "qid":"16066361-dfc0-49f6-b734-9b3dda09db22",
    "operation": "...",
    "classpath": "/rest/v1/...",
    ...
  }
]

Обязательные поля запроса:

operation - тип операции над классом (read, create, replace, update, delete, clear, lookup).
classpath - полный путь к коллекции класса в REST-API: "/rest/v1/model/builder/packages/Packages",

Специфические поля запроса:

interval - список из двух дат (начало и конец периода). Необходим к указанию в операциях выборки из коллекций динамических классов, имеющих storage_mode = history или transactionlog.
id - идентификатор конкретной сущности. При проведении операций с коллекцией (выборка элементов, поиск, очистка коллекции) необходимо исключать поле из запроса.
content - содержимое запроса. Необходимо при создании, замене, изменении сущности (json-объект), а также в случае поиска по ключу (значение подлежащее поиску - строка или число).
hrkey - устанавливает ключ для hashring-выбора процесса-обработчика операций модификации. По умолчанию используется идентификатор сущности. Применяется для организации распараллеливания обработки операций модификации и чтения конкретной сущности (для классов с integrity_mode: async, sync_fast_read, sync_fast_notify). Привязка к конкретному процессу-обработчику позволяет сохранять важную для системы-клиента последовательность операций при обработке и в уведомлениях. Отдельный ключ может использоваться для сохранения гарантированного сохранения последовательности операций с несколькими различными сущностями класса в рамках одной супер-операции, известной системе-клиенту.

Поля условий выборки - все опциональны:

filter - условие фильтра. См. функции общего назначения.
order - порядок сортировки.
mask - поля выдачи.
offset - смещение в выборке.
limit - ограничение количества элементов в выборке.
aggr - поля агрегации. Объект, содержащий ключами возвращаемые поля, а значениями - функции агрегации. В качестве аргумента допускает применение суперпозиции функций, построение которой аналогично функциям фильтра. См. (функции агрегации).
groupby - база агрегации. Объект, содержащий ключами возвращаемые поля, а значениями - названия полей объекта или список, представляющий собой суперпозицию функций. Построение функций аналогично функциям фильтра. См. (функции общего назначения).

Поддерживаются операции:

read - выборка из коллекции, в том числе агрегирующая.
read - если указано поле id, то в ответ на запрос возвращаются данные конкретной сущности, имеющей указанный идентификатор. Опционально допускается маскировка (mask).
lookup - поиск идентификаторов элементов коллекции по ключевым полям. Значение для поиска передается в поле content.
clear - очистка коллекции. Поддерживается только в коллекциях динамических классов.
create - создание сущности в коллекции с автогенерацией идентификатора.
replace - создание или полная замена сущности с указанным идентификатором. Поддерживается только в коллекциях динамических классов.
update - изменение существующей сущности с указанным идентификатором. Неуказанные поля остаются неизменными. В коллекциях динамических классов (dms) производится замещение значений полей целиком. В коллекциях статических классов (dc) композитные поля допускают частичное обновление на 1 уровень в глубину.
delete - удаление существующей сущности с указанным идентификатором.
setup - рантайм настройка коллекции (например, временная приостановка рассылки уведомлений подписчикам об изменениях, чтение и удаление партиций). Тип операции и ее возможные параметры передаются в виде объекта в поле content.

Примеры запросов к статическим и динамическим коллекциям

Выборка элементов из коллекции:

[
  "rest",
  {
    "qid": "16066361-dfc0-49f6-b734-9b3dda09db22",
    "operation": "read",
    "classpath": "/rest/v1/model/builder/packages/Packages",
    "filter": ["or",["like",["property","pstr"],"asdf*"],["==",["property","pint"],8640000]],
    "order": ["pstr",{"pint","desc"},{"id","asc"}],
    "mask": ["id","pstr"],
    "offset": 0,
    "limit": 2
  }
]

Агрегирующая выборка из коллекции:

[
  "rest",
  {
    "qid": "16066361-dfc0-49f6-b734-9b3dda09db22",
    "operation": "read",
    "classpath": "/rest/v1/model/builder/packages/Packages",
    "filter": ["like",["property","pstr"],"a*"],
    "groupby":{"a":["%",["property","pint"],10]},
    "aggr":{"cnt":["sum",["-",["property","pint"],1]]}
    "offset": 0,
    "limit": 2
  }
]

Поиск элементов в коллекции по ключевым полям:

[
  "rest",
  {
    "qid": "16066361-dfc0-49f6-b734-9b3dda09db22",
    "operation": "lookup",
    "classpath": "/rest/v1/model/builder/packages/Packages",
    "content": "abc"
  }
]

Очистка коллекции:

[
  "rest",
  {
    "qid": "16066361-dfc0-49f6-b734-9b3dda09db22",
    "operation": "clear",
    "classpath": "/rest/v1/model/builder/packages/Packages"
  }
]

Чтение сущности:

[
  "rest",
  {
    "qid": "16066361-dfc0-49f6-b734-9b3dda09db22",
    "operation": "read",
    "classpath": "/rest/v1/model/builder/packages/Packages",
    "id": "c87a8ca6-0f08-91b7-9d19-2fa86f019916"
  }
]

Создание сущности:

[
  "rest",
  {
    "qid": "16066361-dfc0-49f6-b734-9b3dda09db22",
    "operation": "create",
    "classpath": "/rest/v1/model/builder/packages/Packages",
    "content": { ... }
  }
]

Замена сущности:

[
  "rest",
  {
    "qid": "16066361-dfc0-49f6-b734-9b3dda09db22",
    "operation": "replace",
    "classpath": "/rest/v1/model/builder/packages/Packages",
    "id": "c87a8ca6-0f08-91b7-9d19-2fa86f019916",
    "content": { ... }
  }
]

Изменение сущности:

[
  "rest",
  {
    "qid": "16066361-dfc0-49f6-b734-9b3dda09db22",
    "operation": "update",
    "classpath": "/rest/v1/model/builder/packages/Packages",
    "id": "c87a8ca6-0f08-91b7-9d19-2fa86f019916",
    "content": { ... }
  }
]

Удаление сущности:

[
  "rest",
  {
    "qid": "16066361-dfc0-49f6-b734-9b3dda09db22",
    "operation": "delete",
    "classpath": "/rest/v1/model/builder/packages/Packages",
    "id": "c87a8ca6-0f08-91b7-9d19-2fa86f019916"
  }
]

Поиск сущности по ключу:

[
  "rest",
  {
    "qid": "16066361-dfc0-49f6-b734-9b3dda09db22",
    "operation": "lookup",
    "classpath": "/rest/v1/model/builder/packages/Packages",
    "content": "asdfasdf"
  }
]

Рантайм настройка коллекции:

[
  "rest",
  {
    "qid": "16066361-dfc0-49f6-b734-9b3dda09db22",
    "operation": "setup",
    "classpath": "/rest/v1/model/builder/packages/Packages",
    "content": {
      "cmd": "suspend_notification"
    }
  }
]

Специальные коллекции

/rest/v1/domain/nservices

Выполнение запросов к наносервисам продуктового слоя.

Получение списка активных наносервисов:

[
  "rest",
  {
    "qid": "16066361-dfc0-49f6-b734-9b3dda0915f7",
    "operation": "read",
    "classpath": "/rest/v1/domain/nservices"
  }
]

Ответ:

[
  "rest",
  {
    "qid": "16066361-dfc0-49f6-b734-9b3dda0915f7",
    "data": [
      {"name":"builder.DataService"},
      {"name":"builder.GeneratorService"}
    ]
  }
]

Выполнение запроса к наносервису:

[
  "rest",
  {
    "qid": "16066361-dfc0-49f6-b734-9b3dda09472e",
    "operation": "create",
    "classpath": "/rest/v1/domain/nservices",
    "name": "platform.PerfmonService",
    "method": "test",
    "request": {"a":1,"b":"2","cc":[{"d":100,"e":"200"},{"f":300}]}
  }
]

Ответ на запрос:

[
  "rest_result",
  {
    "qid": "16066361-dfc0-49f6-b734-9b3dda09472e",
    "data": {
      "result": "ok",
      "code": "success",
      "response": {"a":"zxcvzxcvzxcv"}
    }
  }
]

Подробнее в разделе Выполнение HTTP запросов к активным наносервисам продуктового слоя

Настройка подключения для выполнения REST-запросов

Общий вид запроса:

[
  "setup_rest",
  {
    "qid": 0.1234,
    "skip_response_entity": true,
    ...
  }
]

Возможные опции - поля запроса:

skip_response_entity - позволяет для конкретного вебсокет-подключения установить запрет на отправку полной сущности в ответ на операции create, replace, update. При этом create все же отправляет обратно сущность с единственным полем "id", другие запросы возвращают просто 'ok'.

Переповторы вместо 5хх

Запросы, которые не могут быть обработаны (переезд микросервисов, таймауты, перегрузка очередей и др.) отвечаются ошибкой с кодом 5хх, эквивалентно кодам HTTP.

Конфигурационный параметр веб-сервера 'rest_reattempts_sec' позволяет управлять режимом переповтора. Пока установленный интервал не истек, веб-сервер делает периодические попытки переотправить запрос целевому микросервису. Это позволяет продуктовым микросервисам, взаимодействующим с моделью данных платформы, не переинициализироваться, а находиться в ожидании. Повторы осуществляются не чаще чем 1 раз в 5 секунд. В течение 5 секунд после отправки запроса ожидается получение отчета о доставке. В течение 30 секунд после отправки запроса ожидается получение ответа.

Побочные эффекты:

За время переотправки может сработать ряд таймаутов в логике инициатора запроса.
Если запрос доставлен, но за 30 секунд не обработался (в целевом микросервисе имеется непустая очередь к БД, где запрос ожидал исполнения), то:
- в случае, когда запрос еще не поступил на исполнение из очереди, он будет отменен.
- в случае, когда запрос уже исполняется, повторные обращения а) спровоцируют дополнительную нагрузку на БД, отчего очередь вырастет еще сильнее, б) запросы create и delete в ходе повторных выполнений будут завершены ошибкой 404.

Ссылки

REST-API для коллекций динамических классов
Функции общего назначения для фильтра и базы агрегации
Функции агрегации