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

Die History-API

Aktuelle Werte und Zeitreihen von Gerätetelemetrie über REST lesen – Parameter, Auflösungen, Aggregate, Grenzwerte, Paging, Fehler und ausgearbeitete Beispiele.

Zwei Lese-Endpunkte liefern Gerätetelemetrie: latest für den aktuellen Wert jedes Schlüssels und series für den Verlauf. Beide sind durch die Berechtigung zum Lesen von Telemetrie geschützt und geben nur Geräte zurück, die der Aufrufer lesen darf. Diese Seite ist die Referenz mit Beispielen; Schlüssel und Pfade finden Sie unter REST-API-Grundlagen und Authentifizierung.

Bevor Sie beginnen

  • Erstellen Sie einen API-Schlüssel mit der Berechtigung zum Lesen von Telemetrie (und zum Lesen von Geräten, wenn Sie diese auch auflisten). Die Voreinstellung Read-only genügt. Beschränken Sie die erlaubten Netzwerke des Schlüssels auf Ihre Server.
  • Ermitteln Sie die Geräte-ID (eine UUID) auf der Geräteseite oder mit GET /api/iot/devices.
  • Alle Pfade liegen unter Ihrer Organisation: https://<your host>/tenant/<tenantId>/api/....
  • Zeitangaben sind Millisekunden seit dem 1. Januar 1970, UTC.

Aktuelle Werte

GET /tenant/{tenantId}/api/telemetry/latest?kind=iot_device&entityId={deviceId}&keys=temperature,humidity
ParameterPflichtBedeutung
kindJaiot_device für Gerätetelemetrie
entityIdJaDie Geräte-ID
keysNeinDurch Kommas getrennte Schlüssel, maximal 50. Weglassen für alle Schlüssel.
{
  "kind": "iot_device",
  "entityId": "6f1c…",
  "latest": {
    "temperature": { "ts": 1759572000000, "value": 21.5 },
    "humidity": { "ts": 1759572000000, "value": 40 }
  }
}

Ein Schlüssel, den das Gerät nie gesendet hat, fehlt in latest.

Verlauf

GET /tenant/{tenantId}/api/telemetry/series?kind=iot_device&entityId={deviceId}&keys=temperature&from=1759568400000&to=1759572000000&bucket=auto&agg=avg
ParameterPflichtWerteStandard
kindJaiot_device
entityIdJaDie Geräte-ID
keysJaDurch Kommas getrennt, 1 bis 50 Schlüssel, jeder entspricht den Schlüsselregeln
fromJaBeginn, einschließlich (Epoche in ms)
toJaEnde, ausschließlich (Epoche in ms); muss nach from liegen
bucketNeinauto, raw, 1m, 1h, 1dauto
aggNeinavg, min, max, last, sum, count, increaseavg
limitNeinPunkte je Schlüssel, 1 bis 10.00010,000
{
  "kind": "iot_device",
  "entityId": "6f1c…",
  "resolution": "1m",
  "agg": "avg",
  "series": {
    "temperature": [
      { "ts": 1759568400000, "value": 21.2 },
      { "ts": 1759568460000, "value": 21.4 }
    ]
  }
}
  • resolution ist die tatsächlich verwendete Auflösung. Bei bucket=auto ist sie raw für Zeitfenster bis 24 Stunden, danach 1m, 1h oder 1d, je nachdem, welche die feinste Auflösung unter 10.000 Buckets ergibt.
  • Bei einem Bucket ist ts der Beginn des Buckets (UTC-ausgerichtet) und value der Aggregatwert. Buckets ohne Messwerte fehlen, sie sind nicht null.
  • Bei raw wird jeder gespeicherte Wert so zurückgegeben, wie er gespeichert wurde (Zahlen, Text, Wahrheitswerte, JSON), ein Punkt je Zeitstempel, der älteste zuerst; agg wird ignoriert.
  • Punkte sind nach Zeit sortiert. Ein Schlüssel ohne Daten liefert eine leere Liste.

Was jedes agg liefert, steht unter Aggregate und Rollups.

Grenzwerte

GrenzeWert
Schlüssel je Anfrage50
Punkte je Schlüssel10.000 (limit)
Buckets in einem Zeitfenster10.000 bei der gewählten Auflösung, sonst 400 range_too_large
RohwerteNur innerhalb Ihrer Rohdaten-Aufbewahrung (höchstens 90 Tage)
Minuten-BucketsNur innerhalb der Minutenspeicherung (höchstens 31 Tage)
AnfragenDas API-Ratenlimit; bei Überschreitung 429 mit Retry-After. Siehe Fehler und Ratenlimits.

