Neu: Die KI-Firewall überwacht die gesamte Plattform und erklärt jeden Vorfall in einfachen Worten. So funktioniert es

Telemetrie- und Attribut-API

Lesen Sie neueste Werte und Verlauf, listen Sie die Schlüssel eines Geräts auf und lesen, schreiben und löschen Sie Server- und Shared-Attribute über REST – mit Schlüsselregeln und Fehlern.

Telemetrie ist das, was Geräte messen und über die Zeit senden. Attribute sind benannte Werte, die ein Gerät beschreiben: was es über sich selbst meldet (client), was Sie über es speichern (server) und was Sie ihm zuweisen möchten (shared). Diese Seite listet die REST-Routen für beide. Pfade liegen unter https://<your host>/tenant/<tenantId>.

Die REST-API liest Telemetrie, schreibt sie aber nie. Geräte schreiben Telemetrie über MQTT oder HTTP; Flows schreiben abgeleitete Werte mit Save telemetry. Siehe Device HTTP API und Derived values.

Telemetrie-Routen

MethodePfadBerechtigungFunktion
GET/api/telemetry/latesttelemetry.readDer neueste Wert jedes Schlüssels eines Geräts
GET/api/telemetry/seriestelemetry.readVerlauf von bis zu 50 Schlüsseln über einen Zeitraum
GET/api/telemetry/kindstelemetry.readDie Messwertarten in Ihrer Organisation (zum Beispiel iot_device)
GET/api/iot/devices/{deviceId}/elementstelemetry.readDie Schlüssel eines Geräts, im Geräteprofil deklariert oder gesendet, höchstens 300

Ein Gerät, das Sie nicht lesen dürfen, beantwortet 404, genauso wie ein nicht existierendes Gerät.

Neueste Werte

GET /api/telemetry/latest?kind=iot_device&entityId={deviceId}&keys=temperature,humidity

Lassen Sie keys weg (höchstens 50), um alle Schlüssel abzurufen.

{
  "kind": "iot_device",
  "entityId": "6f1c…",
  "latest": {
    "temperature": { "ts": 1762681200000, "value": 21.5 },
    "humidity": { "ts": 1762681200000, "value": 40 }
  }
}

Verlauf

GET /api/telemetry/series?kind=iot_device&entityId={deviceId}&keys=temperature&from=1762594800000&to=1762681200000&bucket=1h&agg=max
ParameterWerteStandard
keys1 bis 50, durch Kommas getrennterforderlich
from, toMillisekunden seit der Epoche; to nach fromerforderlich
bucketauto, raw, 1m, 1h, 1dauto
aggavg, min, max, last, sum, count, increaseavg
limitPunkte pro Schlüssel, 1 bis 10.00010,000

Tagesblöcke sind UTC-Tage: Für Tage in Ihrer eigenen Zeitzone lesen Sie Stundenblöcke und addieren sie. Rohwerte werden höchstens 90 Tage aufbewahrt, Minutenblöcke höchstens 31 Tage. Die vollständigen Parameterregeln, das Blättern durch Rohwerte und Beispiele finden Sie unter Die History-API.

Die Schlüssel eines Geräts

GET /api/iot/devices/{deviceId}/elements

Die Antwort listet die Elemente des Geräts mit Bezeichnungen und die Schlüssel, die es hat, im Geräteprofil deklariert oder gesendet, höchstens 300. Ohne die Berechtigung, Geräteprofile zu lesen, werden nur die Schlüssel aufgelistet, die das Gerät gesendet hat.

Attribut-Routen

MethodePfadBerechtigungFunktion
GET/api/iot/devices/{deviceId}/attributesiot_device.attributes.readAttribute aller Bereiche lesen
POST/api/iot/devices/{deviceId}/attributes/serveriot_device.attributes.writeServer-Attribute schreiben
POST/api/iot/devices/{deviceId}/attributes/sharediot_device.attributes.writeShared-Attribute schreiben; das Gerät erhält sie
DELETE/api/iot/devices/{deviceId}/attributes/{scope}?keys=a,biot_device.attributes.writeServer- oder Shared-Schlüssel löschen

Client-Attribute werden nur vom Gerät selbst geschrieben. Ein Schreibzugriff auf client beantwortet 405: „Client attributes are written by the device only.“

Lesen

GET /api/iot/devices/{deviceId}/attributes?scope=server&keys=maxTempThreshold,site_code

scope ist client, shared oder server (Groß-/Kleinschreibung egal); lassen Sie es weg für alle drei. keys enthält bis zu 100 Schlüssel.

