Jeder Messwert ist ein Schlüssel mit einem Wert, zum Beispiel "temperature": 21.5. Diese Seite nennt die Regeln, denen Schlüssel und Werte folgen müssen, was mit einem Schlüssel oder Wert geschieht, der eine Regel verletzt, und wie Sie Ihre Schlüsselnamen planen.
Schlüsselregeln
| Regel | Details |
|---|---|
| Zeichen | Nur A-Z, a-z, 0-9, _, . und - |
| Länge | 1 bis 64 Zeichen |
| Groß-/Kleinschreibung | Groß- und Kleinschreibung wird unterschieden: Temp und temp sind zwei Schlüssel |
| Reservierte Präfixe | Ein Schlüssel darf nicht mit _, fw_, current_fw_ oder cfg. beginnen. Diese gehören zu Attributen (Firmware-Status, gewünschte Konfiguration) und zur Plattform. |
Ein Schlüssel, der eine Regel verletzt, wird aus dem Datensatz herausgelassen; die übrigen Schlüssel desselben Datensatzes bleiben erhalten. Der Verwurf wird im Laufprotokoll des Flows gemeldet (siehe die Gründe unten).
Wertregeln
| Wert | Gespeichert als | Grenze |
|---|---|---|
| Eine endliche Zahl | Eine Zahl (in Diagrammen und Aggregationen verwendet) | |
true / false | Ein Flag | |
| Text | Text | 1.024 Zeichen |
| Ein JSON-Objekt oder -Array | JSON | 4 KiB als JSON geschrieben |
null | Nichts: „kein Messwert“, kein Fehler |
Ein Wert über seinem Grenzwert verwirft nur seinen Schlüssel. Siehe Zahlen, Text und Wahr/Falsch-Werte.
Größe einer Nachricht
Eine Nachricht darf nach der Aufteilung in Datensätze höchstens 1.000 Schlüssel-Wert-Punkte enthalten. Eine Nachricht mit mehr wird als Ganzes abgelehnt (bad_form); nichts davon wird gespeichert. Das Geräteprofil begrenzt außerdem die Nutzlastgröße (standardmäßig 64 KiB). Siehe Geräteprofile.
Der Rohschlüssel
Ein Inhalt, der kein JSON ist (Binärdaten, Klartext oder ein JSON-Skalar bzw. -Array auf einem benutzerdefinierten Topic), wird unter dem einzelnen Schlüssel raw als Text gespeichert. Der Schlüssel raw ist von der Grenze von 1.024 Zeichen ausgenommen und stattdessen durch das Profil-Feld Max. Rohnutzlast (Bytes) begrenzt: standardmäßig 4.096 Bytes, zulässig sind 256 bis 65.536 Bytes. Ein Binärinhalt kommt base64-kodiert an (msg.metadata.encoding ist base64).
Dekodieren Sie raw in einem Flow (zum Beispiel mit den Blöcken Base64, Hex oder Bytes oder einem Skript) und speichern Sie benannte Schlüssel. Siehe Datentransformationsblöcke.
Schlüssel mit Topic-Präfix
Mit der Profileinstellung Schlüssel mit Topic präfixen werden Daten auf einem benutzerdefinierten Topic als <topic>.<key> gespeichert:
/im Topic wird zu.; jedes andere Zeichen außerhalb der Schlüsselregel wird zu_.- Die Regel für reservierte Präfixe und das Limit von 64 Zeichen gelten für den zusammengesetzten Schlüssel. Ein zusammengesetzter Schlüssel mit mehr als 64 Zeichen wird verworfen.
rawwird zu<topic>.raw, mit denselben Rohgrenzen.
Beispiel: Topic site1/boiler und Schlüssel temp ergeben site1.boiler.temp. Ohne Präfix ist derselbe Schlüssel auf zwei Topics ein einziger Schlüssel, und der zuletzt geschriebene Wert gewinnt.
Die Schlüsselobergrenze
Ihr Tarif kann begrenzen, wie viele verschiedene Schlüssel Ihre Organisation speichert:
| IoT-Tarifstufe | Verschiedene Telemetrie-Schlüssel |
|---|---|
| Starter | 250 |
| Growth | 400 |
| Scale | 2,050 |
- Ein Schlüssel zählt einmal, egal wie viele Geräte ihn senden.
- Ein Schlüssel bleibt auch dann gezählt, nachdem die Geräte, die ihn gesendet haben, gelöscht wurden: Das Schlüsselverzeichnis wird nie bereinigt.
- Der Zähler wird höchstens einmal pro Minute gelesen.
- Ein neuer Schlüssel über dem Limit wird nicht gespeichert; die übrigen Schlüssel des Datensatzes werden gespeichert. Ist von einem Datensatz nichts mehr übrig, meldet Telemetrie speichern
key_limit.
Halten Sie Schlüsselnamen stabil und über Gerätetypen hinweg einheitlich (temperature, nicht temp_dev42). Die Identität eines Geräts gehört in das Gerät, nie in den Schlüssel.
Schlüsseleinstellungen des Profils
Die Liste Telemetrie-Schlüssel eines Geräteprofils (bis zu 500 Schlüssel) beschreibt die Schlüssel, die seine Geräte senden:
| Feld | Verwendung |
|---|---|
| Typ | Zahl, Ganzzahl, Ja / Nein, Text oder JSON |
| Einheit | Bis zu 32 Zeichen; wird neben Werten und auf Diagrammachsen angezeigt |
| Bezeichnung | Bis zu 128 Zeichen; der Name, der anstelle des Schlüssels angezeigt wird |
| Min, Max | Der erwartete Bereich; ein Messinstrument übernimmt ihn als Standardskala |
| Dezimalstellen | 0 bis 10 |
Die Liste filtert nicht, was gespeichert wird: Ein nicht aufgeführter Schlüssel wird trotzdem gespeichert. Sie benennt und formatiert Schlüssel auf der Registerkarte Telemetrie, in Dashboards und in SCADA-Bindungen. Siehe Geräteprofile.
Warum ein Wert ausgelassen wurde
Das Laufprotokoll des Root-Flows und der Fehler von Telemetrie speichern verwenden diese Codes:
| Code | Bedeutung |
|---|---|
key_invalid | Ein Zeichen außerhalb der Schlüsselregel oder ein leerer Schlüssel |
key_too_long | Über 64 Zeichen (auch nach dem Topic-Präfix) |
key_reserved | Beginnt mit _, fw_, current_fw_ oder cfg. |
string_too_long | Text über 1.024 Zeichen |
value_too_large | JSON über 4 KiB, raw über seiner Obergrenze oder eine Zahl, die nicht endlich ist |
bad_form | Ein Format, das der Speicher nicht liest, oder mehr als 1.000 Punkte in einer Nachricht |
bad_ts | Ein Zeitstempel, der keine Epochen-Millisekunden ist, zu weit in der Zukunft liegt oder für die Einstellungen zu alt ist |
too_old | Älter als Ihre Aufbewahrungsklasse für Rohdaten |
key_limit | Ein neuer Schlüssel über der Schlüsselobergrenze des Tarifs |
no_values | Im Datensatz konnte nichts gespeichert werden |
Tipps zur Benennung
- Verwenden Sie Kleinbuchstaben und Unterstriche:
flow_rate,pump_1_running. - Verwenden Sie Punkte für Strukturen, die Sie gruppieren möchten:
p1.running,p1.value(SCADA-Elementschlüssel verwenden diese Form). - Halten Sie Einheiten aus Schlüsselnamen heraus; legen Sie sie in der Einheit des Profils ab.
- Speichern Sie Zustände als numerische Codes, wenn Sie deren Verlauf benötigen. Siehe Zahlen, Text und true/false-Werte.
Siehe auch Reservierte Schlüssel und Attribute.

