WebSocket песочница

Общая информация

Для облегчения разработки интеграций, отладки и тестирования, в состав платформы включена websocket-песочница.

Это мини-приложение позволяет быстро и удобно подключаться к платформе по WebSocket, производить запросы, осуществлять подписки и визуализировать результаты.

Песочница доступна на каждой инсталляции, по следующему адресу:

https://[era_platform_fqdn]/integration/ws_sandbox.html

Например, она доступна на ресурсе Vendor:

https://vendor.era-platform.ru/integration/ws_sandbox.html

Данный инструмент позволяет наглядно протестировать все процессы работы с WebSocket в рамках платформы.

Песочница вертикально разделена на 3 зоны:

• Слева находится управление запросами и шаблонами, а также настройки авторизации.
• По центру выводятся табличные данные классов, если производится их чтение с отображением.
• Справа отображается история сообщений в WebSocket, а также поле для свободной отправки сообщений.

Авторизация и начало работы

Параметры авторизации

Для подключения к вебсокету необходимо указать следующие параметры:

• Адрес сервера
  • При использовании HTTPS необходимо использовать схему WSS: wss://192.168.98.10
  • При использовании HTTP, необходимо использовать схему WS: ws://192.168.98.10
  • При использовании портов, отличных от стандартных (443 и 80), необходимо указывать их через двоеточие: ws://192.168.98.10:8080
• Тип авторизации
  • Учетная запись пользователя домена
  • Авторизационный токен канала интеграции
• Домен*
• Логин*
• Пароль*

*только при использовании авторизации через учетную запись.

Тип авторизации определяет используемый WebSocket API:

• User-API
• Token-API

Старт соединения

Для начала работы, необходимо произвести несколько базовых шагов:

1. Подключиться к WebSocket
2. Настроить соединение - передать сообщение setup, в котором перечислить требуемые capabilities
3. Произвести авторизацию - передать авторизационные данные

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

• Connect - подключение
• Setup - настройка соединения
• Login - авторизация

Каждая из этих кнопок отправляет шаблонное сообщение, позволяющее без ручного составления JSON пройти каждый из этих шагов.

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

Кнопка Info позволяет получить информацию о текущем подключении:

• Сайт
• Домен
• Идентификаторы пользователя, сессии и подключения
• Текущие возможности Websocket (запрошенные через сообщение setup)
• Текущая дата и время
• Роли
• и т.д.

Кнопка Close позволяет закрыть текущее соединение.

Работа с данными классов

Песочница позволяет удобно производить запросы к классам платформы и продуктового слоя. Доступны следующие операции:

• Чтение
• Подписка на изменение
• Визуализация данных
• Создание
• Замена по идентификатору
• Обновление по идентификатору
• Удаление по идентификатору

В качестве примера, в песочнице реализованы три шаблона.

Шаблон My status позволяет прочитать статус текущего пользователя, подписаться на его изменение и при необходимости изменить его.

Шаблон Call management позволяет просмотреть текущие (активные) звонки, а также управлять ими.

Шаблон My archive calls читает данные звонков текущего пользователя, и может использоваться как пример для работы с фильтрами, сортировкой и интервалами (для классов со storageMode=history).

Чтение данных

Для операций чтения данных используется следующие параметры, для подстановки в шаблон:

