check_updates
Чтобы получить обновления событий для всех элементов, добавленных в сессию, используйте метод events/check_updates. Элементами могут быть объекты или ресурсы.
Перед вызовом этого метода добавьте элементы в сессию и установите детекторы для отслеживания с помощью events/update_items. Если вы отслеживаете только объекты, можно также использовать events/update_units.
Если параметр
evt_flags, установленный в events/update_items или events/update_units, включает флаг0x200, обновления возвращаются в полеunits_updateметода avl_evts. В этом случаеevents/check_updatesвозвращает{}.
Конечная точка
svc=events/check_updates¶ms={
"lang": <text>,
"measure": <uint>,
"detalization": <uint>
}
Параметры
Все параметры необязательны.
| Параметр | Описание | Значение по умолчанию |
|---|---|---|
lang |
Язык (двухсимвольный код). | en |
measure |
Система измерения:
|
0 |
detalization |
Флаги состава ответа (см. ниже). Должны быть указаны в десятичном формате. | 7 |
Флаги состава ответа
| Флаг | Описание |
|---|---|
| 0x1 | Основные данные события: позиции и время начала и окончания, а также служебные флаги событий. |
| 0x2 | Данные, зависящие от типа детектора. |
| 0x4 | Параметры сообщения, связанного с событием. |
| 0x8 | Расширенные подробные данные детектора для поддерживаемых детекторов. |
| 0x10 | Подробные данные сообщений для поддерживаемых детекторов. |
| 0x20 | Отформатированные значения детектора. |
Тип датчика
| Значение type | Описание | Регистрация событий |
|---|---|---|
| 1 | Датчики-переключатели:
|
События активны, пока значение ненулевое. |
| 2 | Мгновенные датчики:
|
События активны, пока значение ненулевое. |
| 3 | Дифференциальные датчики:
|
События активны, пока рассчитанный счётчик ненулевой. |
| 4 | Аналоговые датчики:
|
Предоставляет только текущее состояние датчика; детектор sensors не регистрирует интервальные события для этого типа. |
Таблица выше не включает датчики уровня топлива и уровня заряда батареи. Система обрабатывает их данные с помощью отдельных детекторов: lls, fuel_level, filling и theft для датчиков уровня топлива, а также battery_level, charge и ev для датчиков уровня заряда батареи. Это не касается импульсного датчика уровня топлива: он относится к аналоговым датчикам (тип 4). Полный список детекторов см. в разделе Типы детекторов событий.
Ответ
Ответ сгруппирован по ID элемента. Для каждого элемента ответ содержит массив объектов детекторов:
{
"<item_id_1>": [
{ "<detector_name>": { ... } },
{ "<detector_name>": { ... } },
...
],
"<item_id_2>": [ ... ]
}
Каждый вызов возвращает обновления событий с момента предыдущего вызова events/check_updates в той же сессии. Метод возвращает пустой объект, если новых обновлений нет.
Если не указано иное, значения в ответе (датчики, топливо, расстояние, скорость, высота и пробег) используют систему измерения из параметра measure. Значения в секундах, байтах, КиБ, км/ч и UNIX time не преобразуются.
Структура каждого объекта детектора зависит от включённых флагов состава ответа. Комбинируйте флаги в параметре detalization по мере необходимости. В разделах ниже описывается каждый флаг отдельно.
Флаг 0x1
Возвращает основные данные для каждого события. Структура ответа зависит от детектора. Детекторы ignition, sensors, lls, filling, theft, fuel_level, ev, charge и battery_level используют ID датчика объекта в качестве ключа объекта <detector_specific_id>. Детектор eco_driving использует ID критерия качества вождения, health_check использует ID инцидента, resource_drivers использует ID водителя, а speedings использует 0. Детекторы, такие как trips и counters, возвращают данные напрямую, без группировки.
Детектор
eco_drivingнедоступен в Wialon Local.
Для детекторов, которые группируют данные по ID, структура следующая:
{
"<detector_name>": {
"<detector_specific_id>": {
"from": {
"t": <uint>, /* время (UNIX time) */
"y": <double>, /* широта */
"x": <double> /* долгота */
},
"to": {
"t": <uint>, /* время (UNIX time) */
"y": <double>, /* широта */
"x": <double> /* долгота */
},
"m": <uint>, /* время последнего сообщения, связанного с событием */
"f": <uint> /* служебные флаги событий */
}
}
}
Для детекторов, которые возвращают данные напрямую, таких как trips и counters, уровень <detector_specific_id> не включается:
{
"<detector_name>": {
"from": {
"t": <uint>, /* время (UNIX time) */
"y": <double>, /* широта */
"x": <double> /* долгота */
},
"to": {
"t": <uint>, /* время (UNIX time) */
"y": <double>, /* широта */
"x": <double> /* долгота */
},
"m": <uint>, /* время последнего сообщения, связанного с событием */
"f": <uint> /* служебные флаги событий */
}
}
Для приватной начальной или конечной позиции, например, когда частный режим скрывает местоположение объекта, значения x и y возвращаются как 0.
Флаг 0x2
Возвращает данные, зависящие от детектора. Структура зависит от детектора.
Детекторы датчиков
Для ignition и sensors структура, возвращаемая для каждого датчика, зависит от типа датчика. Поле type показывает тип датчика.
"ignition": {
"<sensor_id>": {
"state": <double>, /* состояние: 0 — выключен, 1 — включен */
"type": 1, /* тип датчика: переключатель */
"hours": <uint>, /* моточасы за всю историю, в секундах */
"switches": <uint>, /* количество переключений за всю историю */
"value": <double> /* последнее значение датчика */
}
}
Возможные объекты для sensors:
"sensors": {
"<sensor_id1>": {
"state": <double>, /* состояние: 0 — выключен, 1 — включен */
"type": 1, /* тип датчика: переключатель */
"hours": <uint>, /* моточасы за всю историю, в секундах */
"switches": <uint>, /* количество переключений за всю историю */
"value": <double> /* последнее значение */
},
"<sensor_id2>": {
"type": 2, /* тип датчика: мгновенный датчик */
"counter": <uint>, /* число последовательных сообщений в событии */
"summary": <double>, /* сумма значений в событии */
"total_counter": <uint>, /* общее число сообщений за всю историю */
"total_summary": <double>, /* общая сумма значений за всю историю */
"value": <double> /* последнее значение; -348201.3876 означает, что значение неизвестно */
},
"<sensor_id3>": {
"type": 3, /* тип датчика: дифференциальный датчик */
"counter": <double>, /* сумма значений в событии */
"total_counter": <double>, /* сумма значений за всю историю */
"value": <double> /* последнее значение; -348201.3876 означает, что значение неизвестно */
},
"<sensor_id4>": {
"type": 4, /* тип датчика: аналоговый датчик */
"value": <double> /* последнее значение; -348201.3876 означает, что значение неизвестно */
}
}
Детекторы уровня топлива
Детекторы lls, filling, theft и fuel_level возвращают одну и ту же структуру.
"lls": {
"<sensor_id>": {
"value": <double>, /* последний рассчитанный уровень топлива */
"raw_value": <double>, /* последнее исходное значение датчика */
"filled": <double>, /* изменение объёма топлива: положительное — заправка, отрицательное — слив */
"timeDiff": <uint>, /* время сообщения с максимальной разницей объёма, UNIX time */
"latDiff": <double>, /* широта этого сообщения */
"lonDiff": <double> /* долгота этого сообщения */
}
}
Детекторы батареи
Детектор battery_level работает с датчиками уровня заряда батареи и возвращает обработанное и исходное значения текущего уровня заряда батареи.
"battery_level": {
"<sensor_id>": {
"value": <double>, /* последний рассчитанный уровень заряда батареи */
"raw_value": <double> /* последнее исходное значение датчика */
}
}
Детектор charge возвращает следующую структуру:
"charge": {
"<sensor_id>": {
"charge": <double>, /* изменение объёма зарядки */
"timeDiff": <uint>, /* время сообщения с максимальной разницей объёма зарядки, UNIX time */
"latDiff": <double>, /* широта этого сообщения */
"lonDiff": <double> /* долгота этого сообщения */
}
}
Детектор ev объединяет оба типа событий батареи электромобиля. Он возвращает структуру battery_level для событий уровня заряда батареи и структуру charge для событий зарядки. Используйте ev, чтобы получать события уровня заряда батареи и зарядки через один детектор, или используйте battery_level и charge, чтобы получать их отдельно.
resource_drivers
Детектор группирует данные по ID водителя и возвращает текущее состояние назначения.
"resource_drivers": {
"<driver_id>": {
"state": <uint>, /* состояние назначения: 0 — снят, 1 — назначен */
"aflags": <uint>, /* флаги назначения */
"unit_id": <long>, /* ID объекта, на который назначен водитель, с которого водитель снят, или 0 */
"propitem_cr_time": <uint>, /* время создания водителя, UNIX time */
"switched_to": <long>, /* ID объекта, на который был переключен водитель; возвращается только в том случае, если водитель был назначен на другой объект без снятия с этого */
"real_time_from": <uint>, /* фактическое время начала назначения, UNIX time */
"validate_sensor_id": <uint> /* ID датчика, используемого для подтверждения автоматического назначения и следующего за ним снятия; 0, если подтверждение не используется */
}
}
Подробную информацию об этих полях см. в разделе resource_drivers на странице events/get.
Поле aflags может содержать следующие флаги:
| Флаг | Описание |
|---|---|
0x1 |
Назначение завершилось из-за переключения водителя на другой объект. ID этого объекта возвращается в поле switched_to. |
0x2 |
Назначение началось из-за переключения водителя с другого объекта. При этом предыдущее назначение на том объекте завершилось. |
0x4 |
Назначение было начато вручную. |
0x8 |
Назначение было завершено вручную. |
0x10 |
Назначение начинается со state 0, потому что на тот же объект был назначен другой эксклюзивный водитель. |
0x20 |
Назначение завершилось, потому что на тот же объект был назначен другой эксклюзивный водитель. |
trips
Детектор возвращает данные напрямую, без группировки по ID.
"trips": {
"state": <uint>, /* состояние поездки: 0 — стоянка, 1 — поездка, 2 — остановка */
"max_speed": <uint>, /* максимальная скорость во время поездки */
"curr_speed": <uint>, /* текущая скорость */
"avg_speed": <uint>, /* средняя скорость на основе расстояния */
"distance": <uint>, /* GPS-пробег во время поездки */
"odometer": <uint>, /* общее расстояние для всех поездок в истории */
"course": <uint>, /* курс */
"altitude": <uint>, /* высота */
"pos_flags": <uint> /* флаги позиции: 1 — ошибка датчика, 2 — датчик не фиксирует движение */
}
speedings
Детектор использует единственный специфичный для детектора ID 0.
"speedings": {
"0": {
"max_speed": <uint>, /* максимальная скорость во время события */
"last_speed": <uint>, /* скорость в последнем сообщении события */
"limit": <uint> /* ограничение скорости */
}
}
counters
Детектор возвращает данные напрямую, без группировки по ID.
"counters": {
"engine_hours": <uint>, /* счётчик моточасов, в секундах */
"mileage": <uint>, /* счётчик пробега */
"bytes": <uint> /* счётчик GPRS-трафика, в байтах */
}
eco_driving
Детектор группирует данные по ID критерия качества вождения.
"eco_driving": {
"<eco_driving_id>": {
"criterion_type": <text>, /* тип критерия: "acceleration", "brake", "turn", "speeding", "sensor", "harsh", "idling" */
"index": <uint>, /* индекс критерия */
"max_speed": <uint>, /* максимальная скорость, зафиксированная во время нарушения, в км/ч */
"mark": <double> /* штрафные баллы; может включать дробную часть и зависит от настроек критерия и длительности нарушения */
}
}
Детектор
eco_drivingнедоступен в Wialon Local.
health_check
Детектор группирует данные по ID инцидента.
"health_check": {
"<incident_id>": {
"incident_type": <text>, /* тип инцидента диагностики */
"duration": <uint>, /* длительность инцидента, в секундах */
"sensor_id": <uint> /* ID датчика объекта; не включается, если инцидент не связан с датчиком */
}
}
Флаг 0x4
Возвращает доступные параметры сообщения, связанного с событием. Объект p не включается или возвращается как пустой объект, если параметры недоступны.
Если объект возвращается, он использует группировку, описанную для флага 0x1.
"<detector_name>": {
"<detector_specific_id>": {
"p": {
"<parameter_name>": <any>
}
}
}
Для детекторов, которые возвращают данные напрямую, уровень <detector_specific_id> не включается:
"<detector_name>": {
"p": {
"<parameter_name>": <any>
}
}
Флаг 0x8
Возвращает дополнительные подробные данные, если они доступны: track для trips и speedings, data для событий мгновенных и дифференциальных датчиков.
Флаг 0x10
Возвращает подробные сообщения для детекторов, которые их поддерживают. Массив msgs возвращается, когда доступны подробные данные сообщений события.
Для мгновенных и дифференциальных датчиков (типы 2 и 3), кроме датчиков уровня топлива, возвращается следующий ответ:
"sensors": {
"<sensor_id>": {
"msgs": [
{
"tm": <uint>, /* время сообщения, UNIX time */
"v": <double> /* значение */
},
...
]
},
...
}
Значение поля v зависит от типа датчика.
Для датчиков уровня топлива возвращается следующий ответ:
"lls": {
"<sensor_id>": {
"msgs": [
{
"tm": <uint>, /* время сообщения, UNIX time */
"v": <double>, /* рассчитанный уровень топлива */
"rv": <double> /* исходное значение датчика */
},
...
]
},
...
}
Детекторы filling, theft и fuel_level используют ту же структуру подробных сообщений, что и lls, если подробные данные сообщений доступны.
Для поездок возвращается следующий ответ:
"trips": {
"msgs": [
{
"tm": <uint>, /* время сообщения, UNIX time */
"x": <double>, /* долгота */
"y": <double>, /* широта */
"c": <uint>, /* курс */
"z": <uint>, /* высота */
"s": <uint>, /* скорость */
"m": <double>, /* пробег на момент сообщения */
"pf": <uint> /* флаги позиции; не включается, если равно 0 */
},
...
]
}
Если позиция приватная, значения x, y и c возвращаются как 0.
Для превышений скорости возвращается следующий ответ:
"speedings": {
"0": {
"msgs": [
{
"tm": <uint>, /* время сообщения, UNIX time */
"x": <double>,/* долгота */
"y": <double>,/* широта */
"c": <uint>, /* курс */
"s": <uint>, /* скорость */
"l": <uint>, /* ограничение скорости */
"pf": <uint> /* флаги позиции; не включается, если равно 0 */
},
...
]
}
}
Если позиция приватная, значения x, y и c возвращаются как 0.
Для событий назначения водителей возвращается следующий ответ:
"resource_drivers": {
"<driver_id>": {
"msgs": [
{
"tm": <uint> /* время повторного назначения в рамках события, UNIX-время */
},
...
]
}
}
Флаг 0x20
Возвращает отформатированные значения детектора. Вывод зависит от настроек объекта и параметров measure и lang.
Детекторы eco_driving, health_check и resource_drivers не возвращают объект format для этого флага.
Детекторы датчиков
Детекторы ignition и sensors используют следующий объект format:
"<sensor_detector>": {
"<sensor_id>": {
"format": {
"value": <text>, /* отформатированное значение датчика */
"custom_value": <text> /* пользовательское значение датчика, соответствующее value */
}
}
}
Детекторы уровня топлива
Детекторы lls, filling, theft и fuel_level возвращают следующий объект format:
"lls": {
"<sensor_id>": {
"format": {
"value": <text>, /* отформатированный рассчитанный уровень топлива */
"raw_value": <text>, /* отформатированное исходное значение датчика */
"filled": <text>, /* отформатированный объём заправленного топлива; 0, если заправки не было */
"theft": <text>, /* отформатированный объём слитого топлива; 0, если слива не было */
"custom_value": <text> /* пользовательское значение датчика, соответствующее value */
}
}
}
Детекторы батареи
Детектор battery_level возвращает следующий объект format:
"battery_level": {
"<sensor_id>": {
"format": {
"value": <text>, /* отформатированный уровень заряда батареи */
"raw_value": <text>, /* отформатированное исходное значение датчика */
"custom_value": <text> /* пользовательское значение датчика, соответствующее value */
}
}
}
Детектор charge возвращает следующий объект format:
"charge": {
"<sensor_id>": {
"format": {
"charge": <text> /* отформатированный объём зарядки */
}
}
}
Детектор ev возвращает объект format из структуры battery_level для событий уровня заряда батареи и из структуры charge для событий зарядки.
Для датчиков уровня заряда батареи поля value и raw_value объекта format учитывают ключ show_as_percentage в настройках датчика. Если для этого ключп установлено значение 1, а значение battery_capacity больше 0, в этих полях возвращается уровень заряда батареи в процентах от ёмкости, со знаком процента. В противном случае в них возвращается уровень в кВт·ч.
Проценты применяются только к отформатированным значениям флага
0x20. Полеcharge, числовые значения, возвращаемые с флагом 0x2, а также данные в отчётах и уведомлениях всегда указываются в кВт·ч.
trips
Детектор возвращает следующий объект format:
"trips": {
"format": {
"distance": <text>, /* отформатированное расстояние поездки */
"avg_speed": <text> /* отформатированная средняя скорость поездки */
}
}
speedings
Детектор возвращает следующий объект format:
"speedings": {
"0": {
"format": {
"last_speed": <text>, /* отформатированная скорость в последнем сообщении */
"limit": <text>, /* отформатированное ограничение скорости */
"max_speed": <text> /* отформатированная максимальная скорость во время события */
}
}
}
counters
Детектор возвращает следующий объект format:
"counters": {
"format": {
"engine_hours": <text | uint>, /* отформатированные моточасы; целые часы, если форматирование недоступно */
"mileage": <text>, /* отформатированный пробег */
"bytes": <uint> /* GPRS-трафик, в КиБ */
}
}
Коды ошибок
Если запрос не выполнен, возвращается код ошибки.
| Код ошибки | Описание |
|---|---|
| 1 | Неверный или устаревший SID запроса. |
| 4 | Ошибка валидации параметров. |
| 7 | Сервис событий недоступен. |