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 incumpla una regla se omite del registro; las demás claves del mismo registro se conservan. La omisión se notifica en el registro de ejecución del flujo (véanse 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 que supere su límite solo elimina su clave. Consulta Números, texto y valores verdadero/falso.
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 en su totalidad (bad_form); no se almacena nada de él. El perfil del dispositivo también limita el tamaño de la carga útil (64 KiB por defecto). Consulta Perfiles de dispositivo.
La clave raw
Un cuerpo que no es JSON (datos binarios, texto plano, o un escalar o matriz JSON en un tema 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 el Máx. carga útil raw (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. Consulta Bloques de transformación de datos.
Claves con prefijo de tema
Con el ajuste del perfil Prefijar claves con el tema, los datos de un tema personalizado se almacenan como <topic>.<key>:
/en el tema se convierte en.; cualquier otro carácter fuera de la regla de claves se convierte en_.- La regla de prefijos reservados y el límite de 64 caracteres se aplican a la clave unida. Una clave unida de más de 64 caracteres se omite.
rawpasa a ser<topic>.raw, con los mismos límites raw.
Ejemplo: el tema site1/boiler y la clave temp dan site1.boiler.temp. Sin el prefijo, la misma clave llegada por dos temas 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 vez, sin importar 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 tope no se almacena; las demás claves del registro sí. Cuando no queda nada de un registro, Guardar telemetría notifica
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 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 predeterminada |
| 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. Consulta 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 del tema) |
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 | Una forma 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 de lo que conserva tu clase de retención para datos raw |
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 historial. Consulta Números, texto y valores verdadero/falso.
Consulta también Claves y atributos reservados.