Приложения

Приложение в ONS объединяет устройства и даёт внешней системе доступ к их данным: к WebSocket API подключаются с App ID приложения и одним из его токенов. В разделе «Приложения» веб-интерфейса создают приложения, задают лимиты соединений, выпускают и отзывают токены, выдают права другим пользователям. Пункт меню «Приложения» открывает список по адресу /applications.

Кто видит раздел

Что	Кому доступно
Пункт меню «Приложения» и сам раздел	Группы admin, monitoring и суперпользователь (superuser)
Кнопка «Добавить приложение» и действие «Удалить»	Группы admin, application_admin и суперпользователь
Действие «Права»	Группа dealer и суперпользователь
Изменение существующего приложения и выпуск токенов	Владелец приложения, суперпользователь или пользователь с правом «Изменение» на это приложение, см. Права пользователей на приложения
Удаление токенов	Владелец приложения и суперпользователь

Кнопки и действия из таблицы видны только тому, кто может открыть сам раздел. Учётная запись только из группы monitoring видит список, но не может добавлять и удалять приложения.

Список приложений

В списке только активные приложения, владельцем которых является пользователь или на которые ему выдано право просмотра. Суперпользователь видит все активные приложения.

1. Поле поиска и кнопка Найти — поиск по части имени, App ID или App EUI и по значениям дополнительных полей.
2. Добавить приложение — открывает страницу /applications/add.
3. Действие и Выполнить — «Удалить» или «Права» для отмеченных строк.
4. Настройки таблицы (шестерёнка) — переключатель «Сокращать текст».
5. Флажок в заголовке таблицы — отмечает все строки страницы.
6. Имя — ссылка на страницу приложения.
7. Количество клиентов и Количество потребителей — открытые соединения WebSocket API и те из них, что подписаны на данные.
8. Размер таблицы — число строк на странице, по умолчанию 25.

Столбец	Что показывает
«Имя»	Название приложения; ссылка на его страницу
«Узлы»	Число активных устройств приложения, без multicast-групп
«App ID»	Идентификатор приложения, 8 hex-символов
«App EUI»	AppEUI приложения, 16 hex-символов
«Количество данных в час»	Пакеты приложения за последний час, кроме downlink
«Последнее сообщение»	Самое позднее время последних данных среди устройств приложения, в формате ГГГГ-ММ-ДД чч:мм:сс
«Количество клиентов»	Сколько соединений WebSocket API с приложением открыто. Счётчик ведёт сервер WebSocket
«Количество потребителей»	Сколько из этих соединений подписано на данные. Счётчик ведёт сервер WebSocket
Дополнительные поля	Поля, которые задал администратор

Поиск находит приложения по части имени, App ID или App EUI без учёта регистра, а также по значениям дополнительных полей. Сортировать можно по столбцам «Имя», «App ID», «App EUI», «Количество клиентов» и «Количество потребителей»: первый щелчок по заголовку сортирует по возрастанию, второй — по убыванию, третий сбрасывает сортировку.

На странице по умолчанию 25 строк; чтобы изменить, введите число в поле под таблицей и нажмите кнопку «Размер таблицы». В меню с шестерёнкой «Настройки таблицы» есть переключатель «Сокращать текст». Поиск, сортировку, размер таблицы и режим сокращения браузер запоминает (localStorage) и восстанавливает при следующем открытии списка; список всегда открывается с первой страницы.

Действие над несколькими приложениями:

1. Отметьте строки — по одной или флажком в заголовке таблицы (вся страница).
2. Выберите «Действие»: «Удалить» или «Права».
3. Нажмите «Выполнить».

Когда отмечены все строки страницы, ссылка «Выбрать все (N)» распространяет выбор на все найденные приложения — только если в поиске задан текст. Без текста в поиске действие применяется лишь к строкам текущей страницы, хотя над таблицей написано «Выбраны все N». Щелчок с нажатой Shift отмечает диапазон только визуально: действие выполнится лишь для строк, отмеченных отдельными щелчками или флажком в заголовке таблицы.

Создание приложения

1. В списке нажмите «Добавить приложение» — откроется страница /applications/add.
2. Поля «App ID» и «App EUI» уже заполнены: сервер генерирует случайные значения в верхнем регистре, которых ещё нет в базе. Изменить их нельзя ни при создании, ни позже.
3. Заполните «Имя» и при необходимости остальные поля — см. Поля приложения.
4. Нажмите «Добавить»: приложение создаётся, и открывается список.
5. Откройте новое приложение и добавьте токен — см. Токены и уровни доступа. Приложение, созданное в веб-интерфейсе, токенов не имеет.