Fehler

StatusInhaltUrsache
400{ "message": "to must be after from" }to liegt nicht nach from
400{ "message": "bad keys" }Leeres keys, mehr als 50 oder ein Schlüssel, der die Schlüsselregeln verletzt
400{ "message": "…", "code": "range_too_large" }Zu viele Buckets für das Zeitfenster; verwenden Sie einen gröberen bucket
401 / 403Kein gültiger Schlüssel oder dem Schlüssel fehlt die Berechtigung
404{ "message": "Not found" }Das Gerät existiert nicht, oder Sie dürfen es nicht lesen (in beiden Fällen dieselbe Antwort)
429Ratenlimit

Rohwerte seitenweise lesen

Ein Rohwert-Lesevorgang liefert höchstens 10.000 Punkte je Schlüssel, der älteste zuerst. Um mehr zu lesen:

  1. Fordern Sie bucket=raw&limit=10000 für Ihr Zeitfenster an.
  2. Hat ein Schlüssel 10.000 Punkte geliefert, fordern Sie erneut an, mit from gleich dem ts des letzten Punkts + 1.
  3. Wiederholen Sie dies, bis ein Schlüssel weniger als limit Punkte liefert.

Für lange Zeiträume verwenden Sie besser 1m– oder 1h-Buckets: Sie enthalten Minimum, Maximum, Summe, Anzahl und letzten Wert jedes Buckets als je einen Wert.

Beispiele

Aktuelle Werte mit curl:

curl -s -H "Authorization: Bearer $HERMETRY_KEY" \
  "https://$HOST/tenant/$TENANT/api/telemetry/latest?kind=iot_device&entityId=$DEVICE&keys=level,pump_running"

Stündliches Maximum eines Drucks über die letzten 7 Tage:

TO=$(date +%s000); FROM=$((TO - 7*24*3600*1000))
curl -s -H "Authorization: Bearer $HERMETRY_KEY" \
  "https://$HOST/tenant/$TENANT/api/telemetry/series?kind=iot_device&entityId=$DEVICE&keys=pressure&from=$FROM&to=$TO&bucket=1h&agg=max"

Energieverbrauch je Stunde (ein kWh-Zähler, der nur steigt) über einen Tag:

curl -s -H "Authorization: Bearer $HERMETRY_KEY" \
  "https://$HOST/tenant/$TENANT/api/telemetry/series?kind=iot_device&entityId=$DEVICE&keys=energy_kwh&from=1762642800000&to=1762729200000&bucket=1h&agg=increase"

Tagessummen in Ihrer Zeitzone

Tages-Buckets sind UTC-Tage. Für einen lokalen Tag lesen Sie das stündliche increase (oder sum) und addieren die Stunden, die zu jedem lokalen Tag gehören:

// Node.js 18+: daily energy per local day (Europe/Istanbul) for the last 7 days
const tz = 'Europe/Istanbul';
const to = Date.now();
const from = to - 7 * 24 * 3600 * 1000;
const url = `https://${host}/tenant/${tenant}/api/telemetry/series?kind=iot_device&entityId=${device}`
  + `&keys=energy_kwh&from=${from}&to=${to}&bucket=1h&agg=increase`;
const res = await fetch(url, { headers: { Authorization: `Bearer ${key}` } });
const { series } = await res.json();
const days = {};
for (const p of series.energy_kwh) {
  const day = new Date(p.ts).toLocaleDateString('en-CA', { timeZone: tz }); // YYYY-MM-DD
  days[day] = (days[day] ?? 0) + p.value;
}
console.log(days);

Die erste Stunde des Zeitfensters zählt nur, was darin gestiegen ist. Beginnen Sie das Zeitfenster daher eine Stunde vor dem ersten benötigten lokalen Tag und verwerfen Sie diese Stunde. Eine Zone mit einer halbstündigen Abweichung benötigt 1m-Buckets, die höchstens 31 Tage zurückreichen.

Weitere Lese-Routen

RouteFunktion
GET /api/telemetry/kindsDie Arten von Messwerten Ihrer Organisation (zum Beispiel iot_device)
GET /api/iot/devices/{deviceId}/elementsDie Schlüssel eines Geräts (im Profil deklariert oder gesendet), höchstens 300, mit Bezeichnungen und Einheiten

Für Schreibzugriffe nutzen Geräte MQTT oder HTTP; die REST-API hat keine Schreibroute für Telemetrie. Siehe Geräte-HTTP-API und Telemetrie- und Attribute-API.