Справочный центр Wialon

get

Чтобы получить загруженные данные о событиях из сессии, используйте метод events/get.

Перед вызовом метода загрузите события в сессию с помощью events/load.

Если вы передаете параметр selector в events/load и получаете нужные события в объекте selector ответа, метод events/get не требуется.

Endpoint

Используйте метод events/get со следующими форматами селектора.

Получение событий с помощью селектора типа

Используйте селектор type, чтобы получить события указанного детектора за период от timeFrom до timeTo.

Copied!
svc=events/get&params={
  "selector": {
    "type": <text>,
    "timeFrom": <uint>,
    "timeTo": <uint>,
    "detalization": <uint>
  }
}

Получение событий с помощью селектора выражения

Используйте селектор expr, чтобы получить события, выбранные по выражению. Выражение может выбирать интервалы загруженных детекторов, удовлетворяющие условию, явно заданным интервалам времени или и тому, и другому. Параметры timeFrom и timeTo ограничивают период, из которого выбираются события.

Copied!
svc=events/get&params={
  "selector": {
    "expr": <text>,
    "timeFrom": <uint>,
    "timeTo": <uint>,
    "detalization": <uint>
  }
}

Например, trips{s>100} выбирает события поездок, в которых скорость больше 100. Синтаксис выражений см. в разделе Интервалы по выражению.

Получение событий с помощью селектора индекса

Используйте массив селекторов, чтобы запросить диапазон событий по индексу. Чтобы определить индекс конкретного события, получите события детектора по типу, затем используйте индекс события в возвращённом массиве. Индексация начинается с 0.

