Die History-API – Hermetry

Zwei Lese-Endpunkte liefern Ihnen Gerätetelemetrie: latest für den aktuellen Wert jedes Schlüssels und series für den Verlauf. Beide sind durch die Berechtigung zum Lesen der Telemetrie geschützt und liefern 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, Telemetrie zu lesen (und Geräte zu lesen, falls Sie diese auch auflisten). Die Voreinstellung Read-only reicht aus. Beschränken Sie die erlaubten Netzwerke des Schlüssels auf Ihre Server.
Die Geräte-ID (eine UUID) finden Sie 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

Parameter	Pflicht	Bedeutung
`kind`	Ja	`iot_device` für Gerätetelemetrie
`entityId`	Ja	Die Geräte-ID
`keys`	Nein	Durch Kommas getrennte Schlüssel, höchstens 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.

Zeitreihen

GET /tenant/{tenantId}/api/telemetry/series?kind=iot_device&entityId={deviceId}&keys=temperature&from=1759568400000&to=1759572000000&bucket=auto&agg=avg

Parameter	Pflicht	Werte	Standard
`kind`	Ja	`iot_device`
`entityId`	Ja	Die Geräte-ID
`keys`	Ja	Durch Kommas getrennt, 1 bis 50 Schlüssel, jeweils gemäß den Schlüsselregeln
`from`	Ja	Beginn, einschließlich (Epoche in ms)
`to`	Ja	Ende, ausschließlich (Epoche in ms); muss nach `from` liegen
`bucket`	Nein	`auto`, `raw`, `1m`, `1h`, `1d`	`auto`
`agg`	Nein	`avg`, `min`, `max`, `last`, `sum`, `count`, `increase`	`avg`
`limit`	Nein	Punkte pro Schlüssel, 1 bis 10.000	10,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 ist, die unter 10.000 Buckets bleibt.
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 pro Zeitstempel, der älteste zuerst; agg wird ignoriert.
Punkte sind nach Zeit sortiert. Ein Schlüssel ohne Daten liefert eine leere Liste.

Was jeder agg-Wert liefert, steht unter Aggregate und Rollups.

Grenzwerte

Grenze	Wert
Schlüssel pro Anfrage	50
Punkte pro Schlüssel	10.000 (`limit`)
Buckets in einem Zeitfenster	10.000 bei der gewählten Auflösung, sonst `400 range_too_large`
Rohwerte	Nur innerhalb Ihrer Rohdaten-Aufbewahrung (höchstens 90 Tage)
Minuten-Buckets	Nur innerhalb der Minuten-Aufbewahrung (höchstens 31 Tage)
Anfragen	Das API-Ratenlimit; bei Überschreitung `429` mit `Retry-After`. Siehe Fehler und Ratenlimits.

Fehler

Status	Antwortinhalt	Ursache
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 / 403		Kein gültiger Schlüssel oder der Schlüssel hat keine Berechtigung
404	`{ "message": "Not found" }`	Das Gerät existiert nicht, oder Sie dürfen es nicht lesen (dieselbe Antwort in beiden Fällen)
429		Ratenlimit

Rohwerte seitenweise abrufen

Eine Rohwert-Abfrage liefert höchstens 10.000 Punkte pro Schlüssel, der älteste zuerst. Um mehr zu lesen:

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

Für lange Zeiträume sollten Sie 1m– oder 1h-Buckets bevorzugen: Sie enthalten für jeden Bucket Minimum, Maximum, Summe, Anzahl und letzten Wert, jeweils als ein 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 pro 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 stündliches 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 Zeitzone mit einem halbstündigen Versatz benötigt 1m-Buckets, die höchstens 31 Tage zurückreichen.

Weitere Lese-Routen

Route	Funktion
`GET /api/telemetry/kinds`	Die Arten von Messwerten Ihrer Organisation (zum Beispiel `iot_device`)
`GET /api/iot/devices/{deviceId}/elements`	Die 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 Attribut-API.