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
| Parameter | Pflicht | Bedeutung |
|---|---|---|
kind | Ja | iot_device für Gerätetelemetrie |
entityId | Ja | Die Geräte-ID |
keys | Nein | Durch 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
| Parameter | Pflicht | Werte | Standard |
|---|---|---|---|
kind | Ja | iot_device | |
entityId | Ja | Die Geräte-ID | |
keys | Ja | Durch Kommas getrennt, 1 bis 50 Schlüssel, jeder entspricht 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 je 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 }
]
}
}
resolutionist die tatsächlich verwendete Auflösung. Beibucket=autoist sierawfür Zeitfenster bis 24 Stunden, danach1m,1hoder1d, je nachdem, welche die feinste Auflösung unter 10.000 Buckets ergibt.- Bei einem Bucket ist
tsder Beginn des Buckets (UTC-ausgerichtet) undvalueder Aggregatwert. Buckets ohne Messwerte fehlen, sie sind nicht null. - Bei
rawwird jeder gespeicherte Wert so zurückgegeben, wie er gespeichert wurde (Zahlen, Text, Wahrheitswerte, JSON), ein Punkt je Zeitstempel, der älteste zuerst;aggwird 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
| Grenze | Wert |
|---|---|
| Schlüssel je Anfrage | 50 |
| Punkte je 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 Minutenspeicherung (höchstens 31 Tage) |
| Anfragen | Das API-Ratenlimit; bei Überschreitung 429 mit Retry-After. Siehe Fehler und Ratenlimits. |
Fehler
| Status | Inhalt | 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 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) |
| 429 | Ratenlimit |
Rohwerte seitenweise lesen
Ein Rohwert-Lesevorgang liefert höchstens 10.000 Punkte je Schlüssel, der älteste zuerst. Um mehr zu lesen:
- Fordern Sie
bucket=raw&limit=10000für Ihr Zeitfenster an. - Hat ein Schlüssel 10.000 Punkte geliefert, fordern Sie erneut an, mit
fromgleich demtsdes letzten Punkts + 1. - Wiederholen Sie dies, bis ein Schlüssel weniger als
limitPunkte 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
| 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 Attribute-API.

