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

API de telemetría y atributos

Lee los últimos valores e historial, lista las claves de un dispositivo y lee, escribe y elimina atributos de servidor y compartidos mediante REST, con reglas de claves y errores.

La telemetría son las mediciones que los dispositivos toman y envían a lo largo del tiempo. Los atributos son valores con nombre que describen un dispositivo: lo que informa sobre sí mismo (client), lo que almacena sobre él (server) y lo que quiere que tenga (shared). Esta página enumera las rutas REST de ambos. Las rutas están bajo https://<tu host>/tenant/<tenantId>.

La API REST lee telemetría, pero nunca la escribe. Los dispositivos escriben telemetría por MQTT o HTTP; los flujos escriben valores derivados con Guardar telemetría. Consulta API HTTP de dispositivos y Valores derivados.

Rutas de telemetría

MétodoRutaPermisoFunción
GET/api/telemetry/latesttelemetry.readEl último valor de cada clave de un dispositivo
GET/api/telemetry/seriestelemetry.readHistorial de hasta 50 claves en un intervalo
GET/api/telemetry/kindstelemetry.readLos tipos de lecturas de tu organización (por ejemplo iot_device)
GET/api/iot/devices/{deviceId}/elementstelemetry.readLas claves de un dispositivo, declaradas en su perfil o enviadas, como máximo 300

Un dispositivo que no puedes leer responde 404, igual que un dispositivo que no existe.

Últimos valores

GET /api/telemetry/latest?kind=iot_device&entityId={deviceId}&keys=temperature,humidity

Omite keys (como máximo 50) para obtener todas las claves.

{
  "kind": "iot_device",
  "entityId": "6f1c…",
  "latest": {
    "temperature": { "ts": 1762681200000, "value": 21.5 },
    "humidity": { "ts": 1762681200000, "value": 40 }
  }
}

Historial

GET /api/telemetry/series?kind=iot_device&entityId={deviceId}&keys=temperature&from=1762594800000&to=1762681200000&bucket=1h&agg=max
ParámetroValoresPor defecto
keysDe 1 a 50, separadas por comasobligatorio
from, tomilisegundos desde la época; to posterior a fromobligatorio
bucketauto, raw, 1m, 1h, 1dauto
aggavg, min, max, last, sum, count, increaseavg
limitpuntos por clave, de 1 a 10.00010,000

Los cubos diarios son días UTC: para días en su propia zona horaria, lea los cubos horarios y súmelos. Los valores en bruto se conservan como máximo 90 días, y los cubos por minuto como máximo 31 días. Las reglas completas de parámetros, la paginación de valores en bruto y los ejemplos trabajados están en La API de histórico.

Claves de un dispositivo

GET /api/iot/devices/{deviceId}/elements

La respuesta lista los elementos del dispositivo con sus etiquetas y las claves que tiene, declaradas en su perfil o enviadas, como máximo 300. Sin el permiso para leer perfiles de dispositivo, solo se listan las claves que el dispositivo ha enviado.

Rutas de atributos

MétodoRutaPermisoFunción
GET/api/iot/devices/{deviceId}/attributesiot_device.attributes.readLee los atributos de todos los ámbitos
POST/api/iot/devices/{deviceId}/attributes/serveriot_device.attributes.writeEscribe atributos de servidor
POST/api/iot/devices/{deviceId}/attributes/sharediot_device.attributes.writeEscribe atributos compartidos; el dispositivo los recibe
DELETE/api/iot/devices/{deviceId}/attributes/{scope}?keys=a,biot_device.attributes.writeElimina claves de servidor o compartidas

Los atributos client solo los escribe el propio dispositivo. Una escritura en client responde 405: “Los atributos client solo los escribe el dispositivo.”

Lectura

GET /api/iot/devices/{deviceId}/attributes?scope=server&keys=maxTempThreshold,site_code

scope es client, shared o server (sin distinguir mayúsculas); omítelo para los tres. keys admite hasta 100 claves.

