Attribute sind benannte Werte, die ein Gerät beschreiben oder konfigurieren, im Gegensatz zu Telemetrie, einer Zeitreihe von Messwerten. Eine Firmware-Version, eine Seriennummer, ein Meldeintervall, ein gerätespezifischer Alarmgrenzwert oder eine Raumnummer sind Attribute. Jedes Attribut behält nur seinen aktuellen Wert und den Zeitpunkt seiner letzten Änderung.
Die drei Bereiche
| Bereich | Angezeigt als | Geschrieben von | Sichtbar für das Gerät | Typische Verwendung |
|---|---|---|---|---|
| Client | Client | das Gerät | es selbst | Firmware-Version, IP-Adresse, Fähigkeiten, die angewendete Konfiguration |
| Shared | Shared | die Cloud: Personen, die API, Regeln, Flows, Firmware-Updates | ja, bei Änderung übertragen | Soll-Konfiguration (cfg.*), Firmware-Angebote (fw_*) |
| Server | Server | die Cloud | nie | Gerätespezifische Grenzwerte für Alarmregeln, Notizen, Inventarnummern, Daten für Dashboards |
„Shared-Attribute werden an das Gerät gesendet.“ „Server-Attribute bleiben auf der Plattform.“ „Client-Attribute werden vom Gerät gemeldet und können hier nicht geändert werden.“
Der Tab Attribute
Öffnen Sie das Gerät und dessen Tab Attributes. Wählen Sie den Bereich (Server, Shared, Client) und verwenden Sie Search keys and values. Jede Zeile zeigt den Key, den Value, den Zeitpunkt der Änderung Updated und bei Konfigurationsschlüsseln deren Sync-Status.
Zum Hinzufügen oder Ändern eines Wertes benötigen Sie die Berechtigung Write server and shared device attributes (standardmäßig Administratoren):
- Wählen Sie Add attribute (oder Edit in einer Zeile).
- Geben Sie den New key und den Value als JSON ein: eine Zahl (
300),trueoderfalse,"text"in Anführungszeichen, ein Array oder ein Objekt. - Speichern. Delete entfernt einen Schlüssel, nachdem Sie Delete key? bestätigt haben.
Werte mit der Markierung Write-only sind geheime Konfigurationswerte: Sie können gesetzt, aber nie wieder ausgelesen werden.
Regeln für Schlüssel
- Bis zu 128 Zeichen aus
A–Z a–z 0–9 _ . -, groß- und kleinschreibungsabhängig. deletedist nie ein Schlüssel, und Schlüssel, die mit_beginnen, sind für die Plattform reserviert.- Personen, die API und Flows dürfen keine Schlüssel schreiben, die die Plattform oder das Gerät besitzt:
fw_*undcurrent_fw_*(Firmware), Schlüssel, die auf.stateoder.reasonenden, die Verwaltungsschlüssel des Geräts (cfg_rejected,cfg_applied_ts,cfg_hash,attr_error,rpc_result,cert_not_after,time_quality) undsession_limits. cfg.*-Schlüssel sind ausschließlich Shared-Attribute.- Andere Shared-Schlüssel sind höchstens 57 Zeichen lang, damit die Antwort des Geräts
<key>.reasonnoch in das Geräteschlüssel-Limit von 64 Zeichen passt.
Regeln für Werte
| Element | Grenzwert |
|---|---|
| Verschachtelungstiefe | 8 Ebenen |
| Ein Server- oder Client-Wert | 64 KiB |
| Ein Shared-Wert | Muss in das Downlink-Limit des Geräts passen (standardmäßig 64 KiB, 4 KiB für lizenzierte Geräte) |
null | Kein Wert: Löschen Sie stattdessen den Schlüssel |
Die Geräteseite
Client-Attribute senden (nur geänderte Schlüssel werden gesendet):
PUBLISH v1/attributes
{"current_fw_title": "boiler-fw", "current_fw_version": "26.10.2", "lan.ip": "192.168.1.1"}Attribute abfragen, zum Beispiel nach jeder Verbindung:
PUBLISH v1/attributes/req/7
{"clientKeys": "current_fw_version,lan.ip", "sharedKeys": "cfg.telemetry.interval_s"}
answer on v1/attributes/res/7
{"client": {...}, "shared": {...}}Eine leere Anfrage {} liefert alle Shared-Attribute. Ein Eintrag in der Schlüsselliste, der auf .* endet (zum Beispiel cfg.*), fragt alle Schlüssel mit diesem Präfix ab.
Shared-Änderungen empfangen auf v1/attributes/set. Es werden nur geänderte Schlüssel gesendet. Ein entfernter Schlüssel kommt als {"deleted": ["cfg.wifi.guest.enabled"]} an. Wenden Sie Aktualisierungen idempotent an: Eine Nachricht kann zweimal eintreffen.
Alle Topics finden Sie in der MQTT-Topics- und Payload-Referenz.
Konfigurationsschlüssel (cfg.*)
Shared-Attribute, die mit cfg. beginnen, sind die Soll-Konfiguration. Das Gerät wendet sie an und meldet den angewendeten Wert als Client-Attribut mit demselben Schlüssel. Hermetry vergleicht beide und zeigt den Status jedes Schlüssels an:
| Status | Bedeutung |
|---|---|
| In sync | Das Gerät meldet den Wert, den Sie gesetzt haben. |
| Pending | Sie haben einen Wert gesetzt; das Gerät hat ihn noch nicht gemeldet. |
| Rejected | Das Gerät hat ihn abgelehnt. Die Zeile zeigt Reason: reason. |
| Drifted | Das Gerät meldet einen anderen Wert als den von Ihnen gesetzten. |
| Unknown key | Der Schlüssel ist im Tab Configuration keys des Profils nicht deklariert. |
Ein Schlüssel, den das Gerät nicht anwenden kann, wird im Client-Attribut cfg_rejected gemeldet:
{"cfg_rejected": {"cfg.wifi.radio0.channel": "out_of_range"}}Gründe: unknown_key, bad_type, out_of_range, apply_failed, read_only, busy.
Deklarieren Sie die Schlüssel, die ein Gerät akzeptiert, mit Typ, Bezeichnung und Grenzwerten im Tab Configuration keys des Profils. Siehe Geräteprofile. Lizenzierte Geräte verwenden für ihre vollständige Konfiguration die Fernen Geräteeinstellungen.
Wo Attribute verwendet werden
- Gerätespezifische Alarmgrenzwerte. Der Wert einer Alarmregel
attribute:maxTempliest das Server-AttributmaxTempdes Geräts (danach das Shared-Attribut). Ein Gerät ohne das Attribut wird für diesen Grenzwert nicht geprüft. Siehe Alarmbedingungen-Referenz. - Dashboards. Attributkarten und -tabellen zeigen Server- und Shared-Attribute. Client-Attribute werden dort nicht angeboten.
- Flows. Der Block enrich.device fügt einer Nachricht die Attribute eines Geräts hinzu; Flows können Attribute auch schreiben.
- Gateway-Kindgeräte. Ein Shared-Attribut, das an einen untergeordneten Datenpunkt gesendet wird, wendet das Gateway an und meldet
<key>.stateund<key>.reason.
API
| Aufruf | Funktion | Berechtigung |
|---|---|---|
GET /tenant/{tenantId}/api/iot/devices/{deviceId}/attributes?scope=server&keys=a,b | Attribute lesen: scope ist client, shared oder server (alle, wenn weggelassen), bis zu 100 Schlüssel | Geräteattribute anzeigen |
POST …/attributes/server oder …/attributes/shared | Bis zu 100 Schlüssel schreiben: {"maxTemp": 80} | Server- und Shared-Geräteattribute schreiben |
DELETE …/attributes/server?keys=a,b | Schlüssel löschen | Server- und Shared-Geräteattribute schreiben |
Client-Attribute können nicht über die API geschrieben werden (405). Ein Schreibvorgang über die API hat immer Vorrang vor dem gespeicherten Wert und wird Ihren Flows gemeldet. Siehe Telemetrie- und Attribute-API.
Audit und Export
Jedes Speichern und Löschen eines Attributs wird mit den Schlüsseln, nie mit den Werten, im Audit-Log und im Tab Log des Geräts protokolliert. Ein Organisationsexport enthält Attribute, wobei Werte, die wie Geheimnisse aussehen, maskiert werden.