Концепция Websocket API

Обзор

Адрес подключения

Для подключения к системе через websocket может использоваться любой веб-сервер. Используются те же адрес и порт, что и для HTTP.

Подключение по websocket должно инициироваться внешней системой. Websocket handshake поддерживается при запросах на специальные URL:

  • user-api – /ws, требует авторизации. Обслуживает клиентские подключения от пользователей системы.

  • token-api – /ws/token/v1/:TOKEN, где :TOKEN - идентификатор из поля token_local сущности integration_point. Не требует авторизации, её заменяет наличие :TOKEN. Обслуживает интеграционные подключения от внешних сервисов и систем.

Формат сообщений

Все сообщения имеют формат json-массива из двух элементов:

["method",{... params ...}]

Если метод является запросом, то он:

  • должен содержать параметр qid, содержащий уникальный идентификатор произвольного типа для сопоставления с ответом.

  • предполагает ответ ["method_result",{…​ params …​}], содержащий тот же самый qid и определенные протоколом параметры, в частности result.

Если метод является асинхронным сообщением, то он может оформляться в виде запроса с ответом, лишь подтверждающим получение, либо не предполагать ответа вовсе. Параметр qid в этом случае не является обязательным.

Настройка подключения

Изначально сервер поддерживает только базовые методы login - для авторизации, и setup - для настройки подключения. Любые другие методы не будут доступны, и при их запросе сервер вернёт ошибку.

Для того, чтобы подключение обрело функциональность, требуется его настроить методом setup.

Сообщение-запрос:
["setup",{"qid":0.5828120205227802,
          "capabilities":[{"key":"a"},
                          {"key":"b"}] }]
Сообщение-ответ:
["setup_result", {
   "qid":0.5828120205227802,
   "capabilities":[
     {"key":"a","result":"ok"},
     {"key":"b","result":"error","errormsg":"Unknown capability"}] }]

В рамках user-api сообщение-запрос может содержать опциональные параметры:

  • params - дополнительные настройки подключения, применяемые некоторыми API.

  • appPath - относительный URL пользовательского приложения, осуществившего подключение.

Например:
["setup", {"qid":0.34198798,
           "capabilities":[{"key":"a"},{"key":"b"}],
           "params":{"x":1,"y":"abc"},
           "appPath":"/app/arm" }]

Указанные в свойстве capabilities различные подключаемые API, фильтруются сервером. Фильтрация производится на основании:

  • а) обнаруженных модулей,

  • б) настроенных endpoint в метаданных сервиса IAM (ассеты iam_all.json и iam.json),

  • в) назначенных ролей авторизованного пользователя.

По отфильтрованным API в ответе вернется информация о причине неудачи.

После успешного подключения требуемых API, подключенному приложению или системе в рамках настроенного веб-сокет подключения становятся доступны все методы этих API. Также подключенные API начинают снабжать серверными событиями.

Если метод setup вызывается до авторизации (в рамках user-api), то в ответе на него все capabilities возвращают "ok", но после авторизации в ответ на запрос login сервер отправит модифицированный список capabilities.

См. также

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