{
  "attributes": {
    "client": { "fw_version": { "value": "2.4.1", "updatedAt": 1762594800000 } },
    "shared": { "reportInterval": { "value": 60, "updatedAt": 1762500000000 } },
    "server": { "maxTempThreshold": { "value": 8, "updatedAt": 1762400000000 } }
  }
}

Einstellungen, die der Tab Settings eines Geräts verwaltet (cfg.*-Schlüssel auf Geräten, die Einstellungen nach Abschnitt annehmen), werden hier nicht angezeigt; lesen Sie sie über die Geräteeinstellungs-Routen, siehe Firmware and device settings API.

Schreiben

POST/tenant/{tenantId}/api/iot/devices/{deviceId}/attributes/server

Ein flaches JSON-Objekt mit Schlüsseln und Werten: 1 bis 100 Schlüssel pro Anfrage. Ein Wert darf eine Zahl, Text, ein Boolescher Wert, ein Objekt oder eine Liste sein, aber nicht null (löschen Sie stattdessen den Schlüssel). Nur Schlüssel, deren Wert sich geändert hat, werden gespeichert; die Antwort nennt sie. Jede Änderung erreicht Flows als attributes_updated-Nachricht und wird im Audit-Log protokolliert (die Schlüssel, nie die Werte).

Anfragekörper application/json

{
    "maxTempThreshold": 8,
    "site_code": "IST-04"
}

Beispiel curl

curl -X POST 'https://<your-host>/tenant/{tenantId}/api/iot/devices/{deviceId}/attributes/server' \
  -H 'Content-Type: application/json' \
  -d '{"maxTempThreshold":8,"site_code":"IST-04"}'

Antworten

200OK
{
    "changed": [
        "maxTempThreshold",
        "site_code"
    ]
}
400Bad Request
{
    "message": "One or more attribute keys are invalid or reserved.",
    "code": "VALIDATION_ERROR",
    "details": {
        "reason": "keys_invalid",
        "keys": [
            {
                "key": "fw_title",
                "reason": "reserved"
            }
        ]
    }
}
404Not Found
{
    "message": "Device not found.",
    "code": "NOT_FOUND"
}

Shared-Attribute werden dem Gerät sofort gesendet, wenn es verbunden ist, sonst bei der Verbindung. Ein Shared-Wert muss in das Downlink-Limit des Geräteprofils passen: „An attribute value is larger than the device’s downlink limit.“ (details.reason = value_too_large).

Löschen

DELETE /api/iot/devices/{deviceId}/attributes/shared?keys=reportInterval,mode

Die Antwort ist { "deleted": ["mode", "reportInterval"] }, die Schlüssel, die existierten. Ein Gerät wird über gelöschte Shared-Schlüssel informiert.

Regeln für Attributschlüssel

RegelDetail
ZeichenBuchstaben, Ziffern, _, ., -; 1 bis 128; Groß-/Kleinschreibung beachten
Niedeleted; ein Schlüssel, der mit _ beginnt
Für die Plattform oder das Gerät reserviertfw_*, current_fw_*, Schlüssel, die auf .state oder .reason enden, sowie die internen Verwaltungsschlüssel des Geräts (cfg_rejected, cfg_applied_ts, cfg_hash, attr_error, rpc_result, cert_not_after, time_quality)
cfg.*Gewünschte Konfiguration: nur Shared, bis zu 128 Zeichen. Auf einem Gerät, dessen Einstellungen im Tab Settings verwaltet werden, beantwortet ein Schreibzugriff 409 „This device’s configuration (cfg.*) is managed in its Settings; change it there.“
Andere Shared-Schlüsselhöchstens 57 Zeichen
WertgrößeServer-Werte bis 64 KiB JSON; Shared-Werte bis zum Downlink-Limit des Geräts; Verschachtelung höchstens 8 Ebenen tief

Siehe Attributes, wozu jeder Bereich dient, und Reserved keys and attributes für die vollständige Liste.

Typische Anwendungen

  • Gerätespezifische Grenzwerte aus einem ERP oder MES: Schreiben Sie maxTempThreshold als Server-Attribut; Alarmregeln können damit vergleichen. Siehe Alarm conditions reference.
  • Gewünschte Einstellungen für ein Fremdgerät: Schreiben Sie einen Shared-Schlüssel, den die Firmware des Geräts liest, und beobachten Sie seine Client-Attribute auf das Ergebnis.
  • Ein nächtlicher Bericht: Lesen Sie die stündlichen series von gestern und speichern Sie sie in Ihrem Data Warehouse.