Skip to main content

Подключение

Клиент открывает WebSocket-соединение по адресу ниже и передаёт идентификатор приложения и токен в строке запроса. Сервер принимает WebSocket-соединение сразу, а app_id и токен проверяет уже после этого. Результат проверки приходит первым сообщением connected: со status: 1 можно отправлять команды, со status: 2 сервер закрывает соединение.

wss://kz1.orion-m2m.online/ws/v2/?app_id=APP_ID&token=APP_KEY
ПараметрОписание
app_idИдентификатор приложения (AppID), 8 hex-символов
tokenТокен приложения, 22 символа: латинские буквы и цифры. От уровня токена зависит, какие команды доступны и какие устройства видны, — см. раздел «Доступ» на странице каждой команды

Сервер принимает подключение, если:

  • токен принадлежит приложению с этим app_id и не отозван;
  • приложение активно;
  • учётная запись владельца приложения активна;
  • у приложения не превышен лимит одновременных соединений.
Текущая версия ONS

uuid в connected — строка из 32 hex-символов, а не uuid64, как указано в описании v0.17. Сообщение die_connection_close из описания v0.17 сервер не отправляет: соединение с истёкшим тайм-аутом закрывается без сообщения, см. «Поддержание соединения».

Сообщение connected​

ПолеТипОписание
cmdstringconnected
statusuint81 — подключение принято, 2 — отказ
uuidstringИдентификатор соединения, 32 hex-символа. По нему соединение находят в connections_list и отключают командой connection_kill. Только при status = 1
api_versionstringВерсия протокола, сейчас 0.17. Только при status = 1
clients_countuint16Сколько соединений приложения открыто, считая это. Отсутствует при ошибке 1
consumer_countuint16Сколько соединений приложения подписано на данные. Автоподписка этого соединения сюда ещё не входит. Отсутствует при ошибке 1
error_code, error_textuint8, stringТолько при отказе, см. ниже

Подключение принято:

{
    "cmd": "connected",
    "status": 1,
    "clients_count": 1,
    "consumer_count": 0,
    "uuid": "80f0769cae484a4ea7a22a023f2f6379",
    "api_version": "0.17"
}

Неверный app_id или токен:

{
    "cmd": "connected",
    "status": 2,
    "error_code": 1,
    "error_text": "Auth error"
}

Ошибки​

error_codeerror_textЧто случилось
1Auth errorНе передан app_id или token, токен не принадлежит этому приложению или отозван, приложение отключено, учётная запись владельца неактивна
2Clients count limit reachedУ приложения открыто максимальное число соединений. Посмотрите их командой connections_list и закройте лишние

После отказа сервер отправляет кадр Close без кода и закрывает соединение. HTTP-рукопожатие WebSocket при этом проходит успешно: об отказе клиент узнаёт только из connected.

После подключения​

  1. Дождитесь connected со status: 1. Команды, отправленные раньше, сервер игнорирует и не отвечает на них. Исключение — сообщение, которое не разбирается как JSON: на него сразу приходит json_parse_error.
  2. Если в настройках приложения включена автоподписка, сразу после connected сервер подпишет соединение на данные и пришлёт consume_resp без operation_id. Иначе подпишитесь сами: consume_req.
  3. Отправляйте ping_req с интервалом меньше тайм-аута.

Поддержание соединения​

Сервер закрывает соединение, если клиент не присылает ping_req дольше тайм-аута. Тайм-аут по умолчанию — 300 секунд, его можно изменить для текущего соединения командой set_alive_timeout.

  • Таймер сбрасывает только команда ping_req. Другие команды и кадры ping протокола WebSocket его не сбрасывают.
  • Отсчёт начинается с момента подключения.
  • Сервер проверяет тайм-аут раз в 30 секунд, поэтому соединение закрывается в пределах 30 секунд после истечения тайм-аута.
  • Соединение закрывается без сообщения и без кадра Close: клиент видит обрыв, например код 1006 в браузерном WebSocket.

Когда сервер закрывает соединение​

ПричинаКак выглядит для клиента
Отказ при подключении, ошибки 1 и 2Сообщение connected со status: 2, затем кадр Close без кода
Истёк тайм-аут: не было ping_reqОбрыв без сообщения и без кадра Close
Другой клиент отключил соединение командой connection_killОбрыв без сообщения и без кадра Close

Подписка на данные действует, пока открыто соединение. Пока клиент отключён, данные получают другие подписанные соединения приложения, а если их нет — сервер копит данные в очереди приложения. Переподключитесь и подпишитесь снова: накопленное придёт сообщениями realtime_data.

См. также​