На странице существующего приложения две кнопки: «Сохранить» сохраняет изменения и возвращает в список, «Сохранить и продолжить редактирование» сохраняет и оставляет на странице. Кнопки активны, только когда в форме есть изменения и все поля заполнены верно. Изменение только поля «Доступные приложения» кнопки не включает: измените вместе с ним, например, поле «Имя» — введите и сотрите символ. Без права изменения приложения кнопок нет.

Поля приложения

1. Имя — обязательно, до 256 символов.
2. App ID и App EUI — уже заполнены сервером, изменить нельзя.
3. Выход — выход приложения, обязательно.
4. Кол-во клиентов, до и Кол-во потребителей, до — пороги для соединений и подписок WebSocket API, по умолчанию 2 и 1.
5. Автостарт потребления — автоподписка новых соединений, по умолчанию выключена.
6. Доступные приложения — приложения, данные которых получает это приложение.
7. Добавить — создаёт приложение и открывает список.

Поле	Что задаёт	По умолчанию
«Имя»	Название приложения. Обязательно, до 256 символов. Уникальность не проверяется: два приложения могут называться одинаково	—
«App ID»	Идентификатор приложения, 8 hex-символов. Генерирует сервер, изменить нельзя	Случайное значение
«App EUI»	AppEUI приложения, 16 hex-символов. Генерирует сервер, изменить нельзя	Случайное значение
«Выход»	Выход приложения. Обязательно. Список вариантов хранится на сервере	Выход с номером 1
«Кол-во клиентов, до»	Порог для соединений WebSocket API: сервер отклоняет новое соединение, когда уже открытых соединений больше этого числа. При значении 2 открываются три соединения, четвёртое получает ошибку 2	2
«Кол-во потребителей, до»	Порог для подписок: сервер отклоняет подписку, когда подписанных соединений уже больше этого числа. При значении 1 подписаться могут два соединения	1
«Автостарт потребления»	Автоподписка: сервер сам подписывает на данные каждое новое соединение	Выключено
«Доступные приложения»	Приложения, данные которых получает это приложение, см. ниже	—
Дополнительные поля	Поля, которые задал администратор	—

Те же значения получает приложение, созданное командой WebSocket API create_application_req: 2 в «Кол-во клиентов, до», 1 в «Кол-во потребителей, до», автоподписка выключена, выход с именем WebSocket.

Если у выбранного выхода тег http_push, в форме появляется блок «Настройки выхода» с обязательным полем «Целевой URL». Есть ли такой выход в списке, зависит от настроек сервера.

Как сервер применяет лимиты и автоподписку:

• Соединение, при котором уже открытых соединений больше значения «Кол-во клиентов, до», получает connected с ошибкой 2 (Clients count limit reached), и сервер закрывает его — см. Подключение.
• Подписка, при которой подписанных соединений уже больше значения «Кол-во потребителей, до», не проходит: на consume_req приходит consume_resp с ошибкой 1 (Consumer limit reached).
• С включённым «Автостарт потребления» сервер подписывает каждое новое соединение сразу после connected, если лимит подписок позволяет, и присылает consume_resp без operation_id. Повторный consume_req на таком соединении вернёт ошибку 2 (Already consumed).

Доступные приложения: данные других приложений

Поле «Доступные приложения» позволяет одному приложению получать данные устройств другого. Если в приложении X в этом поле выбрано приложение Y, то:

• соединения приложения X получают realtime_data от устройств приложения Y;
• токен низкого уровня приложения X видит устройства приложения Y и их данные — если у X и Y один владелец. Если Y принадлежит другому пользователю, соединения X получают realtime_data от устройств Y, но ни устройств Y, ни их сохранённых данных токен X не видит.

Настройку задают у получателя — в приложении X. Связь односторонняя: приложение Y данных приложения X не получает. В описании WebSocket API приложения из поля «Доступные приложения» называются приложениями, «которые открыли ему доступ».

Список выбора показывает не больше 50 последних созданных приложений, которые видит пользователь, в виде «имя/App ID». Ввод текста фильтрует только эти 50 приложений: на сервере поиск не выполняется.

Токены и уровни доступа