{
  "attributes": {
    "client": { "fw_version": { "value": "2.4.1", "updatedAt": 1762594800000 } },
    "shared": { "reportInterval": { "value": 60, "updatedAt": 1762500000000 } },
    "server": { "maxTempThreshold": { "value": 8, "updatedAt": 1762400000000 } }
  }
}

Los ajustes que gestiona la pestaña Settings de un dispositivo (claves cfg.* en dispositivos que aceptan ajustes por secciones) no se muestran aquí; léelos mediante las rutas de ajustes del dispositivo, ver API de firmware y ajustes de dispositivo.

Escritura

POST/tenant/{tenantId}/api/iot/devices/{deviceId}/attributes/server

Un objeto JSON plano de claves y valores: de 1 a 100 claves por solicitud. Un valor puede ser un número, texto, booleano, objeto o lista, pero no null (elimina la clave en su lugar). Solo se almacenan las claves cuyo valor cambió; la respuesta las nombra. Cada cambio llega a los flujos como un mensaje attributes_updated y se escribe en el registro de auditoría (las claves, nunca los valores).

Cuerpo de la solicitud application/json

{
    "maxTempThreshold": 8,
    "site_code": "IST-04"
}

Ejemplo curl

curl -X POST 'https://<your-host>/tenant/{tenantId}/api/iot/devices/{deviceId}/attributes/server' \
  -H 'Content-Type: application/json' \
  -d '{"maxTempThreshold":8,"site_code":"IST-04"}'

Respuestas

200OK
{
    "changed": [
        "maxTempThreshold",
        "site_code"
    ]
}
400Solicitud incorrecta
{
    "message": "One or more attribute keys are invalid or reserved.",
    "code": "VALIDATION_ERROR",
    "details": {
        "reason": "keys_invalid",
        "keys": [
            {
                "key": "fw_title",
                "reason": "reserved"
            }
        ]
    }
}
404No encontrado
{
    "message": "Device not found.",
    "code": "NOT_FOUND"
}

Los atributos compartidos se envían al dispositivo de inmediato si está conectado; si no, cuando se conecte. Un valor compartido debe caber en el límite de downlink del perfil del dispositivo: “El valor de un atributo es mayor que el límite de downlink del dispositivo.” (details.reason = value_too_large).

Eliminar

DELETE /api/iot/devices/{deviceId}/attributes/shared?keys=reportInterval,mode

La respuesta es { "deleted": ["mode", "reportInterval"] }, las claves que existían. Se avisa al dispositivo de las claves compartidas eliminadas.

Reglas de claves de atributo

ReglaDetalle
Caracteresletras, dígitos, _, ., -; de 1 a 128; distingue mayúsculas
Nuncadeleted; una clave que empieza por _
Reservadas para la plataforma o el dispositivofw_*, current_fw_*, claves que terminan en .state o .reason, y las claves de contabilidad propias del dispositivo (cfg_rejected, cfg_applied_ts, cfg_hash, attr_error, rpc_result, cert_not_after, time_quality)
cfg.*Configuración deseada: solo compartida, hasta 128 caracteres. En un dispositivo cuyos ajustes se gestionan en su pestaña Settings, una escritura responde 409 “La configuración (cfg.*) de este dispositivo se gestiona en sus Settings; cámbiala allí.”
Otras claves compartidascomo máximo 57 caracteres
Tamaño del valorvalores de servidor de hasta 64 KiB de JSON; valores compartidos hasta el límite de downlink del dispositivo; anidamiento de como máximo 8 niveles

Consulta Atributos para ver para qué sirve cada ámbito, y Claves y atributos reservados para la lista completa.

Usos habituales

  • Límites por dispositivo desde un ERP o MES: escribe maxTempThreshold como atributo de servidor; las reglas de alarma pueden compararlo con él. Ver Referencia de condiciones de alarma.
  • Ajustes deseados para un dispositivo de terceros: escribe una clave compartida que lee el firmware del dispositivo, y observa sus atributos client para ver el resultado.
  • Un informe nocturno: lee las series por hora de ayer y guárdalas en tu almacén de datos.