Wialon para desarrolladores Manual de usuario Documentación de API events get

get

Para obtener los datos de eventos cargados en la sesión, utilice el método events/get.

Antes de llamar a este método, cargue eventos en la sesión mediante el método events/load.

Si especificó el parámetro selector en events/load y obtuvo los eventos necesarios dentro del objeto selector de la respuesta, puede omitir la llamada a este método.

Endpoint

Utilice el método events/get con los siguientes formatos de selector.

Obtener eventos mediante un selector de tipo

Utilice el selector type para devolver eventos del detector especificado dentro del rango comprendido entre timeFrom y timeTo.

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

Obtener eventos mediante un selector de expresión

Utilice el selector expr para obtener los eventos filtrados mediante una expresión. Una expresión permite seleccionar intervalos de detectores cargados que cumplan con una condición, rangos de tiempo explícitos o una combinación de ambos. Los parámetros timeFrom y timeTo delimitan el período de consulta.

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

Por ejemplo, trips{s>100} selecciona los eventos de viaje en los que la velocidad es superior a 100. Para conocer la sintaxis de las expresiones, consulte la sección Intervalos basados en expresiones.

Obtener eventos mediante un selector de índice

Utilice un arreglo (array) de selectores para consultar un rango de eventos por su índice. Para identificar el índice de un evento específico, obtenga los eventos del detector por tipo y utilice el índice encontrado dentro del arreglo retornado. La indexación inicia en 0.

Copied!
svc=events/get&params={
  "selector": [
    {
      "type": <text>,
      "filter1": <long>,
      "indexFrom": <uint>,
      "indexTo": <uint>,
      "detalization": <uint>
    },
    ...
  ]
}

Parámetros

Parámetro Se aplica a Descripción
selector Todos los formatos de selector Obligatorio. Define los eventos que se van a retornar.
type Selector de tipo, selector de índice Obligatorio. Nombre de un tipo de detector de eventos cargado en la sesión. En un selector de tipo, use * para retornar los eventos de todos los detectores cargados. En un selector de índice, especifique el nombre de un detector.
expr Selector de expresión Obligatorio (en lugar de type). Expresión para filtrar intervalos dentro del período especificado. Consulte más información abajo.
timeFrom Selector de tipo, selector de expresión Obligatorio. Inicio del rango de tiempo (tiempo UNIX).
timeTo Selector de tipo, selector de expresión Obligatorio. Fin del rango de tiempo (tiempo UNIX).
detalization Todos los formatos de selector Obligatorio. Flags de respuesta. Consulte más información abajo.
indexFrom Selector de índice Obligatorio. Índice del primer evento solicitado.
indexTo Selector de índice Obligatorio. Índice del último evento solicitado.
filter1 Selector de índice Obligatorio. ID utilizado como clave en el arreglo de eventos para el detector seleccionado. Consulte los IDs específicos por detector en events/check_updates.

El detector de eventos eco_driving no está disponible en Wialon Local.

Flags

Flag Descripción
0x1 Datos básicos del evento: posiciones inicial y final, tiempos y flags de servicio del evento.
0x2 Datos específicos según el tipo de detector.
0x4 Parámetros del mensaje asociado al evento.
0x8 Detalles adicionales cuando estén disponibles: track para viajes (trips) y excesos de velocidad (speedings), y data para eventos de sensores instantáneos y diferenciales.
0x10 Datos detallados de mensaje para los detectores compatibles.
0x20 Valores formateados del detector.
0x40 Agrupar los resultados del selector de expresión por sus intervalos de intersección.
0x80 Resumen de cálculos para resultados del selector de expresión.
0x100 Incluir eventos extendidos.

Intervalos basados en expresiones

Para seleccionar intervalos dentro del período timeFrom–timeTo, especifique una expresión en el parámetro "expr":<text> en lugar de usar el parámetro "type":<text>. Una expresión puede referirse a eventos de detectores cargados, rangos de tiempo explícitos o una combinación de ellos. Puede utilizar los siguientes formatos de expresión:

