API de telemetría y atributos

La telemetría son los valores que los dispositivos miden y envían a lo largo del tiempo. Los atributos son valores con nombre que describen un dispositivo: lo que informa sobre sí mismo (cliente), lo que usted almacena sobre él (servidor) y lo que quiere que tenga (compartido). Esta página enumera las rutas REST de ambos. Las rutas cuelgan de https://<su 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 Save telemetry. Consulte Device HTTP API y Derived values.

Rutas de telemetría

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

Últimos valores

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

Omita 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

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

Las claves de un dispositivo

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

La respuesta enumera 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 enumeran las claves que el dispositivo ha enviado.

Rutas de atributos

Los atributos de cliente solo los escribe el dispositivo. Una escritura en client responde 405: «Client attributes are written by the device only.»

Leer

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

scope es client, shared o server (en cualquier forma de mayúsculas); omítalo 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 reciben ajustes por secciones) no se muestran aquí; léalos mediante las rutas de ajustes del dispositivo, consulte Firmware and device settings API.

Escribir

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

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"}'

{
    "changed": [
        "maxTempThreshold",
        "site_code"
    ]
}

{
    "message": "One or more attribute keys are invalid or reserved.",
    "code": "VALIDATION_ERROR",
    "details": {
        "reason": "keys_invalid",
        "keys": [
            {
                "key": "fw_title",
                "reason": "reserved"
            }
        ]
    }
}

{
    "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: «An attribute value is larger than the device’s downlink limit.» (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 informa al dispositivo de las claves compartidas eliminadas.

Reglas de las claves de atributo

Consulte Attributes para saber para qué sirve cada ámbito, y Reserved keys and attributes para la lista completa.

Usos habituales

• Límites por dispositivo desde un ERP o MES: escriba maxTempThreshold como atributo de servidor; las reglas de alarma pueden compararlo. Consulte Alarm conditions reference.
• Ajustes deseados para un dispositivo de terceros: escriba una clave compartida que lea el firmware del dispositivo, y observe sus atributos de cliente para ver el resultado.
• Un informe nocturno: lea las series horarias de ayer y guárdelas en su almacén de datos.