Jeder Messwert ist ein Schlüssel-Wert-Paar, zum Beispiel "temperature": 21.5. Diese Seite listet die Regeln auf, denen Schlüssel und Werte folgen müssen, was mit einem Schlüssel oder Wert geschieht, der gegen eine Regel verstößt, und wie Sie Ihre Schlüsselnamen planen.
Regeln für Schlüssel
| Regel | Details |
|---|---|
| Zeichen | Nur A-Z, a-z, 0-9, _, . und - |
| Länge | 1 bis 64 Zeichen |
| Groß-/Kleinschreibung | Case-sensitiv: 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 gegen eine Regel verstößt, wird aus dem Datensatz weggelassen; die übrigen Schlüssel desselben Datensatzes bleiben erhalten. Der Verwurf wird im Laufprotokoll des Flows gemeldet (siehe die Gründe unten).
Regeln für Werte
| 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 seiner Grenze verwirft nur seinen Schlüssel. Siehe Zahlen, Text und true/false-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 insgesamt abgelehnt (bad_form); nichts davon wird gespeichert. Das Profil des Geräts begrenzt außerdem die Nutzlastgröße (standardmäßig 64 KiB). Siehe Gerätprofile.
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ärer Inhalt 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 dem Topic präfixieren 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 die Grenze von 64 Zeichen gelten für den zusammengesetzten Schlüssel. Ein zusammengesetzter Schlüssel mit mehr als 64 Zeichen wird verworfen.
- Aus
rawwird<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 letzte Schreibvorgang 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, unabhängig davon, wie viele Geräte ihn senden.
- Ein Schlüssel bleibt gezählt, nachdem die Geräte, die ihn gesendet haben, gelöscht wurden: Das Schlüsselverzeichnis wird nie bereinigt.
- Der Zählerstand wird höchstens einmal pro Minute gelesen.
- Ein neuer Schlüssel über der Obergrenze 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 gleich (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ätprofils (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 statt des Schlüssels angezeigt wird |
| Min, Max | Der erwartete Bereich; ein Messinstrument übernimmt ihn als Standardskala |
| Nachkommastellen | 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 dem Tab Telemetrie, in Dashboards und in SCADA-Bindungen. Siehe Gerätprofile.
Warum ein Wert weggelassen 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 Grenze oder eine Zahl, die nicht endlich ist |
bad_form | Ein Format, das der Speicher nicht lesen kann, oder mehr als 1.000 Punkte in einer Nachricht |
bad_ts | Ein Zeitstempel, der keine Epoche in Millisekunden ist, zu weit in der Zukunft liegt oder für die Einstellungen zu alt ist |
too_old | Älter, als Ihre Aufbewahrungsklasse Rohdaten vorhält |
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; geben Sie sie in der Profil-Einheit an.
- Speichern Sie Zustände als numerische Codes, wenn Sie ihren Verlauf benötigen. Siehe Zahlen, Text und true/false-Werte.
Siehe auch Reservierte Schlüssel und Attribute.