Telemetrie- und Attribute-API

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 beides. 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

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 (maximal 50) weg, um alle Schlüssel zu erhalten.

{
  "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

Tages-Buckets sind UTC-Tage; für Tage in Ihrer eigenen Zeitzone lesen Sie stündliche Buckets und addieren sie. Rohwerte werden höchstens 90 Tage aufbewahrt, Minuten-Buckets höchstens 31 Tage. Die vollständigen Parameterregeln, das Blättern durch Rohwerte und Beispiele finden Sie unter The 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 den Schlüsseln, die es hat, im Geräteprofil deklariert oder gesendet, maximal 300. Ohne die Berechtigung, Geräteprofile zu lesen, werden nur die Schlüssel aufgelistet, die das Gerät gesendet hat.

Attribut-Routen

Client-Attribute werden nur vom Gerät geschrieben. Ein Schreibvorgang 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 (beliebige Groß-/Kleinschreibung); 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 Reiter 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äte-Einstellungsrouten, siehe Firmware and device settings API.

Schreiben

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

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"}'

{
    "changed": [
        "maxTempThreshold",
        "site_code"
    ]
}

{
    "message": "One or more attribute keys are invalid or reserved.",
    "code": "VALIDATION_ERROR",
    "details": {
        "reason": "keys_invalid",
        "keys": [
            {
                "key": "fw_title",
                "reason": "reserved"
            }
        ]
    }
}

{
    "message": "Device not found.",
    "code": "NOT_FOUND"
}

Shared-Attribute werden dem Gerät sofort gesendet, wenn es verbunden ist, andernfalls beim Verbinden. 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 lautet { "deleted": ["mode", "reportInterval"] }, die Schlüssel, die existierten. Ein Gerät wird über gelöschte Shared-Schlüssel informiert.

Regeln für Attributschlüssel

Was jeder Bereich bewirkt, lesen Sie unter Attributes, die vollständige Liste finden Sie unter Reserved keys and attributes.

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.
• Soll-Einstellungen für ein Drittanbietergerä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ündliche series von gestern und speichern Sie sie in Ihrem Data Warehouse.