Cada lectura es una clave y un valor, por ejemplo "temperature": 21.5. Esta página enumera las reglas que deben cumplir las claves y los valores, qué ocurre con una que incumpla una regla y cómo planificar los nombres de tus claves.
Reglas de las claves
| Regla | Detalle |
|---|---|
| Caracteres | Solo A-Z, a-z, 0-9, _, . y - |
| Longitud | De 1 a 64 caracteres |
| Mayúsculas y minúsculas | Distingue mayúsculas y minúsculas: Temp y temp son dos claves |
| Prefijos reservados | Una clave no puede empezar por _, fw_, current_fw_ ni cfg.. Estos pertenecen a los atributos (estado del firmware, configuración deseada) y a la plataforma. |
Una clave que incumple una regla se deja fuera del registro; las demás claves del mismo registro se conservan. El descarte se informa en el registro de ejecución del flujo (vea los motivos más abajo).
Reglas de los valores
| Valor | Se almacena como | Límite |
|---|---|---|
| Un número finito | Un número (representado en gráficos y agregado) | |
true / false | Un indicador | |
| Texto | Texto | 1.024 caracteres |
| Un objeto o matriz JSON | JSON | 4 KiB cuando se escribe como JSON |
null | Nada: «sin lectura», no un error |
Un valor por encima de su límite descarta solo su clave. Consulte Numbers, text and true/false values.
Tamaño de un mensaje
Un mensaje puede contener como máximo 1,000 puntos clave-valor después de dividirse en registros. Un mensaje con más se rechaza completo (bad_form); no se almacena nada de él. El perfil del dispositivo también limita el tamaño de la carga (64 KiB por defecto). Consulte Device profiles.
La clave raw
Un cuerpo que no es JSON (datos binarios, texto plano, o un escalar o matriz JSON en un tópico personalizado) se almacena bajo la única clave raw, como texto. La clave raw está exenta del límite de 1.024 caracteres y en su lugar está limitada por la Carga útil raw máxima (bytes) del perfil: 4.096 bytes por defecto, de 256 a 65.536 bytes. Un cuerpo binario llega codificado en base64 (msg.metadata.encoding es base64).
Decodifica raw en un flujo (por ejemplo con los bloques Base64, Hex o Bytes, o con un script) y guarda claves con nombre. Véase Bloques de transformación de datos.
Claves con prefijo de tópico
Con el ajuste del perfil Prefijar claves con el tópico, los datos de un tópico personalizado se almacenan como <tópico>.<clave>:
/en el tópico se convierte en.; cualquier otro carácter fuera de la regla de claves se convierte en_.- La regla de prefijo reservado y el límite de 64 caracteres se aplican a la clave unida. Una clave unida de más de 64 caracteres se descarta.
rawpasa a ser<tópico>.raw, con los mismos límites de raw.
Ejemplo: el tópico site1/boiler y la clave temp dan site1.boiler.temp. Sin el prefijo, la misma clave que llega por dos tópicos es una sola clave, y gana la última escritura.
El tope de claves
Tu plan puede limitar cuántas claves distintas almacena tu organización:
| Nivel del plan IoT | Claves de telemetría distintas |
|---|---|
| Starter | 250 |
| Growth | 400 |
| Scale | 2,050 |
- Una clave cuenta una sola vez, independientemente de cuántos dispositivos la envíen.
- Una clave sigue contando después de que se eliminen los dispositivos que la enviaron: el diccionario de claves nunca se depura.
- El recuento se lee como máximo una vez por minuto.
- Una clave nueva por encima del límite no se almacena; sí se almacenan las demás claves del registro. Cuando no queda nada de un registro, Save telemetry informa
key_limit.
Mantén los nombres de las claves estables y compartidos entre tipos de dispositivo (temperature, no temp_dev42). Pon la identidad de un dispositivo en el propio dispositivo, nunca en la clave.
Ajustes de claves del perfil
La lista Claves de telemetría de un perfil de dispositivo (hasta 500 claves) describe las claves que envían sus dispositivos:
| Campo | Uso |
|---|---|
| Tipo | Número, Número entero, Sí / no, Texto o JSON |
| Unidad | Hasta 32 caracteres; se muestra junto a los valores y en los ejes de los gráficos |
| Etiqueta | Hasta 128 caracteres; el nombre que se muestra en lugar de la clave |
| Mín, Máx | El rango esperado; un indicador lo toma como escala por defecto |
| Decimales | De 0 a 10 |
La lista no filtra lo que se almacena: una clave que no aparece en ella se sigue almacenando. Sirve para nombrar y dar formato a las claves en la pestaña Telemetría, en los paneles y en los enlaces SCADA. Véase Perfiles de dispositivo.
Por qué se omitió un valor
El registro de ejecución del flujo raíz y el error de Guardar telemetría usan estos códigos:
| Código | Significado |
|---|---|
key_invalid | Un carácter fuera de la regla de claves, o una clave vacía |
key_too_long | Más de 64 caracteres (también tras el prefijo de tópico) |
key_reserved | Empieza por _, fw_, current_fw_ o cfg. |
string_too_long | Texto de más de 1.024 caracteres |
value_too_large | JSON de más de 4 KiB, raw por encima de su tope, o un número que no es finito |
bad_form | Un formato que el almacén no lee, o más de 1.000 puntos en un mensaje |
bad_ts | Una marca de tiempo que no está en milisegundos epoch, demasiado en el futuro o demasiado antigua para la configuración |
too_old | Más antiguo que su clase de retención de datos brutos |
key_limit | Una clave nueva por encima del tope de claves del plan |
no_values | No se pudo almacenar nada del registro |
Consejos para nombrar
- Usa minúsculas y guiones bajos:
flow_rate,pump_1_running. - Usa puntos para la estructura que quieras agrupar:
p1.running,p1.value(las claves de elementos SCADA usan esta forma). - No incluyas unidades en los nombres de las claves; ponlas en la Unidad del perfil.
- Almacena los estados como códigos numéricos cuando necesites su histórico. Véase Números, texto y valores verdadero/falso.
Véase también Claves y atributos reservados.