Copied!
svc=events/get&params={
  "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.

Флаги

Флаг Описание
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, которые пересекаются с одним или обоими из двух пользовательских интервалов:

Copied!
(trips[0]|sensors[8])&(1784550000-1784560000|1784570000-1784580000)

Ответ

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

Большинство детекторов возвращают массивы событий с ключами в виде ID, зависящего от детектора (например, ID датчика, ID водителя или ID критерия качества вождения). Список ID, используемых каждым детектором, см. в разделе ID, зависящие от детектора. Детекторы trips и counters возвращают данные напрямую, без группировки по ID, а speedings всегда использует единственный ID 0.

Если не указано иное, значения в ответе (датчики, топливо, расстояние, скорость, высота и пробег) приводятся к системе мер, заданной при загрузке событий методом events/load. Значения в секундах, байтах, КиБ, км/ч и UNIX-время не преобразуются.

Флаг 0x1

Возвращает основные данные события.

Copied!
"<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 возвращает следующую структуру:

Copied!
"ignition": {
  "<sensor_id>": {
    "state": <double>,  /* состояние: 0 — выключен, 1 — включен */
    "type": 1,          /* тип датчика: переключатель */
    "hours": <uint>,    /* моточасы за всю историю, в секундах */
    "switches": <uint>, /* количество переключений за всю историю */
    "value": <double>   /* последнее значение датчика */
  }
}

Детектор sensors возвращает одну из следующих структур в зависимости от типа датчика:

Copied!
"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 возвращают одну и ту же структуру.

Copied!
"lls": {
  "<sensor_id>": {
    "value": <double>,     /* последний рассчитанный уровень топлива */
    "raw_value": <double>, /* последнее исходное значение уровня топлива */
    "filled": <double>,    /* изменение объёма топлива: положительное — заправка, отрицательное — слив */
    "timeDiff": <uint>,    /* время сообщения с максимальной разницей объёма, UNIX-время */
    "latDiff": <double>,   /* широта этого сообщения */
    "lonDiff": <double>    /* долгота этого сообщения */
  }
}

Детекторы батареи

Детектор battery_level возвращает обработанное и исходное значения уровня заряда батареи.

Copied!
"battery_level": {
  "<sensor_id>": {
    "value": <double>,     /* последний рассчитанный уровень заряда */
    "raw_value": <double>  /* последнее исходное значение датчика */
  }
}

Детектор charge возвращает следующую структуру:

Copied!
"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 показывает последнее обработанное сообщение, а не ещё одно снятие; используйте историю событий, чтобы получить фактическое время снятия.

Copied!
"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 Назначение было завершено, потому что другой исключающий водитель был назначен на тот же объект.

trips

Детектор возвращает данные напрямую, без группировки по ID.

Copied!
"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.

Copied!
"speedings": {
  "0": {
    "max_speed": <uint>,  /* максимальная скорость во время события */
    "last_speed": <uint>, /* скорость в последнем сообщении события */
    "limit": <uint>       /* ограничение скорости, использованное для регистрации события */
  }
}

counters

Детектор возвращает данные напрямую, без группировки по ID.

Copied!
"counters": {
  "engine_hours": <uint>, /* счётчик моточасов, в секундах */
  "mileage": <uint>,      /* счётчик пробега */
  "bytes": <uint>         /* счётчик GPRS-трафика, в байтах */
}

eco_driving

Детектор группирует данные по ID критерия качества вождения.

Copied!
"eco_driving": {
  "<eco_driving_id>": [
    {
      "criterion_type": <text>, /* тип критерия качества вождения */
      "index": <uint>,          /* индекс критерия */
      "max_speed": <uint>,      /* максимальная скорость во время нарушения, км/ч */
      "mark": <double>          /* рассчитанный штраф; может включать дробную часть */
    }
  ]
}

health_check

Детектор группирует данные по ID инцидента.

Copied!
"health_check": {
  "<incident_id>": [
    {
      "incident_type": <text>, /* тип инцидента диагностики */
      "duration": <uint>,      /* длительность инцидента, в секундах */
      "sensor_id": <uint>      /* ID датчика объекта; не включается, если инцидент не связан с датчиком */
    }
  ]
}

Флаг 0x4

Возвращает доступные параметры сообщения, связанного с событием. Объект p не включается, если параметры отсутствуют.

Значения параметров могут быть строками, целыми числами, длинными целыми числами или числами с плавающей точкой.

Copied!
"<type_name>": {
  "<detector_specific_id>": [
    {
      "p": {              /* параметры сообщения */
        "<parameter_name>": <any>
      }
    }
  ]
}

Флаг 0x8

Возвращает дополнительные данные, если они доступны. Для trips и speedings поле track содержит закодированный маршрут в нотации Google. Для событий мгновенных и дифференциальных датчиков поле data содержит дополнительные данные события.

Copied!
{
  "trips": {
    "0": [
      {
        "track": "wspnGgvcv@??oey@kwl@~dtBkeRwjzF??~ja@_qo]??g~g^????????????~bV???????"
      }
    ]
  }
}

Флаг 0x10

Возвращает подробные сообщения для детекторов, которые их поддерживают. Массив msgs возвращается, когда подробные данные сообщений доступны.

Для мгновенных и дифференциальных датчиков (типы 2 и 3), кроме датчиков уровня топлива:

Copied!
"sensors": {
  "<sensor_id>": {
    "msgs": [
      {
        "tm": <uint>,  /* время сообщения (UNIX-время) */
        "v": <double>  /* значение */
      },
      ...
    ]
  },
  ...
}

Для датчиков уровня топлива:

Copied!
"lls": {
  "<sensor_id>": {
    "msgs": [
      {
        "tm": <uint>,  /* время сообщения (UNIX-время) */
        "v": <double>, /* значение */
        "rv": <double> /* исходное значение */
      },
      ...
    ]
  }
},
...

Для поездок массив msgs содержит подробные сообщения из интервала события:

Copied!
"trips": {
  "msgs": [
    {
      "tm": <uint>,    /* время сообщения (UNIX-время) */
      "x": <double>,   /* долгота */
      "y": <double>,   /* широта */
      "c": <uint>,     /* курс */
      "z": <int>,      /* высота */
      "s": <uint>,     /* скорость */
      "m": <double>,   /* пробег */
      "pf": <uint>     /* флаги позиции; включается, если не равно 0 */
    },
    ...
  ]
}

Для приватных позиций значения x, y и c возвращаются как 0.

Для событий назначения водителей возвращается следующий ответ:

Copied!
"resource_drivers": {
  "<driver_id>": [
    {
      "msgs": [
        {
          "tm": <uint>  /* время повторного назначения, UNIX-время */
        },
        ...
      ]
    }
  ]
}

Флаг 0x20

Возвращает отформатированные значения. В разделах ниже описан объект format каждого детектора.

Детекторы eco_driving, health_check и resource_drivers не возвращают объект format для этого флага.

Детекторы датчиков

Детектор ignition возвращает следующий объект format:

Copied!
"ignition": {
  "<sensor_id>": {
    "format": {
      "value": <text>, /* отформатированное значение, обычно «Вкл.» или «Выкл.» */
      "custom_value": <text> /* пользовательское отформатированное значение */
    }
  }
}

Детектор sensors возвращает следующий объект format:

Copied!
"sensors": {
  "<sensor_id>": {
    "format": {
      "value": <text>, /* отформатированное значение; зависит от типа и формата датчика */
      "custom_value": <text> /* пользовательское отформатированное значение */
    }
  }
}

Детекторы уровня топлива

Детекторы lls, filling, theft и fuel_level возвращают следующий объект format:

Copied!
"lls": {
  "<sensor_id>": {
    "format": {
      "value": <text>,   /* отформатированное значение; зависит от типа и формата датчика */
      "raw_value": <text>,/* отформатированное исходное значение */
      "filled": <text>,  /* объём заправленного топлива */
      "theft": <text>,   /* объём слитого топлива */
      "custom_value": <text> /* пользовательское отформатированное значение */
    }
  }
}

Детекторы батареи

Детектор battery_level возвращает следующий объект format:

Copied!
"battery_level": {
  "<sensor_id>": {
    "format": {
      "value": <text>,        /* отформатированный уровень заряда */
      "raw_value": <text>,    /* отформатированное исходное значение датчика */
      "custom_value": <text>  /* пользовательское значение датчика, соответствующее value */
    }
  }
}

Детектор charge возвращает следующий объект format:

Copied!
"charge": {
  "<sensor_id>": {
    "format": {
      "charge": <text>  /* отформатированный объём заряда */
    }
  }
}

Детектор ev возвращает объект format для battery_level или charge в зависимости от события.

Для датчиков уровня заряда батареи поля value и raw_value объекта format учитывают ключ show_as_percentage конфигурации датчика. Если значение этого ключа 1, а значение battery_capacity больше 0, в этих полях возвращается уровень заряда батареи в процентах от ёмкости, со знаком процента. В противном случае в них возвращается уровень заряда в кВт·ч.

trips

Детектор возвращает следующий объект format:

Copied!
"trips": {
  "format": {
    "distance": <text>,   /* отформатированное расстояние поездки */
    "avg_speed": <text>   /* отформатированная средняя скорость */
  }
}

speedings

Детектор возвращает следующий объект format:

Copied!
"speedings": {
  "0": {
    "format": {
      "last_speed": <text>, /* отформатированная скорость в последнем сообщении */
      "limit": <text>,      /* отформатированное ограничение скорости */
      "max_speed": <text>   /* отформатированная максимальная скорость во время события */
    }
  }
}

counters

Детектор возвращает следующий объект format:

Copied!
"counters": {
  "format": {
    "engine_hours": <text | uint>,  /* отформатированное значение счётчика моточасов */
    "mileage": <text>,       /* отформатированное значение счётчика пробега */
    "bytes": <uint>          /* отформатированное значение счётчика GPRS-трафика, в КиБ */
  }
}

Флаг 0x40

Для селекторов выражения возвращает массив, сгруппированный по интервалам, полученным при вычислении выражения. См. Интервалы по выражению.

Copied!
[
  {
    "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 могут содержать:

Copied!
{
  "summary": {
    "speedings": {
      "0": {
        "countIvals": <uint>,    /* количество событий превышения скорости */
        "sumSeconds": <uint>,    /* общая длительность событий, в секундах */
        "countMessages": <uint>, /* количество сообщений в событиях */
        "avgSpeed": <uint>,      /* средняя скорость */
        "maxSpeed": <uint>,      /* максимальная скорость */
        "minSpeed": <uint>       /* минимальная скорость */
      }
    }
  }
}

Коды ошибок

Код ошибки Описание
1 Недействительный или устаревший SID запроса.
4 Ошибка проверки параметров.
7 Сервис событий недоступен.

Если вы заметили ошибку в тексте, пожалуйста, выделите её и нажмите Ctrl+Enter.