Operador Descripción Ejemplo
* Selecciona el período de tiempo completo solicitado. *
{} Se utiliza para seleccionar intervalos de detector que cumplan una condición. trips{s>100}
- Se utiliza para especificar un intervalo personalizado en formato inicio-fin, tiempo UNIX. 1451953325-1451953525
| Combina intervalos o expresiones. (1615849200-1615935599|1615935601-1616022000)
& Devuelve la intersección de dos expresiones. trips[0]&1451953325-1451953525
~ Excluye intervalos del período de tiempo solicitado. ~1451953325-1451953525
() Agrupa una expresión. (trips[0]|1451953325-1451953525)
[] Selecciona un ID específico del detector. Si no se especifica ningún ID, se utiliza el primer ID cargado para el detector. sensors[3]

Por ejemplo, la siguiente expresión devuelve eventos del detector trips, que utiliza el ID específico del detector fijo 0, y de sensors con ID 8 que se superponen con uno o ambos de los dos intervalos de tiempo personalizados:

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

Respuesta

Si la solicitud se completa correctamente, la respuesta contiene los resultados del detector solicitados. De lo contrario, se devuelve un código de error.

La mayoría de los detectores devuelven arrays de eventos con claves de ID específicos del detector (por ejemplo, un ID de sensor, ID de conductor o ID de criterio de Conducción eficiente). Para los IDs utilizados por cada detector, consulte IDs específicos del detector. Los detectores trips y counters devuelven sus datos directamente, sin agrupar por ID, y speedings siempre utiliza el ID único 0.

A menos que se indique lo contrario, los valores en la respuesta (sensor, combustible, distancia, velocidad, altitud y kilometraje) utilizan el sistema de medidas establecido al cargar eventos con events/load. Los valores en segundos, bytes, KiB, km/h y tiempo UNIX no se convierten.

Flag 0x1

Devuelve datos básicos del evento.

Copied!
"<type_name>": {
  "<detector_specific_id>": [
    {
      "from": {
        "t": <uint>,  /* hora de inicio del intervalo de evento (tiempo UNIX) */
        "y": <double>,/* latitud */
        "x": <double> /* longitud */
      },
      "to": {
        "t": <uint>,  /* hora de fin del intervalo de evento (tiempo UNIX) */
        "y": <double>,/* latitud */
        "x": <double> /* longitud */
      },
      "m": <uint>,    /* hora del último mensaje procesado */
      "f": <uint>     /* flags de servicio del evento */
    },
    ...
  ]
}

Flag 0x2

Devuelve datos específicos del detector. Los siguientes ejemplos muestran un objeto de evento; se devuelve en el array con clave de su ID específico del detector.

Detectores de sensores

El detector ignition devuelve la siguiente estructura:

Copied!
"ignition": {
  "<sensor_id>": {
    "state": <double>,  /* estado: 0 para apagado, 1 para encendido */
    "type": 1,          /* tipo de sensor: sensor conmutador */
    "hours": <uint>,    /* horas de motor para todo el historial, en segundos */
    "switches": <uint>, /* número de conmutaciones para todo el historial */
    "value": <double>   /* último valor del sensor */
  }
}

El detector sensors devuelve una de las siguientes estructuras dependiendo del tipo de sensor:

Copied!
"sensors": {
  "<sensor_id1>": {
    "state": <double>,      /* estado: 0 para apagado, 1 para encendido */
    "type": 1,              /* tipo de sensor: sensor conmutador */
    "hours": <uint>,        /* horas de motor para todo el historial, en segundos */
    "switches": <uint>,     /* número de conmutaciones para todo el historial */
    "value": <double>       /* último valor del sensor */
  },
  "<sensor_id2>": {
    "type": 2,              /* tipo de sensor: sensor instantáneo */
    "counter": <uint>,      /* número de mensajes consecutivos en el evento */
    "summary": <double>,    /* suma de valores en el evento */
    "total_counter": <uint>,/* número total de mensajes en todo el historial */
    "total_summary": <double>,/* suma total de valores en todo el historial */
    "value": <double>       /* último valor; si es -348201.3876, el valor es desconocido */
  },
  "<sensor_id3>": {
    "type": 3,              /* tipo de sensor: sensor diferencial */
    "counter": <double>,    /* suma de valores en el evento */
    "total_counter": <double>,/* suma de valores en el historial */
    "value": <double>       /* último valor; si es -348201.3876, el valor es desconocido */
  },
  "<sensor_id4>": {
    "type": 4,              /* tipo de sensor: sensor analógico */
    "value": <double>       /* último valor; si es -348201.3876, el valor es desconocido */
  }
}