С токеном приложения подключаются к WebSocket API. Блок «Токены приложения» есть только на странице уже созданного приложения: на странице добавления его нет. Команда create_application_req, в отличие от веб-интерфейса, сразу выпускает для нового приложения токен низкого уровня.

1. Токен — 22 случайных символа.
2. Значок-галочка «Выберите токен» — какой токен подставлен в строку Websocket URL. Значок виден при наведении указателя на ячейку токена.
3. Уровень доступа — «Низкий» или «Высокий».
4. Удалить — отзывает токен.
5. Добавить токен — описание, уровень и кнопка «Добавить».
6. Websocket URL — готовый адрес подключения к WebSocket API с App ID приложения и выбранным токеном.
7. Кнопка копирования адреса в буфер обмена.
8. Кнопка на карточке блока «WebSocket приложения» — открывает инструмент с App ID приложения и первым токеном таблицы.

Столбец	Что показывает
«Токен»	Сам токен: 22 случайных символа — латинские буквы и цифры
«Описание»	Подпись к токену, до 255 символов
«Уровень доступа»	«Низкий» или «Высокий»
Кнопка «Удалить»	Отзывает токен

Уровень	Значение на сервере	Какие устройства видны
«Низкий»	0	Устройства своего приложения и приложений из поля «Доступные приложения»
«Высокий»	3	Без этого ограничения — все устройства владельца приложения

Что ещё разрешает каждый уровень — в разделе Токены и уровни доступа описания WebSocket API.

Добавить токен:

1. В последней строке таблицы, «Добавить токен», введите описание.
2. Выберите уровень: «Низкий» (по умолчанию) или «Высокий».
3. Нажмите «Добавить».

Удалить токен: нажмите «Удалить» в его строке и подтвердите вопрос «Вы уверены, что хотите удалить токен …?» — в нём указан сам токен. Сервер отзывает токен: он пропадает из таблицы, где показаны только действующие токены, и новые подключения с ним сервер отклоняет. Когда у приложения не остаётся ни одного действующего токена, consume_req возвращает ошибку 3 (Disabled application).

Без права изменения приложения кнопки «Добавить» и «Удалить» неактивны. Выпустить токен могут владелец приложения, суперпользователь и пользователь с правом «Изменение» на приложение. Отозвать токен могут только владелец приложения и суперпользователь: пользователю с правом «Изменение» кнопка «Удалить» доступна, но сервер отклонит запрос, и появится сообщение об ошибке.

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

Когда у приложения есть хотя бы один токен, под таблицей токенов появляется строка Websocket URL: <адрес>?app_id=<App ID>&token=<токен>. Это готовый адрес для подключения к WebSocket API.

• Адрес сервера — это адрес WebSocket API, заданный в настройках сервера ONS; он зависит от установки.
• В адрес подставляется токен, отмеченный в таблице значком-галочкой (подсказка «Выберите токен»). При открытии страницы отмечен первый токен таблицы. Сразу после добавления первого токена адрес выводится с пустым token=: отметьте токен галочкой или обновите страницу. После удаления выбранного токена в адресе остаётся отозванный токен — выберите другой.
• Кнопка рядом со строкой копирует адрес в буфер обмена. Подсказка у неё показывает служебное имя COPY_WEBSOCKET_URL: перевода для неё нет.

Ниже, если у приложения есть хотя бы один токен, расположен блок «WebSocket приложения» — встроенные инструменты веб-интерфейса:

Карточка	Подпись
lwParser	«Приложение для парсинга данных»
lwGPS	«GPS приложение»
lwLighting 1	«Lighting приложение v1»
lwLighting 2	«Lighting приложение v2»
lwNodeCertify	«Приложение для сертификации устройств»

Кнопка на карточке открывает инструмент с App ID этого приложения и первым токеном таблицы — не тем, что выбран для адреса подключения.

Другие блоки страницы приложения

Блок	Что в нём
«Теги»	Пары «ключ — значение»
«Интеграции»	Интеграции типов HTTP, MQTT и ThingsBoard.io
«Кодек»	JS-скрипт кодека. Проверка: введите hex-payload и нажмите «RUN», результат появится в «Result»
«Состояние сети»	Графики «Активность узлов» и «Статистика по трафику»
«Данные»	Таблица пакетов приложения

На странице существующего приложения в боковом меню под пунктом «Приложения» есть ссылки «Websocket» и «Данные»: они переходят к блоку «WebSocket приложения» и к таблице данных. На странице добавления этих ссылок нет.

