Dos endpoints de lectura le dan la telemetría de los dispositivos: latest para el valor actual de cada clave, y series para el histórico. Ambos requieren 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 preset 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ámetro | Obligatorio | Significado |
|---|---|---|
kind | Sí | iot_device para la telemetría de dispositivos |
entityId | Sí | El id del dispositivo |
keys | No | Claves separadas por comas, como máximo 50. Omítalo para obtener 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ámetro | Obligatorio | Valores | Por defecto |
|---|---|---|---|
kind | Sí | iot_device | |
entityId | Sí | El id del dispositivo | |
keys | Sí | Separadas por comas, de 1 a 50 claves, cada una según las reglas de claves | |
from | Sí | Inicio, incluido (ms epoch) | |
to | Sí | Fin, excluido (ms epoch); debe ser posterior a from | |
bucket | No | auto, raw, 1m, 1h, 1d | auto |
agg | No | avg, min, max, last, sum, count, increase | avg |
limit | No | Puntos por clave, de 1 a 10.000 | 10,000 |
{
"kind": "iot_device",
"entityId": "6f1c…",
"resolution": "1m",
"agg": "avg",
"series": {
"temperature": [
{ "ts": 1759568400000, "value": 21.2 },
{ "ts": 1759568460000, "value": 21.4 }
]
}
}resolutiones la resolución realmente usada. Conbucket=autoesrawpara ventanas de hasta 24 horas, y después1m,1ho1d, la más fina que quede por debajo de 10.000 buckets.- Con un bucket,
tses el inicio del bucket (alineado a UTC) yvalueel agregado. Los buckets sin lecturas no aparecen, 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;aggse 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ímite | Valor |
|---|---|
| Claves por solicitud | 50 |
| Puntos por clave | 10.000 (limit) |
| Buckets en una ventana | 10.000 a la resolución elegida; si no, 400 range_too_large |
| Valores raw | Solo dentro de su retención raw (como máximo 90 días) |
| Buckets de minuto | Solo dentro de la retención de minuto (como máximo 31 días) |
| Solicitudes | El límite de tasa de la API; 429 con Retry-After cuando se supera. Consulte Errores y límites de tasa. |
Errores
| Estado | Cuerpo | Causa |
|---|---|---|
| 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 claves |
| 400 | { "message": "…", "code": "range_too_large" } | Demasiados buckets para la ventana; use un bucket más grueso |
| 401 / 403 | Sin clave válida, o la clave no tiene el permiso | |
| 404 | { "message": "Not found" } | El dispositivo no existe, o no puede leerlo (la misma respuesta en ambos casos) |
| 429 | Límite de tasa |
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:
- Pida
bucket=raw&limit=10000para su ventana. - Si una clave devolvió 10.000 puntos, vuelva a pedir con
fromigual altsdel último punto + 1. - Repita hasta que una clave devuelva menos de
limitpuntos.
Para periodos largos, prefiera buckets de 1m o 1h: contienen el mínimo, máximo, suma, recuento y último de cada bucket en un 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 buckets 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 buckets de 1m, que llegan como máximo a 31 días atrás.
Otras rutas de lectura
| Ruta | Función |
|---|---|
GET /api/telemetry/kinds | Los tipos de lecturas de su organización (por ejemplo iot_device) |
GET /api/iot/devices/{deviceId}/elements | Las 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.