Detectores de nivel de combustible

Los detectores lls, filling, theft y fuel_level devuelven la misma estructura.

Copied!
"lls": {
  "<sensor_id>": {
    "value": <double>,     /* último nivel de combustible calculado */
    "raw_value": <double>, /* último valor sin procesar del sensor */
    "filled": <double>,    /* cambio de volumen de combustible: positivo para llenado, negativo para descarga */
    "timeDiff": <uint>,    /* hora del mensaje con la máxima diferencia de volumen, tiempo UNIX */
    "latDiff": <double>,   /* latitud de ese mensaje */
    "lonDiff": <double>    /* longitud de ese mensaje */
  }
}

Detectores de batería

El detector battery_level devuelve los valores procesados y sin procesar del nivel de batería.

Copied!
"battery_level": {
  "<sensor_id>": {
    "value": <double>,     /* último nivel de batería calculado */
    "raw_value": <double>  /* último valor sin procesar del sensor */
  }
}

El detector charge devuelve la siguiente estructura:

Copied!
"charge": {
  "<sensor_id>": {
    "charge": <double>,  /* cambio de volumen de carga */
    "timeDiff": <uint>,  /* hora del mensaje con la máxima diferencia de carga, tiempo UNIX */
    "latDiff": <double>, /* latitud de ese mensaje */
    "lonDiff": <double>  /* longitud de ese mensaje */
  }
}

El detector ev devuelve la estructura battery_level o charge, dependiendo del evento.

resource_drivers

El detector agrupa los intervalos de asignación por ID de conductor y devuelve cada intervalo como un objeto separado. El estado actual también se devuelve cuando se solicita el evento actual. Un estado actual puede tener state 1 mientras el conductor todavía está asignado. En este caso, la hora de fin en la respuesta 0x1 es la hora de la última actualización, no la hora real de fin de la asignación. También puede tener state 0 después de que el conductor se haya separado. En este caso, el objeto to muestra el último mensaje procesado, no otra separación; use el historial de eventos para obtener la hora real de separación.

Copied!
"resource_drivers": {
  "<driver_id>": [
    {
      "state": <uint>,             /* estado del conductor: 0 para no asignado, 1 para asignado */
      "aflags": <uint>,            /* flags de asignación */
      "unit_id": <long>,           /* ID de la unidad a la que está asignado el conductor, de la que se separó el conductor, o 0 */
      "propitem_cr_time": <uint>,  /* hora de creación del conductor, tiempo UNIX */
      "switched_to": <long>,       /* ID de la unidad a la que se cambió el conductor; se devuelve solo cuando el conductor fue asignado a otra unidad sin ser separado de esta */
      "real_time_from": <uint>,    /* hora real de inicio de la asignación, tiempo UNIX */
      "validate_sensor_id": <uint> /* ID del sensor utilizado para validar la asignación automática y la separación que le sigue; 0 cuando no se utiliza validación */
    }
  ]
}

Utilice propitem_cr_time para comprobar si el conductor es el actual o si es un conductor que se eliminó y se volvió a crear con el mismo ID.

El valor from.t en la respuesta 0x1 es el inicio del intervalo de evento devuelto. El valor real_time_from es la hora real de inicio de la asignación continua. Estos valores pueden diferir cuando una asignación se representa mediante varios intervalos de eventos, por ejemplo, cuando una asignación larga se divide o una asignación manual repetida inicia un nuevo intervalo. Si la asignación no se divide, real_time_from normalmente coincide con from.t.

Los flags de servicio del evento base, incluidos los flags de posiciones privadas, eventos silenciosos, eventos no secuenciados y eventos recalculados, se devuelven en el campo f con el flag 0x1, no en el objeto específico del detector.

