Novedad: el cortafuegos de IA supervisa toda la plataforma y explica cada incidente con palabras sencillas. Vea cómo funciona

La API de historial

Lea valores actuales y series temporales de telemetría de dispositivos por REST: parámetros, resoluciones, agregados, límites, paginación, errores y ejemplos prácticos.

Dos endpoints de lectura le dan la telemetría de los dispositivos: latest para el valor actual de cada clave, y series para el historial. Ambos están protegidos por el permiso de lectura de telemetría y devuelven solo los dispositivos que el solicitante puede leer. Esta página es la referencia con ejemplos; consulte Fundamentos de la API REST y Autenticación para las claves y las rutas.

Antes de empezar

  • Cree una clave de API con el permiso para leer telemetría (y para leer dispositivos, si también los lista). El preajuste Read-only es suficiente. Restrinja las redes permitidas de la clave a sus servidores.
  • Busque el id del dispositivo (un UUID) en la página del dispositivo o con GET /api/iot/devices.
  • Todas las rutas están bajo su organización: https://<su host>/tenant/<tenantId>/api/....
  • Las horas se expresan en milisegundos desde el 1 de enero de 1970, UTC.

Valores actuales

GET /tenant/{tenantId}/api/telemetry/latest?kind=iot_device&entityId={deviceId}&keys=temperature,humidity
ParámetroObligatorioSignificado
kindSíiot_device para la telemetría de dispositivos
entityIdSíEl id del dispositivo
keysNoClaves separadas por comas, como máximo 50. Omítalo para todas las claves.
{
  "kind": "iot_device",
  "entityId": "6f1c…",
  "latest": {
    "temperature": { "ts": 1759572000000, "value": 21.5 },
    "humidity": { "ts": 1759572000000, "value": 40 }
  }
}

Una clave que el dispositivo nunca envió no aparece en latest.

Series

GET /tenant/{tenantId}/api/telemetry/series?kind=iot_device&entityId={deviceId}&keys=temperature&from=1759568400000&to=1759572000000&bucket=auto&agg=avg
ParámetroObligatorioValoresPredeterminado
kindSíiot_device
entityIdSíEl id del dispositivo
keysSíSeparadas por comas, de 1 a 50 claves, cada una según las reglas de clave
fromSíInicio, incluido (epoch en ms)
toSíFin, excluido (epoch en ms); debe ser posterior a from
bucketNoauto, raw, 1m, 1h, 1dauto
aggNoavg, min, max, last, sum, count, increaseavg
limitNoPuntos por clave, de 1 a 10 00010,000
{
  "kind": "iot_device",
  "entityId": "6f1c…",
  "resolution": "1m",
  "agg": "avg",
  "series": {
    "temperature": [
      { "ts": 1759568400000, "value": 21.2 },
      { "ts": 1759568460000, "value": 21.4 }
    ]
  }
}
  • resolution es la resolución realmente usada. Con bucket=auto es raw para ventanas de hasta 24 horas, y después 1m, 1h o 1d, la más fina que quede por debajo de 10 000 intervalos.
  • Con un intervalo, ts es el inicio del intervalo (alineado en UTC) y value el agregado. Los intervalos sin lecturas están ausentes, no son cero.
  • Con raw, cada valor almacenado se devuelve tal como se guardó (números, texto, booleanos, JSON), un punto por marca de tiempo, del más antiguo al más reciente; agg se ignora.
  • Los puntos se ordenan por tiempo. Una clave sin datos devuelve una lista vacía.

Consulte Agregados y rollups para ver lo que devuelve cada agg.

Límites

LímiteValor
Claves por solicitud50
Puntos por clave10 000 (limit)
Intervalos en una ventana10 000 a la resolución elegida; si no, 400 range_too_large
Valores brutosSolo dentro de su retención de datos brutos (como máximo 90 días)
Intervalos de minutoSolo dentro de la retención de minutos (como máximo 31 días)
SolicitudesEl límite de frecuencia de la API; 429 con Retry-After cuando se supera. Consulte Errores y límites de frecuencia.

