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

Claves de telemetría

Las reglas que deben cumplir todas las claves y valores de telemetría, los prefijos reservados, la clave raw, las claves con prefijo de tópico, el tope de claves del plan y los ajustes de claves del perfil.

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

ReglaDetalle
CaracteresSolo A-Z, a-z, 0-9, _, . y -
LongitudDe 1 a 64 caracteres
Mayúsculas y minúsculasDistingue mayúsculas y minúsculas: Temp y temp son dos claves
Prefijos reservadosUna 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

ValorSe almacena comoLímite
Un número finitoUn número (representado en gráficos y agregado)
true / falseUn indicador
TextoTexto1.024 caracteres
Un objeto o matriz JSONJSON4 KiB cuando se escribe como JSON
nullNada: «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.
  • raw pasa 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 IoTClaves de telemetría distintas
Starter250
Growth400
Scale2,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:

CampoUso
TipoNúmero, Número entero, Sí / no, Texto o JSON
UnidadHasta 32 caracteres; se muestra junto a los valores y en los ejes de los gráficos
EtiquetaHasta 128 caracteres; el nombre que se muestra en lugar de la clave
Mín, MáxEl rango esperado; un indicador lo toma como escala por defecto
DecimalesDe 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ódigoSignificado
key_invalidUn carácter fuera de la regla de claves, o una clave vacía
key_too_longMás de 64 caracteres (también tras el prefijo de tópico)
key_reservedEmpieza por _, fw_, current_fw_ o cfg.
string_too_longTexto de más de 1.024 caracteres
value_too_largeJSON de más de 4 KiB, raw por encima de su tope, o un número que no es finito
bad_formUn formato que el almacén no lee, o más de 1.000 puntos en un mensaje
bad_tsUna marca de tiempo que no está en milisegundos epoch, demasiado en el futuro o demasiado antigua para la configuración
too_oldMás antiguo que su clase de retención de datos brutos
key_limitUna clave nueva por encima del tope de claves del plan
no_valuesNo 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.