El detector no devuelve un marcador separado para una asignación marcada como falsa. Estas acciones se almacenan por separado, y las acciones automáticas de asignación correspondientes se excluyen cuando se recalculan los eventos.

Las asignaciones manuales, separaciones y acciones de ignorar que afectan los eventos resource_drivers se registran, se consultan y se eliminan con resource/driver_actions_register, resource/driver_actions_list y resource/driver_actions_cleanup.

El campo aflags describe cómo empezó y terminó la asignación. Un intervalo completado generalmente contiene un flag para su inicio y otro para su fin, por lo que los flags se combinan.

Flag Descripción
0x1 La asignación finalizó porque el conductor se cambió a otra unidad. El ID de esa unidad se devuelve en switched_to.
0x2 La asignación empezó porque el conductor se cambió desde otra unidad. Esto finalizó la asignación anterior en esa unidad.
0x4 La asignación se inició manualmente.
0x8 La asignación finalizó manualmente.
0x10 La asignación empieza con state 0 porque otro conductor exclusivo fue asignado a la misma unidad.
0x20 La asignación finalizó porque otro conductor exclusivo fue asignado a la misma unidad.

El detector resource_drivers está disponible solo para recursos. Para cargar sus eventos, pase el ID del recurso en el parámetro itemId de events/load.

trips

El detector devuelve sus datos directamente, sin agrupar por ID.

Copied!
"trips": {
  "state": <uint>,       /* estado del viaje: 0 para estacionamiento, 1 para viaje, 2 para parada */
  "max_speed": <uint>,   /* velocidad máxima durante el viaje */
  "curr_speed": <uint>,  /* velocidad actual */
  "avg_speed": <uint>,   /* velocidad promedio basada en la distancia */
  "distance": <uint>,    /* kilometraje GPS durante el viaje */
  "odometer": <uint>,    /* distancia total de todos los viajes en el historial */
  "course": <uint>,      /* rumbo */
  "altitude": <uint>,    /* altitud */
  "pos_flags": <uint>    /* flags de posición: 1 para error del sensor, 2 cuando el sensor no muestra movimiento */
}

speedings

El detector utiliza el ID específico del detector único 0.

Copied!
"speedings": {
  "0": {
    "max_speed": <uint>,  /* velocidad máxima durante el evento */
    "last_speed": <uint>, /* velocidad en el último mensaje del evento */
    "limit": <uint>       /* límite de velocidad utilizado para detectar el evento */
  }
}

counters

El detector devuelve sus datos directamente, sin agrupar por ID.

Copied!
"counters": {
  "engine_hours": <uint>, /* contador de horas de motor, en segundos */
  "mileage": <uint>,      /* contador de kilometraje */
  "bytes": <uint>         /* contador de tráfico GPRS, en bytes */
}

eco_driving

El detector agrupa los datos por ID de criterio de conducción eficiente.

Copied!
"eco_driving": {
  "<eco_driving_id>": [
    {
      "criterion_type": <text>, /* tipo de criterio de Conducción eficiente */
      "index": <uint>,          /* índice del criterio */
      "max_speed": <uint>,      /* velocidad máxima durante la infracción, km/h */
      "mark": <double>          /* penalización calculada; puede incluir decimales */
    }
  ]
}

El detector eco_driving no está disponible en Wialon Local.

health_check

El detector agrupa los datos por ID de incidente.

Copied!
"health_check": {
  "<incident_id>": [
    {
      "incident_type": <text>, /* tipo de incidente de Diagnóstico */
      "duration": <uint>,      /* duración del incidente, en segundos */
      "sensor_id": <uint>      /* ID del sensor de unidad; no se incluye cuando el incidente no está asociado con un sensor */
    }
  ]
}

Flag 0x4

Devuelve los parámetros disponibles del mensaje asociado con el evento. El objeto p no se incluye cuando no hay parámetros disponibles.

Los valores de los parámetros pueden ser cadenas, enteros, enteros largos o números de punto flotante.