Errores

EstadoCuerpoCausa
400{ "message": "to must be after from" }to no es posterior a from
400{ "message": "bad keys" }keys vacío, más de 50, o una clave que incumple las reglas de clave
400{ "message": "…", "code": "range_too_large" }Demasiados intervalos para la ventana; use un bucket más grueso
401 / 403Clave no válida o sin el permiso necesario
404{ "message": "Not found" }El dispositivo no existe, o no tiene permiso para leerlo (la misma respuesta en ambos casos)
429Límite de frecuencia

Paginación de valores raw

Una lectura raw devuelve como máximo 10 000 puntos por clave, del más antiguo al más reciente. Para leer más:

  1. Solicite bucket=raw&limit=10000 para su ventana.
  2. Si una clave devolvió 10 000 puntos, vuelva a solicitar con from igual al ts del último punto + 1.
  3. Repita hasta que una clave devuelva menos puntos que limit.

Para periodos largos, prefiera intervalos de 1m o 1h: contienen el mínimo, máximo, suma, recuento y último valor de cada intervalo en un solo valor cada uno.

Ejemplos

Valores actuales con curl:

curl -s -H "Authorization: Bearer $HERMETRY_KEY" \
  "https://$HOST/tenant/$TENANT/api/telemetry/latest?kind=iot_device&entityId=$DEVICE&keys=level,pump_running"

Máximo por hora de una presión en los últimos 7 días:

TO=$(date +%s000); FROM=$((TO - 7*24*3600*1000))
curl -s -H "Authorization: Bearer $HERMETRY_KEY" \
  "https://$HOST/tenant/$TENANT/api/telemetry/series?kind=iot_device&entityId=$DEVICE&keys=pressure&from=$FROM&to=$TO&bucket=1h&agg=max"

Energía consumida por hora (un contador de kWh que solo crece) durante un día:

curl -s -H "Authorization: Bearer $HERMETRY_KEY" \
  "https://$HOST/tenant/$TENANT/api/telemetry/series?kind=iot_device&entityId=$DEVICE&keys=energy_kwh&from=1762642800000&to=1762729200000&bucket=1h&agg=increase"

Totales diarios en su zona horaria

Los intervalos diarios son días UTC. Para un día local, lea el increase (o sum) por hora y sume las horas que pertenecen a cada día local:

// Node.js 18+: daily energy per local day (Europe/Istanbul) for the last 7 days
const tz = 'Europe/Istanbul';
const to = Date.now();
const from = to - 7 * 24 * 3600 * 1000;
const url = `https://${host}/tenant/${tenant}/api/telemetry/series?kind=iot_device&entityId=${device}`
  + `&keys=energy_kwh&from=${from}&to=${to}&bucket=1h&agg=increase`;
const res = await fetch(url, { headers: { Authorization: `Bearer ${key}` } });
const { series } = await res.json();
const days = {};
for (const p of series.energy_kwh) {
  const day = new Date(p.ts).toLocaleDateString('en-CA', { timeZone: tz }); // YYYY-MM-DD
  days[day] = (days[day] ?? 0) + p.value;
}
console.log(days);

La primera hora de la ventana cuenta solo lo que subió dentro de ella, así que comience la ventana una hora antes del primer día local que necesite y descarte esa hora. Una zona con desfase de media hora necesita intervalos de 1m, que llegan como máximo a 31 días atrás.

Otras rutas de lectura

RutaFunción
GET /api/telemetry/kindsLos tipos de lecturas que tiene su organización (por ejemplo iot_device)
GET /api/iot/devices/{deviceId}/elementsLas claves de un dispositivo (declaradas en su perfil o enviadas), como máximo 300, con etiquetas y unidades

Para escrituras, los dispositivos usan MQTT o HTTP; la API REST no tiene ruta de escritura de telemetría. Consulte API HTTP de dispositivos y API de telemetría y atributos.