Параметр	Пример	Комментарий
Table caption	My archive calls	Заголовок таблицы, используемый при визуализации данных. Опциональный параметр
Class name	model/callcenter/connections/ArchiveConnections	Полное имя класса, из которого будет производиться чтение. Обязательный параметр
Filter	["or",["==",["property","sideA","user_id"],["const","166f5849-018e-7bfc-a0d5-960002bdc633"]],["==",["property","sideB","user_id"],["const","166f5849-018e-7bfc-a0d5-960002bdc633"]]]	Фильтр, используемый для чтения данных. При необходимости, можно воспользоваться визуальным редактором фильтров, например в REST Sandbox в приложении Builder. Опциональный параметр, однако при большом объеме данных, пустые фильтры следует использовать с осторожностью.
Interval	["2025-05-24T13:16:50.071Z","2025-07-31T13:16:50.071Z"]	Интервал запрашиваемых данных. Используется для чтения из классов со storageMode=history. Для них является обязательным, для других не используется.
Order	[{"timeStart":"desc"}]	Массив параметров сортировки. Опциональный параметр.
Properties	timeStart;direction;sideA.display;sideB.display;durationTalk	Список свойств класса, которые необходимо выводить в таблицу при визуалциации данных. Опциональный параметр.
Actions	getFileName=CCS_getRecordedFile|recordInfo#{"recordLink":"[recordLink]"}	Список доступных действий. Используется для формирования шаблонов вызова сервисов. Вызов сервисов будет рассмотрен в следующем блоке статьи. Опциональный параметр.

В блоке чтения (Class read and subscribe) доступно три вида операций:

• Read, subscribe and show - осуществляет чтение данных, подписку на их изменение и отображает результат в виде таблицы
• Only read - осуществляет только чтение данных. Результат чтения будет доступен в истории сообщений Websocket.
• Only subscribe - осуществляет только подписку. При изменении данных, сообщения об этом будут доступны в истории сообщений.

Запись данных

Блок записи данных (Class write) позволяет осуществлять операции Insert/Update/Delete.

Для этих операций используется четыре параметра:

• Class name - полное имя класса
• id - идентификатор записи
• timestamp - таймстемп записи (только для классов со storageMode=history)
• data - JSON данных класса

Все параметры являются обязательными, кроме параметра data при удалении данных.

В блоке записи доступны четыре вида операций:

• Insert data - Добавляет новую запись
• Replace id with data - Полностью заменяет запись с указанным ID на новую, переданную в параметре data
• Update id with data - Обновляет значения полей у записи с указанным ID. Обновляются те поля, которые указаны в параметре data
• Delete id - Удаляет запись с указанным ID.

Вызов сервисов

Блок вызова сервисов (Invocations) позволяет обращаться к сервисам платформы и продуктового слоя.

Для вызова используется четыре параметра:

Параметр	Пример	Комментарий
Service name	callcenter.HolderService	Имя сервиса для вызова. Обязательный параметр.
Method name	CCS_getRecordedFile	Имя метода сервиса. Обязательный параметр.
ID	03f2f6f4-b450-668a-7384-7abea3ab306e	Идентификатор объекта для передачи в метод сервиса в качестве параметра. Обзательность зависит от конкретного метода.
Parameters	{"recordInfo":{"recordLink":""}}	Параметры метода. Обязательность зависит от метода.

При вызове сервиса, доступно только одно действие - Invoke (вызвать). Результат исполнения можно будет посмотреть в истории сообщений.

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

Формат нотации действий следующий:

[ActionCaption]=[MethodName];
Пример:
answer=CurrentCall_answer;

Несколько действий разделяются точкой с запятой. Идентификатор (id) выбранной строки данных будет указан автоматически. Также можно в нотации использовать подстановку параметров через вертикальную черту:

[ActionCaption] = [MethodName] | [ParameterName] # [ParameterValue]

getFileName=CCS_getRecordedFile|recordInfo#{"recordLink":"[recordLink]"}

Данный запрос создаст JSON с параметром recordInfo, значением которого будет переднный JSON-объект.

При использовании квадратных скобок, система автоматически подставит значение класса с указанным именем.

Пример сформированного JSON из параметра в примере:

{"recordInfo":{"recordLink":"fs://..............."}}

Ручная отправка запросов

В правой части под историей сообщений доступен ручной ввод сообщений для отправки.

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

[
  "subscribe",
  {
    "qid": "16066361-dfc0-49f6-b734-9b3dda09db22",
    "objects": ...,
    "events": ...,
    "expires": ...,
    "id": ...
    "exargs": ...
    ...
  }
]