Copied!
"<type_name>": {
  "<detector_specific_id>": [
    {
      "p": {              /* parámetros del mensaje */
        "<parameter_name>": <any>
      }
    }
  ]
}

Flag 0x8

Devuelve datos de detalle adicionales cuando estén disponibles. Para trips y speedings, el campo track contiene una ruta codificada en notación de Google. Para eventos de sensores instantáneos y diferenciales, el campo data contiene datos de evento adicionales.

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

Flag 0x10

Devuelve mensajes detallados para detectores que los admiten. El array msgs se devuelve cuando hay datos de mensaje detallados disponibles.

Para sensores instantáneos y diferenciales (tipos 2 y 3), excepto sensores del nivel de combustible:

Copied!
"sensors": {
  "<sensor_id>": {
    "msgs": [
      {
        "tm": <uint>,  /* hora del mensaje (tiempo UNIX) */
        "v": <double>  /* valor */
      },
      ...
    ]
  },
  ...
}

Para sensores del nivel de combustible:

Copied!
"lls": {
  "<sensor_id>": {
    "msgs": [
      {
        "tm": <uint>,  /* hora del mensaje (tiempo UNIX) */
        "v": <double>, /* valor */
        "rv": <double> /* valor sin procesar */
      },
      ...
    ]
  }
},
...

Para viajes, el array msgs contiene mensajes detallados del intervalo del evento:

Copied!
"trips": {
  "msgs": [
    {
      "tm": <uint>,    /* hora del mensaje (tiempo UNIX) */
      "x": <double>,   /* longitud */
      "y": <double>,   /* latitud */
      "c": <uint>,     /* rumbo */
      "z": <int>,      /* altitud */
      "s": <uint>,     /* velocidad */
      "m": <double>,   /* kilometraje */
      "pf": <uint>     /* flags de posición; se incluyen cuando no son 0 */
    },
    ...
  ]
}

Para posiciones privadas, x, y y c se devuelven como 0.

Para eventos de asignación de conductores, se devuelve la siguiente respuesta:

Copied!
"resource_drivers": {
  "<driver_id>": [
    {
      "msgs": [
        {
          "tm": <uint>  /* hora de asignación repetida, tiempo UNIX */
        },
        ...
      ]
    }
  ]
}

Flag 0x20

Devuelve valores formateados. Las siguientes subsecciones describen el objeto format de cada detector.

Los detectores eco_driving, health_check y resource_drivers no devuelven un objeto format para este flag.

Detectores de sensores

El detector ignition devuelve el siguiente objeto format:

Copied!
"ignition": {
  "<sensor_id>": {
    "format": {
      "value": <text>, /* valor formateado, usualmente "On"/"Off" */
      "custom_value": <text> /* valor formateado personalizado */
    }
  }
}

El detector sensors devuelve el siguiente objeto format:

Copied!
"sensors": {
  "<sensor_id>": {
    "format": {
      "value": <text>, /* valor formateado; depende del tipo de sensor y formato */
      "custom_value": <text> /* valor formateado personalizado */
    }
  }
}

Detectores de nivel de combustible

Los detectores lls, filling, theft y fuel_level devuelven el siguiente objeto format:

Copied!
"lls": {
  "<sensor_id>": {
    "format": {
      "value": <text>,   /* valor formateado; depende del tipo de sensor y formato */
      "raw_value": <text>,/* valor sin procesar formateado */
      "filled": <text>,  /* combustible llenado */
      "theft": <text>,   /* combustible descargado */
      "custom_value": <text> /* valor formateado personalizado */
    }
  }
}

Detectores de batería

El detector battery_level devuelve el siguiente objeto format:

Copied!
"battery_level": {
  "<sensor_id>": {
    "format": {
      "value": <text>,        /* nivel de batería formateado */
      "raw_value": <text>,    /* valor sin procesar del sensor formateado */
      "custom_value": <text>  /* valor personalizado del sensor correspondiente al valor */
    }
  }
}

El detector charge devuelve el siguiente objeto format:

Copied!
"charge": {
  "<sensor_id>": {
    "format": {
      "charge": <text>  /* volumen de carga formateado */
    }
  }
}

