Chaque relevé est une clé et une valeur, par exemple "temperature": 21.5. Cette page présente les règles que doivent respecter les clés et les valeurs, ce qui se passe lorsqu’une donnée enfreint une règle, et comment planifier vos noms de clés.
Règles relatives aux clés
| Règle | Détail |
|---|---|
| Caractères | A-Z, a-z, 0-9, _, . et - uniquement |
| Longueur | 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 appartiennent aux attributs (état du micrologiciel, 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 retrait est signalé dans l’enregistrement d’exécution du flux (voir les motifs ci-dessous).
Règles relatives aux valeurs
| Valeur | Stockée sous forme | Limite |
|---|---|---|
| Un nombre fini | Un nombre (représenté dans des graphiques et agrégé) | |
true / false | Un indicateur | |
| Texte | Texte | 1 024 caractères |
| Un objet ou un tableau JSON | JSON | 4 Kio lorsqu’il est écrit en JSON |
null | Rien : « pas de relevé », et non une erreur |
Une valeur au-delà de sa limite supprime uniquement sa clé. Voir Nombres, texte et valeurs vrai/faux.
Taille d’un message
Un message peut contenir au maximum 1 000 points clé-valeur après sa découpe 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 également la taille de la charge utile (64 Kio par défaut). Voir Profils d’appareils.
La clé brute
Un corps qui n’est pas du JSON (données binaires, texte brut, ou scalaire ou tableau JSON sur un topic personnalisé) est stocké sous la clé unique raw, en tant que texte. La clé raw échappe à la limite de 1 024 caractères et est plafonnée par le paramètre 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 paramètre de profil Prefix keys with the topic, les données d’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_.- Les règles de préfixes réservés et la limite de 64 caractères s’appliquent à la clé complète. Une clé complète de plus de 64 caractères est supprimée.
rawdevient<topic>.raw, avec les mêmes limites pour les données brutes.
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é est comptée une seule 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à du plafond n’est pas stockée ; les autres clés de l’enregistrement le sont. Lorsqu’il ne reste rien d’un enregistrement, Save telemetry 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é.
Paramètres de 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é à 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 | 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
L’enregistrement 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 un nombre non fini |
bad_form | Forme non lisible par le stockage, ou plus de 1 000 points dans un message |
bad_ts | Un horodatage qui n’est pas en millisecondes depuis l’époque, trop éloigné dans le futur ou trop ancien pour les paramètres |
too_old | Plus ancien que ce que conserve votre classe de rétention pour les données brutes |
key_limit | Une nouvelle clé au-delà du plafond du plan |
no_values | Rien dans l’enregistrement n’a pu être stocké |
Conseils de nommage
- Utilisez les minuscules et les tirets bas :
flow_rate,pump_1_running. - Utilisez des points pour la 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 en voulez l’historique. Voir Nombres, texte et valeurs vrai/faux.
Voir aussi Clés et attributs réservés.