1. Теги — пары «ключ — значение».
2. Интеграции — карточки HTTP, MQTT и ThingsBoard.io с кнопками «Edit» (изменить) и «Удалить»; надпись «Edit» в русском интерфейсе не переведена.
3. JS — скрипт кодека в блоке «Кодек».
4. Поле hex-payload и кнопка RUN — проверка кодека.
5. Result — результат проверки.
6. Ссылки Websocket и Данные в боковом меню — переход к блоку «WebSocket приложения» и к таблице данных.

Права пользователей на приложения

Можно ли менять существующее приложение, определяют права на само приложение, а не группы пользователя. Владельцу доступно всё. Остальным нужно право просмотра или изменения на это приложение. Без права изменения поля доступны только для чтения, а кнопок сохранения нет.

Выдать или отозвать права:

1. В списке отметьте приложения, выберите действие «Права» и нажмите «Выполнить».
2. В окне «Назначение прав» выберите «Пользователь» и «Права» (по умолчанию отмечено «Отозвать»).
3. Нажмите «Ок».
4. Подтвердите окно «Будут назначены следующие права для выбранных объектов» кнопкой «Ок». Итог — сообщение «Права успешно назначены».

Значение «Права»	Что получает пользователь
«Отозвать»	Права просмотра и изменения снимаются
«Просмотр»	Право просмотра; право изменения снимается
«Изменение»	Права просмотра и изменения

Пользователь, кроме суперпользователя, может выдавать права только своим дочерним учётным записям и только на приложения, которыми владеет сам. Для остальных отмеченных приложений сервер вернёт «Permission denied», а на свои приложения права всё равно назначит. Понятного сообщения о том, какие приложения отклонены, веб-интерфейс в этом случае не показывает.

Удаление приложения

1. В списке отметьте приложения, выберите действие «Удалить» и нажмите «Выполнить».
2. Подтвердите вопрос «Вы действительно хотите удалить приложения» — под ним перечислены App ID выбранных приложений.
3. Если удалены все отмеченные приложения, появится сообщение «Приложения удалены». Если хотя бы одно удалить нельзя (нет права), окно ожидания закроется без сообщения и список не обновится — обновите страницу и проверьте результат.

Приложение, которым пользователь не владеет, сервер не удаляет и возвращает «Permission denied»: через веб-интерфейс выдаются только права просмотра и изменения, права удаления среди них нет. Суперпользователь может удалить любое приложение. Остальные отмеченные приложения сервер удаляет и в этом случае.

Приложение не стирается из базы: сервер помечает его неактивным и записывает дату отключения, и приложение пропадает из списка. Вместе с ним:

• устройства приложения тоже помечаются неактивными — те, которые пользователь вправе удалять;
• все токены приложения отзываются;
• из поля «Доступные приложения» других приложений пропадают ссылки на него.

Внимание

Удаление в веб-интерфейсе отключает и устройства приложения. Команда WebSocket API delete_application_req устройства не удаляет.

Что важно знать

• Приложение, созданное в веб-интерфейсе, токенов не имеет: без токена к WebSocket API не подключиться. Добавьте токен на странице приложения.
• Очистить поле «Доступные приложения» целиком через веб-интерфейс нельзя: сервер пропускает пустой список и оставляет прежние связи. Убрать часть приложений, оставив хотя бы одно, можно, но кнопки сохранения включатся, только если изменить и другое поле, например «Имя».
• Лимиты соединений и подписок срабатывают на единицу позже, чем следует из названий полей: при «Кол-во клиентов, до» = 2 открываются три соединения, при «Кол-во потребителей, до» = 1 подписываются два.
• Ссылка «Выбрать все (N)» без текста в поиске действует только на строки текущей страницы.
• В выборе «Доступных приложений» — только 50 последних созданных приложений. Если приложений больше, более старое туда не попадёт, даже если ввести его имя.
• Инструменты из блока «WebSocket приложения» открываются с первым токеном таблицы, а не с выбранным для адреса подключения.
• Удаление в веб-интерфейсе отключает устройства приложения, отзывает его токены и убирает ссылки на него из других приложений.

См. также

• Общие понятия — токены и уровни доступа в WebSocket API.
• Подключение — адрес, проверка токена, ошибки при подключении.
• Подписаться на данные в реальном времени — подписка, автоподписка, лимит подписок.
• Создать приложение — создание приложения через WebSocket API.
• Удалить приложение — удаление приложения через WebSocket API.