El detector ev devuelve el objeto format de battery_level o charge, dependiendo del evento.

Para los sensores de nivel de batería, los campos value y raw_value del objeto format toman en cuenta la clave show_as_percentage de la configuración del sensor. Si la clave está establecida en 1 y battery_capacity es mayor que 0, los campos devuelven el nivel de batería como un porcentaje de la capacidad, incluyendo el signo de porcentaje. De lo contrario, devuelven el nivel en kWh.

El porcentaje se aplica únicamente a los valores formateados del flag 0x20. El campo charge, los valores numéricos devueltos con el flag 0x2 y los datos en los informes y notificaciones siempre están en kWh.

trips

El detector devuelve el siguiente objeto format:

Copied!
"trips": {
  "format": {
    "distance": <text>,   /* distancia del viaje formateada */
    "avg_speed": <text>   /* velocidad promedio del viaje formateada */
  }
}

speedings

El detector devuelve el siguiente objeto format:

Copied!
"speedings": {
  "0": {
    "format": {
      "last_speed": <text>, /* velocidad formateada en el último mensaje */
      "limit": <text>,      /* límite de velocidad formateado */
      "max_speed": <text>   /* velocidad máxima formateada durante el evento */
    }
  }
}

counters

El detector devuelve el siguiente objeto format:

Copied!
"counters": {
  "format": {
    "engine_hours": <text | uint>,  /* valor formateado del contador de horas de motor */
    "mileage": <text>,       /* valor formateado del contador de kilometraje */
    "bytes": <uint>          /* valor formateado del contador de tráfico GPRS, en KiB */
  }
}

Flag 0x40

Para selectores de expresión, devuelve un array agrupado por los intervalos producidos al evaluar la expresión. Consulte Intervalos basados en expresiones.

Copied!
[
  {
    "tf": <uint>,  /* inicio del intervalo de expresión (tiempo UNIX) */
    "tt": <uint>,  /* fin del intervalo de expresión (tiempo UNIX) */
    "d": {          /* resultados del detector para el intervalo de expresión */
      "<type_name>": {
        "<sensor_id>": [
          { }  
        ]
      }
    }
  }
]

Flag 0x80

Para selectores de expresión, devuelve valores agregados calculados a partir de los eventos seleccionados por la expresión, para cada detector e ID específico del detector. Sin el flag 0x40, los resultados se devuelven en el objeto summary de nivel superior. Cuando también se especifica 0x40, el objeto d de cada intervalo contiene su propio objeto summary. Este flag se ignora para selectores de tipo e índice.

Los campos de resumen dependen del detector:

  • trips y speedings: número y duración total de eventos, número de mensajes y estadísticas de velocidad; trips también devuelve la distancia total.
  • sensors instantáneos y diferenciales: número y valor total de eventos, o valores iniciales y finales.
  • lls, filling, theft y fuel_level: llenados y descargas totales, niveles de combustible iniciales y finales, y consumo.
  • battery_level, charge y ev: niveles iniciales y finales, consumo o carga total, dependiendo del detector.
  • counters: horas de motor, kilometraje y tráfico GPRS iniciales y finales.
  • Otros detectores, incluyendo ignition, health_check, eco_driving y sensores conmutadores o analógicos: número y duración total de eventos.

Por ejemplo, un resumen de speedings puede contener:

Copied!
{
  "summary": {
    "speedings": {
      "0": {
        "countIvals": <uint>,    /* número de eventos de exceso de velocidad */
        "sumSeconds": <uint>,    /* duración total del evento, en segundos */
        "countMessages": <uint>, /* número de mensajes en los eventos */
        "avgSpeed": <uint>,      /* velocidad promedio */
        "maxSpeed": <uint>,      /* velocidad máxima */
        "minSpeed": <uint>       /* velocidad mínima */
      }
    }
  }
}

Códigos de error

Código de error Descripción
1 SID de solicitud no válido u obsoleto.
4 Error de validación de parámetros.
7 El servicio de eventos no está disponible.

Si nota un error en el texto, por favor resáltelo y presione Ctrl+Intro.