Nouveau : le pare-feu IA surveille toute la plateforme et explique chaque incident en termes simples. Découvrez comment ça marche

Clés de télémétrie

Les règles que doivent suivre toutes les clés et valeurs de télémétrie, les préfixes réservés, la clé raw, les clés préfixées par le topic, le plafond de clés du plan et les réglages de clés du profil.

Chaque relevé est une clé et une valeur, par exemple "temperature": 21.5. Cette page énumère les règles que doivent respecter les clés et les valeurs, ce qui arrive à une clé ou une valeur qui enfreint une règle, et comment planifier le nommage de vos clés.

Règles des clés

RègleDétail
CaractèresA-Z, a-z, 0-9, _, . et - uniquement
LongueurDe 1 à 64 caractères
CasseSensible à la casse : Temp et temp sont deux clés
Préfixes réservésUne clé ne peut pas commencer par _, fw_, current_fw_ ou cfg.. Ces préfixes sont réservés aux attributs (état du firmware, configuration souhaitée) et à la plateforme.

Une clé qui enfreint une règle est retirée de l’enregistrement ; les autres clés du même enregistrement sont conservées. Le rejet est signalé dans l’enregistrement d’exécution du flux (voir les motifs ci-dessous).

Règles des valeurs

ValeurStockée commeLimite
Un nombre finiUn nombre (tracé et agrégé)
true / falseUn indicateur
TexteTexte1 024 caractères
Un objet ou un tableau JSONJSON4 Kio une fois écrit en JSON
nullRien : « pas de relevé », et non une erreur

Une valeur au-delà de sa limite ne fait rejeter que sa clé. Voir Nombres, texte et valeurs vrai/faux.

Taille d’un message

Un message peut contenir au plus 1 000 points clé-valeur après découpage en enregistrements. Un message qui en contient davantage est refusé dans son ensemble (bad_form) ; rien n’en est stocké. Le profil de l’appareil limite aussi la taille de la charge utile (64 Kio par défaut). Voir Profils d’appareils.

La clé raw

Un corps qui n’est pas du JSON (données binaires, texte brut, ou un scalaire ou tableau JSON sur un topic personnalisé) est stocké sous la clé unique raw, en tant que texte. La clé raw est exemptée de la limite de 1 024 caractères et est plafonnée par le réglage Max raw payload (bytes) du profil : 4 096 octets par défaut, de 256 à 65 536 octets. Un corps binaire arrive encodé en base64 (msg.metadata.encoding vaut base64).

Décodez raw dans un flux (par exemple avec les blocs Base64, Hex ou Bytes, ou un script) et enregistrez des clés nommées. Voir Blocs de transformation de données.

Clés préfixées par le topic

Avec le réglage de profil Prefix keys with the topic, les données sur un topic personnalisé sont stockées sous la forme <topic>.<clé> :

  • / dans le topic devient . ; tout autre caractère hors de la règle de clé devient _.
  • La règle du préfixe réservé et la limite de 64 caractères s’appliquent à la clé assemblée. Une clé assemblée de plus de 64 caractères est rejetée.
  • raw devient <topic>.raw, avec les mêmes limites raw.

Exemple : le topic site1/boiler et la clé temp donnent site1.boiler.temp. Sans préfixe, la même clé reçue sur deux topics ne forme qu’une seule clé, et la dernière écriture l’emporte.

Le plafond de clés

Votre plan peut limiter le nombre de clés distinctes que votre organisation stocke :

Niveau du plan IoTClés de télémétrie distinctes
Starter250
Growth400
Scale2,050
  • Une clé ne compte qu’une fois, quel que soit le nombre d’appareils qui l’envoient.
  • Une clé reste comptée après la suppression des appareils qui l’ont envoyée : le dictionnaire des clés n’est jamais épuré.
  • Le nombre est relevé au plus une fois par minute.
  • Une nouvelle clé au-delà de la limite n’est pas stockée ; les autres clés de l’enregistrement le sont. Lorsqu’il ne reste rien d’un enregistrement, Enregistrer la télémétrie signale key_limit.

Gardez des noms de clés stables et partagés entre les types d’appareils (temperature, et non temp_dev42). Placez l’identité d’un appareil dans l’appareil, jamais dans la clé.

Réglages des clés du profil

La liste Telemetry keys d’un profil d’appareil (jusqu’à 500 clés) décrit les clés que ses appareils envoient :

ChampUsage
TypeNumber, Whole number, Yes / no, Text ou JSON
UnitJusqu’à 32 caractères ; affichée à côté des valeurs et sur les axes des graphiques
LabelJusqu’à 128 caractères ; le nom affiché à la place de la clé
Min, MaxLa plage attendue ; un indicateur la prend comme échelle par défaut
DecimalsDe 0 à 10

La liste ne filtre pas ce qui est stocké : une clé qui n’y figure pas est tout de même stockée. Elle nomme et met en forme les clés dans l’onglet Telemetry, dans les tableaux de bord et dans les liaisons SCADA. Voir Profils d’appareils.

Pourquoi une valeur a été omise

Le journal d’exécution du flux racine et l’erreur de Save telemetry utilisent ces codes :

CodeSignification
key_invalidUn caractère hors de la règle de clé, ou une clé vide
key_too_longPlus de 64 caractères (également après le préfixe de topic)
key_reservedCommence par _, fw_, current_fw_ ou cfg.
string_too_longTexte de plus de 1 024 caractères
value_too_largeJSON de plus de 4 Kio, raw au-delà de son plafond, ou nombre qui n’est pas fini
bad_formForme que le stockage ne lit pas, ou plus de 1 000 points dans un message
bad_tsHorodatage qui n’est pas en millisecondes epoch, trop loin dans le futur ou trop ancien pour les réglages
too_oldPlus ancien que la durée de conservation de votre classe de rétention pour les données brutes
key_limitUne nouvelle clé au-delà du plafond de clés du plan
no_valuesRien dans l’enregistrement n’a pu être stocké

Conseils de nommage

  • Utilisez des minuscules et des tirets bas : flow_rate, pump_1_running.
  • Utilisez des points pour une structure que vous voulez regrouper : p1.running, p1.value (les clés d’éléments SCADA utilisent cette forme).
  • Ne mettez pas les unités dans les noms de clés ; placez-les dans l’Unit du profil.
  • Stockez les états sous forme de codes numériques lorsque vous avez besoin de leur historique. Voir Nombres, texte et valeurs true/false.

Voir aussi Clés et attributs réservés.