get
Чтобы получить загруженные данные о событиях из сессии, используйте метод events/get.
Перед вызовом метода загрузите события в сессию с помощью events/load.
Если вы передаете параметр selector в events/load и получаете нужные события в объекте selector ответа, метод events/get не требуется.
Endpoint
Используйте метод events/get со следующими форматами селектора.
Получение событий с помощью селектора типа
Используйте селектор type, чтобы получить события указанного детектора за период от timeFrom до timeTo.
svc=events/get¶ms={
"selector": {
"type": <text>,
"timeFrom": <uint>,
"timeTo": <uint>,
"detalization": <uint>
}
}
Получение событий с помощью селектора выражения
Используйте селектор expr, чтобы получить события, выбранные по выражению. Выражение может выбирать интервалы загруженных детекторов, удовлетворяющие условию, явно заданным интервалам времени или и тому, и другому. Параметры timeFrom и timeTo ограничивают период, из которого выбираются события.
svc=events/get¶ms={
"selector": {
"expr": <text>,
"timeFrom": <uint>,
"timeTo": <uint>,
"detalization": <uint>
}
}
Например, trips{s>100} выбирает события поездок, в которых скорость больше 100. Синтаксис выражений см. в разделе Интервалы по выражению.
Получение событий с помощью селектора индекса
Используйте массив селекторов, чтобы запросить диапазон событий по индексу. Чтобы определить индекс конкретного события, получите события детектора по типу, затем используйте индекс события в возвращённом массиве. Индексация начинается с 0.
svc=events/get¶ms={
"selector": [
{
"type": <text>,
"filter1": <long>,
"indexFrom": <uint>,
"indexTo": <uint>,
"detalization": <uint>
},
...
]
}
Параметры
| Параметр | Где используется | Описание |
|---|---|---|
selector |
Все форматы селектора | Обязательный. Определяет события, которые нужно вернуть. |
type |
Селектор типа, селектор индекса | Обязательный. Имя типа детектора событий, загруженного в сессию. В селекторе типа используйте *, чтобы вернуть события всех загруженных детекторов. В селекторе индекса укажите имя одного детектора. |
expr |
Селектор выражения | Обязательный вместо type. Выражение для выбора интервалов за указанный период. См. ниже. |
timeFrom |
Селектор типа, селектор выражения | Обязательный. Начало периода, UNIX-время. |
timeTo |
Селектор типа, селектор выражения | Обязательный. Конец периода, UNIX-время. |
detalization |
Все форматы селектора | Обязательный. Флаги состава ответа. См. флаги. |
indexFrom |
Селектор индекса | Обязательный. Индекс первого запрашиваемого события. |
indexTo |
Селектор индекса | Обязательный. Индекс последнего запрашиваемого события. |
filter1 |
Селектор индекса | Обязательный. ID, используемый как ключ массива событий выбранного детектора. См. ID, зависящие от детектора в events/check_updates. |
Детектор событий
eco_drivingнедоступен в Wialon Local.
Флаги
| Флаг | Описание |
|---|---|
0x1 |
Основные данные события: позиции и время начала и окончания, а также служебные флаги событий. |
0x2 |
Данные, зависящие от типа детектора. |
0x4 |
Параметры сообщения, связанного с событием. |
0x8 |
Дополнительные данные, если они доступны: track для trips и speedings, data для событий мгновенных и дифференциальных датчиков. |
0x10 |
Подробные данные сообщений для поддерживаемых детекторов. |
0x20 |
Отформатированные значения детектора. |
0x40 |
Группировать результаты селектора выражения expr по интервалам их пересечения. |
0x80 |
Итоговые расчёты для результатов селектора выражения. |
0x100 |
Включить расширенные данные событий. |
Интервалы по выражению
Чтобы выбрать интервалы в периоде от timeFrom до timeTo, укажите выражение в параметре "expr":<text> вместо параметра "type":<text>. Выражение может ссылаться на загруженные события детекторов, явно заданные интервалы времени или их сочетание. Можно использовать следующие форматы выражений:
| Оператор | Описание | Пример |
|---|---|---|
* |
Выбирает весь запрошенный период. | * |
{} |
Выбор интервалов детектора, удовлетворяющих условию. | trips{s>100} |
- |
Пользовательский интервал в формате начало-конец, UNIX-время. | 1451953325-1451953525 |
| |
Объединяет интервалы или выражения. | (1615849200-1615935599|1615935601-1616022000) |
& |
Возвращает пересечение двух выражений. | trips[0]&1451953325-1451953525 |
~ |
Исключает интервалы из запрошенного периода. | ~1451953325-1451953525 |
() |
Группирует выражение. | (trips[0]|1451953325-1451953525) |
[] |
Выбирает ID, зависящий от детектора. Если ID не указан, используется первый загруженный ID детектора. | sensors[3] |
Например, следующее выражение возвращает события детектора trips, который использует фиксированный ID 0, и детектора sensors с ID 8, которые пересекаются с одним или обоими из двух пользовательских интервалов:
(trips[0]|sensors[8])&(1784550000-1784560000|1784570000-1784580000)
Ответ
При успешном выполнении запроса ответ содержит результаты запрошенного детектора. В противном случае возвращается код ошибки.
Большинство детекторов возвращают массивы событий с ключами в виде ID, зависящего от детектора (например, ID датчика, ID водителя или ID критерия качества вождения). Список ID, используемых каждым детектором, см. в разделе ID, зависящие от детектора. Детекторы trips и counters возвращают данные напрямую, без группировки по ID, а speedings всегда использует единственный ID 0.
Если не указано иное, значения в ответе (датчики, топливо, расстояние, скорость, высота и пробег) приводятся к системе мер, заданной при загрузке событий методом events/load. Значения в секундах, байтах, КиБ, км/ч и UNIX-время не преобразуются.
Флаг 0x1
Возвращает основные данные события.
"<type_name>": {
"<detector_specific_id>": [
{
"from": {
"t": <uint>, /* время начала интервала события (UNIX-время) */
"y": <double>,/* широта */
"x": <double> /* долгота */
},
"to": {
"t": <uint>, /* время окончания интервала события (UNIX-время) */
"y": <double>,/* широта */
"x": <double> /* долгота */
},
"m": <uint>, /* время последнего обработанного сообщения */
"f": <uint> /* служебные флаги событий */
},
...
]
}
Флаг 0x2
Возвращает данные, зависящие от типа детектора. В следующих примерах показан объект события, который возвращается в массиве с ключом в виде ID, зависящего от детектора.
Детекторы датчиков
Детектор ignition возвращает следующую структуру:
"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-время */
"latDiff": <double>, /* широта этого сообщения */
"lonDiff": <double> /* долгота этого сообщения */
}
}
Детекторы батареи
Детектор battery_level возвращает обработанное и исходное значения уровня заряда батареи.
"battery_level": {
"<sensor_id>": {
"value": <double>, /* последний рассчитанный уровень заряда */
"raw_value": <double> /* последнее исходное значение датчика */
}
}
Детектор charge возвращает следующую структуру:
"charge": {
"<sensor_id>": {
"charge": <double>, /* изменение объёма заряда */
"timeDiff": <uint>, /* время сообщения с максимальной разницей объёма, UNIX-время */
"latDiff": <double>, /* широта этого сообщения */
"lonDiff": <double> /* долгота этого сообщения */
}
}
Детектор ev возвращает структуру battery_level или charge в зависимости от события.
resource_drivers
Детектор группирует интервалы назначений по ID водителя и возвращает каждый интервал отдельным объектом. Текущее состояние также возвращается, если запрошено текущее событие. Текущее состояние может иметь state 1, пока водитель ещё назначен. В этом случае время окончания в ответе 0x1 — это время последнего обновления, а не фактическое время окончания назначения. Оно также может иметь state 0 после снятия водителя. В этом случае объект to показывает последнее обработанное сообщение, а не ещё одно снятие; используйте историю событий, чтобы получить фактическое время снятия.
"resource_drivers": {
"<driver_id>": [
{
"state": <uint>, /* состояние водителя: 0 — снят, 1 — назначен */
"aflags": <uint>, /* флаги назначения */
"unit_id": <long>, /* ID объекта, на который назначен водитель, с которого водитель был снят, или 0 */
"propitem_cr_time": <uint>, /* время создания водителя, UNIX-время */
"switched_to": <long>, /* ID объекта, на который был переключён водитель; возвращается только когда водитель был назначен на другой объект без снятия с этого */
"real_time_from": <uint>, /* фактическое время начала назначения, UNIX-время */
"validate_sensor_id": <uint> /* ID датчика, используемого для подтверждения автоматического назначения и следующего за ним снятия; 0, если подтверждение не используется */
}
]
}
Используйте propitem_cr_time, чтобы проверить, является ли водитель текущим или был удалён и создан заново с тем же ID.
Значение from.t в ответе 0x1 — это начало возвращаемого интервала события. Значение real_time_from — фактическое время начала непрерывного назначения. Эти значения могут отличаться, когда одно назначение представлено несколькими интервалами событий, например если длительное назначение разделено или повторное ручное назначение начинает новый интервал. Если назначение не разделено, real_time_from обычно совпадает с from.t.
Служебные флаги событий базового события, включая флаги приватных позиций, тихих событий, несеквенцированных событий и пересчитанных событий, возвращаются в поле f с флагом 0x1, а не в объекте данных, зависящих от детектора.
Детектор не возвращает отдельный маркер для назначения, помеченного как ложное. Такие действия хранятся отдельно, а соответствующие автоматические действия назначения исключаются при пересчёте событий.
Ручные назначения, снятия и действия игнорирования, влияющие на события resource_drivers, регистрируются, просматриваются и удаляются с помощью resource/driver_actions_register, resource/driver_actions_list и resource/driver_actions_cleanup.
Поле aflags описывает, как назначение началось и завершилось. Завершённый интервал обычно содержит один флаг для начала и один для окончания, поэтому флаги объединяются.
| Флаг | Описание |
|---|---|
0x1 |
Назначение завершилось, потому что водитель был переключён на другой объект. ID этого объекта возвращается в switched_to. |
0x2 |
Назначение началось, потому что водитель был переключён с другого объекта. Это завершило предыдущее назначение на том объекте. |
0x4 |
Назначение было начато вручную. |
0x8 |
Назначение было завершено вручную. |
0x10 |
Назначение начинается с state 0, потому что другой исключающий водитель был назначен на тот же объект. |
0x20 |
Назначение было завершено, потому что другой исключающий водитель был назначен на тот же объект. |
Детектор
resource_driversдоступен только для ресурсов. Чтобы загрузить его события, передайте ID ресурса в параметреitemIdметода events/load.
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>, /* тип критерия качества вождения */
"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 не включается, если параметры отсутствуют.
Значения параметров могут быть строками, целыми числами, длинными целыми числами или числами с плавающей точкой.
"<type_name>": {
"<detector_specific_id>": [
{
"p": { /* параметры сообщения */
"<parameter_name>": <any>
}
}
]
}
Флаг 0x8
Возвращает дополнительные данные, если они доступны. Для trips и speedings поле track содержит закодированный маршрут в нотации Google. Для событий мгновенных и дифференциальных датчиков поле data содержит дополнительные данные события.
{
"trips": {
"0": [
{
"track": "wspnGgvcv@??oey@kwl@~dtBkeRwjzF??~ja@_qo]??g~g^????????????~bV???????"
}
]
}
}
Флаг 0x10
Возвращает подробные сообщения для детекторов, которые их поддерживают. Массив msgs возвращается, когда подробные данные сообщений доступны.
Для мгновенных и дифференциальных датчиков (типы 2 и 3), кроме датчиков уровня топлива:
"sensors": {
"<sensor_id>": {
"msgs": [
{
"tm": <uint>, /* время сообщения (UNIX-время) */
"v": <double> /* значение */
},
...
]
},
...
}
Для датчиков уровня топлива:
"lls": {
"<sensor_id>": {
"msgs": [
{
"tm": <uint>, /* время сообщения (UNIX-время) */
"v": <double>, /* значение */
"rv": <double> /* исходное значение */
},
...
]
}
},
...
Для поездок массив msgs содержит подробные сообщения из интервала события:
"trips": {
"msgs": [
{
"tm": <uint>, /* время сообщения (UNIX-время) */
"x": <double>, /* долгота */
"y": <double>, /* широта */
"c": <uint>, /* курс */
"z": <int>, /* высота */
"s": <uint>, /* скорость */
"m": <double>, /* пробег */
"pf": <uint> /* флаги позиции; включается, если не равно 0 */
},
...
]
}
Для приватных позиций значения x, y и c возвращаются как 0.
Для событий назначения водителей возвращается следующий ответ:
"resource_drivers": {
"<driver_id>": [
{
"msgs": [
{
"tm": <uint> /* время повторного назначения, UNIX-время */
},
...
]
}
]
}
Флаг 0x20
Возвращает отформатированные значения. В разделах ниже описан объект format каждого детектора.
Детекторы eco_driving, health_check и resource_drivers не возвращают объект format для этого флага.
Детекторы датчиков
Детектор ignition возвращает следующий объект format:
"ignition": {
"<sensor_id>": {
"format": {
"value": <text>, /* отформатированное значение, обычно «Вкл.» или «Выкл.» */
"custom_value": <text> /* пользовательское отформатированное значение */
}
}
}
Детектор sensors возвращает следующий объект format:
"sensors": {
"<sensor_id>": {
"format": {
"value": <text>, /* отформатированное значение; зависит от типа и формата датчика */
"custom_value": <text> /* пользовательское отформатированное значение */
}
}
}
Детекторы уровня топлива
Детекторы lls, filling, theft и fuel_level возвращают следующий объект format:
"lls": {
"<sensor_id>": {
"format": {
"value": <text>, /* отформатированное значение; зависит от типа и формата датчика */
"raw_value": <text>,/* отформатированное исходное значение */
"filled": <text>, /* объём заправленного топлива */
"theft": <text>, /* объём слитого топлива */
"custom_value": <text> /* пользовательское отформатированное значение */
}
}
}
Детекторы батареи
Детектор 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-трафика, в КиБ */
}
}
Флаг 0x40
Для селекторов выражения возвращает массив, сгруппированный по интервалам, полученным при вычислении выражения. См. Интервалы по выражению.
[
{
"tf": <uint>, /* начало интервала выражения (UNIX-время) */
"tt": <uint>, /* конец интервала выражения (UNIX-время) */
"d": { /* результаты детектора для интервала выражения */
"<type_name>": {
"<sensor_id>": [
{ }
]
}
}
}
]
Флаг 0x80
Для селекторов выражения возвращает итоговые значения, рассчитанные на основе событий, выбранных выражением, для каждого детектора и ID, зависящего от детектора. Без флага 0x40 результаты возвращаются в объекте summary верхнего уровня. Если также указан 0x40, объект d каждого интервала содержит собственный объект summary. Этот флаг игнорируется для селекторов типа и индекса.
Поля итоговых данных зависят от детектора:
tripsиspeedings: количество и общая длительность событий, количество сообщений и статистика скорости;tripsтакже возвращает общее расстояние.- Мгновенные и дифференциальные
sensors: количество и общее значение событий или начальные и конечные значения. lls,filling,theftиfuel_level: общие заправки и сливы, начальный и конечный уровень топлива и расход.battery_level,chargeиev: начальный и конечный уровни, расход или общая зарядка, в зависимости от детектора.counters: начальные и конечные моточасы, пробег и GPRS-трафик.- Другие детекторы, включая
ignition,health_check,eco_drivingи датчики-переключатели или аналоговыеsensors: количество и общая длительность событий.
Например, итоговые данные для speedings могут содержать:
{
"summary": {
"speedings": {
"0": {
"countIvals": <uint>, /* количество событий превышения скорости */
"sumSeconds": <uint>, /* общая длительность событий, в секундах */
"countMessages": <uint>, /* количество сообщений в событиях */
"avgSpeed": <uint>, /* средняя скорость */
"maxSpeed": <uint>, /* максимальная скорость */
"minSpeed": <uint> /* минимальная скорость */
}
}
}
}
Коды ошибок
| Код ошибки | Описание |
|---|---|
| 1 | Недействительный или устаревший SID запроса. |
| 4 | Ошибка проверки параметров. |
| 7 | Сервис событий недоступен. |