Общие понятия

Правила, общие для всех команд WebSocket API. На страницах команд они не повторяются.

Сообщения

Клиент и сервер обмениваются текстовыми сообщениями WebSocket, каждое — один JSON-объект. Поле cmd задаёт команду. Имена команд в запросах обычно оканчиваются на _req, в ответах — на _resp. Есть исключения: например, connections_list и connection_kill пишутся без суффикса, а на set_alive_timeout сервер отвечает alive_timeout_resp. Точные имена — на страницах команд.

Кроме ответов, сервер присылает сообщения сам:

• connected — сразу после подключения, см. Подключение;
• realtime_data — данные устройств, если соединение подписано, см. consume_req;
• downlink_status — статусы отправленных кадров, см. Отправка данных на устройство.
• consume_resp — сразу после connected, если в настройках приложения включена автоподписка.

Если сервер не смог разобрать запрос, он присылает служебное сообщение — см. Служебные сообщения сервера.

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

К WebSocket API подключаются с идентификатором приложения (APP_ID) и одним из токенов этого приложения. У каждого токена свой уровень доступа: низкий или высокий. Токены приложения перечислены на его странице в веб-интерфейсе ONS.

	Низкий уровень	Высокий уровень
Какие устройства видны	Устройства своего приложения и приложений, которые открыли ему доступ к своим данным	Все устройства владельца приложения
Управление приложениями, устройствами, multicast-группами	Нет	Да
Данные устройств, отправка downlink, история	Да	Да

У отдельных команд правило другое — оно указано в строке «Доступ» на странице команды. Например, downlink_data_req и set_device_coordinates_req с токеном любого уровня работают с устройствами своего приложения и приложений, которые открыли ему доступ.

Только с токеном высокого уровня работают команды:

• приложения: get_applications_req, create_application_req, delete_application_req;
• устройства: create_device_req, update_device_req, delete_device_req;
• multicast-группы: просмотр, создание, изменение, удаление и состав группы;
• downlink_purge_req.

С токеном низкого уровня такие команды возвращают status: 2 и error_code: 1. Поток данных realtime_data от уровня токена не зависит: приходят данные своего приложения и приложений, которые открыли ему доступ.

operation_id

Необязательное поле запроса: произвольная строка, которую сервер возвращает в ответе без изменений. По нему сопоставляют ответ с запросом — ответы приходят не обязательно в порядке запросов. Если поле не передано, в ответе будет пустая строка.

• Передавайте строку. В некоторых командах, например downlink_data_req, число вместо строки приводит к ошибке 3.
• operation_id нет в сообщениях, которые сервер присылает сам (connected, realtime_data, downlink_status), в ответах на ping_req и set_alive_timeout, а также в служебных сообщениях json_parse_error и invalid_req.

status, error_code, error_text

Поле	Значение
status	1 — успех, 2 — ошибка
error_code	Код ошибки, только при status: 2. Нумерация своя у каждой команды — смотрите таблицу «Ошибки» на её странице
error_text	Текст ошибки на английском. Есть не у всех кодов

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

• 0 — внутренняя ошибка сервера или значение, которое отклонила база данных;
• 1 — нет доступа: команде нужен токен высокого уровня;
• 3 — неверные данные в запросе: не тот формат поля, недопустимое значение.

Исключения:

• get_data_req и get_downlink_data_req отвечают двумя сообщениями: status: 1 — запрос принят, status: 3 — данные;
• в успешном ответе на downlink_ack_req поля status нет;
• поля status нет в ответе на ping_req, в служебных сообщениях и в сообщениях, которые сервер присылает сам, кроме connected.

Форматы полей

Поле	Формат
devEui, application_eui, multicast_eui	16 hex-символов, например 6F1E570FFE14DBFC
devAddr, multicast_addr	8 hex-символов
data	Полезная нагрузка — hex-строка
Ключи (app_key, nwks_key, apps_key)	32 hex-символа
Даты в запросах	YYYY-MM-DD HH:MM:SS+HHMM — всегда указывайте часовой пояс
Даты в ответах	UTC: в ответах из базы — YYYY-MM-DD HH:MM:SS+0000, в realtime_data и статусах — ISO 8601

Hex-значения передавайте заглавными буквами: часть команд сравнивает их с учётом регистра. Коды регионов (частотных планов) — на странице create_device_req.

См. также

• Быстрый старт — подключиться и получить первые данные.
• Подключение — адрес, проверка токена, поддержание соединения.