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ègle | Détail |
|---|---|
| Caractères | A-Z, a-z, 0-9, _, . et - uniquement |
| Longueur | De 1 à 64 caractères |
| Casse | Sensible à la casse : Temp et temp sont deux clés |
| Préfixes réservés | Une 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
| Valeur | Stockée comme | Limite |
|---|---|---|
| Un nombre fini | Un nombre (tracé et agrégé) | |
true / false | Un indicateur | |
| Texte | Texte | 1 024 caractères |
| Un objet ou un tableau JSON | JSON | 4 Kio une fois écrit en JSON |
null | Rien : « 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.
rawdevient<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 IoT | Clés de télémétrie distinctes |
|---|---|
| Starter | 250 |
| Growth | 400 |
| Scale | 2,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 :
| Champ | Usage |
|---|---|
| Type | Number, Whole number, Yes / no, Text ou JSON |
| Unit | Jusqu’à 32 caractères ; affichée à côté des valeurs et sur les axes des graphiques |
| Label | Jusqu’à 128 caractères ; le nom affiché à la place de la clé |
| Min, Max | La plage attendue ; un indicateur la prend comme échelle par défaut |
| Decimals | De 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 :
| Code | Signification |
|---|---|
key_invalid | Un caractère hors de la règle de clé, ou une clé vide |
key_too_long | Plus de 64 caractères (également après le préfixe de topic) |
key_reserved | Commence par _, fw_, current_fw_ ou cfg. |
string_too_long | Texte de plus de 1 024 caractères |
value_too_large | JSON de plus de 4 Kio, raw au-delà de son plafond, ou nombre qui n’est pas fini |
bad_form | Forme que le stockage ne lit pas, ou plus de 1 000 points dans un message |
bad_ts | Horodatage qui n’est pas en millisecondes epoch, trop loin dans le futur ou trop ancien pour les réglages |
too_old | Plus ancien que la durée de conservation de votre classe de rétention pour les données brutes |
key_limit | Une nouvelle clé au-delà du plafond de clés du plan |
no_values | Rien 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.

