Geçmiş API’si

Cihaz telemetrisini iki okuma endpoint’i sağlar: her anahtarın güncel değeri için latest, geçmiş için series. İkisi de telemetri okuma izninin arkasındadır ve yalnızca çağıranın okuyabildiği cihazları döndürür. Bu sayfa örneklerle birlikte başvuru kaynağıdır; anahtarlar ve yollar için REST API temelleri ve Kimlik doğrulama sayfalarına bakın.

Başlamadan önce

Telemetri okuma izni olan bir API anahtarı oluşturun (cihazları da listeleyecekseniz cihaz okuma izniyle). Read-only ön ayarı yeterlidir. Anahtarın izinli ağlarını sunucularınızla sınırlayın.
Cihaz kimliğini (bir UUID) cihaz sayfasında veya GET /api/iot/devices ile bulun.
Her yol kuruluşunuzun altındadır: https://<your host>/tenant/<tenantId>/api/....
Zamanlar, 1 Ocak 1970’ten bu yana geçen milisaniyedir, UTC.

Son değerler

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

Parametre	Zorunlu	Anlamı
`kind`	Evet	Cihaz telemetrisi için `iot_device`
`entityId`	Evet	Cihaz kimliği
`keys`	Hayır	Virgülle ayrılmış anahtarlar, en fazla 50. Tüm anahtarlar için boş bırakın.

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

Cihazın hiç göndermediği bir anahtar latest içinde yer almaz.

Seri

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

Parametre	Zorunlu	Değerler	Varsayılan
`kind`	Evet	`iot_device`
`entityId`	Evet	Cihaz kimliği
`keys`	Evet	Virgülle ayrılmış, 1 ile 50 anahtar; her biri anahtar kurallarına uymalıdır
`from`	Evet	Başlangıç, dahil (epoch ms)
`to`	Evet	Bitiş, hariç (epoch ms); `from` değerinden sonra olmalıdır
`bucket`	Hayır	`auto`, `raw`, `1m`, `1h`, `1d`	`auto`
`agg`	Hayır	`avg`, `min`, `max`, `last`, `sum`, `count`, `increase`	`avg`
`limit`	Hayır	Anahtar başına nokta sayısı, 1 ile 10.000 arası	10,000

{
  "kind": "iot_device",
  "entityId": "6f1c…",
  "resolution": "1m",
  "agg": "avg",
  "series": {
    "temperature": [
      { "ts": 1759568400000, "value": 21.2 },
      { "ts": 1759568460000, "value": 21.4 }
    ]
  }
}

resolution, gerçekte kullanılan çözünürlüktür. bucket=auto ile 24 saate kadar olan pencerelerde raw, sonrasında 10.000 bucket’ın altında kalan en ince seçenek olarak 1m, 1h veya 1d olur.
Bucket kullanıldığında ts bucket’ın başlangıcıdır (UTC hizalı), value ise toplulaştırılmış değerdir. Okuması olmayan bucket’lar sıfır değil, yok sayılır.
raw ile her kayıtlı değer, saklandığı gibi (sayı, metin, boolean, JSON) döndürülür; zaman damgası başına bir nokta, en eskiden başlayarak; agg yok sayılır.
Noktalar zamana göre sıralıdır. Verisi olmayan bir anahtar boş liste döndürür.

Her agg değerinin ne döndürdüğü için Toplulaştırmalar ve rollup’lar sayfasına bakın.

Limitler

Limit	Değer
İstek başına anahtar	50
Anahtar başına nokta	10.000 (`limit`)
Bir penceredeki bucket sayısı	Seçilen çözünürlükte 10.000, aksi halde `400 range_too_large`
Ham değerler	Yalnızca ham veri saklama sürenizin içinde (en fazla 90 gün)
Dakika bucket’ları	Yalnızca dakika saklama süresi içinde (en fazla 31 gün)
İstekler	API hız limiti; aşıldığında `Retry-After` ile `429`. Bkz. Hatalar ve hız limitleri.

Hatalar

Durum	Gövde	Neden
400	`{ "message": "to must be after from" }`	`to`, `from` değerinden sonra değil
400	`{ "message": "bad keys" }`	Boş `keys`, 50’den fazla anahtar veya anahtar kurallarına uymayan bir anahtar
400	`{ "message": "…", "code": "range_too_large" }`	Pencere için çok fazla bucket; daha kaba bir `bucket` kullanın
401 / 403		Geçerli anahtar yok veya anahtarın izni yok
404	`{ "message": "Not found" }`	Cihaz mevcut değil veya onu okuyamazsınız (ikisi için de aynı yanıt)
429		Hız limiti

Ham değerleri sayfalama

Bir raw okuma, anahtar başına en fazla 10.000 nokta döndürür, en eskiden başlayarak. Daha fazlasını okumak için:

Pencereniz için bucket=raw&limit=10000 isteyin.
Bir anahtar 10.000 nokta döndürdüyse, from değerini son noktanın ts + 1 değerine ayarlayarak yeniden isteyin.
Bir anahtar limit değerinden az nokta döndürene kadar tekrarlayın.

Uzun dönemler için 1m veya 1h bucket’larını tercih edin: her bucket’ın min, max, sum, count ve last değerlerini birer değer olarak tutarlar.

Örnekler

curl ile son değerler:

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

Son 7 günde bir basıncın saatlik maksimumu:

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"

Bir gün boyunca saatlik harcanan enerji (yalnızca artan bir kWh sayacı):

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"

Saat diliminizde günlük toplamlar

Gün bucket’ları UTC günleridir. Yerel bir gün için saatlik increase (veya sum) okuyun ve her yerel güne ait saatleri toplayın:

// 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);

Pencerenin ilk saati yalnızca o saat içinde artanı sayar; bu yüzden pencereyi ihtiyaç duyduğunuz ilk yerel günden bir saat önce başlatın ve o saati çıkarın. Yarım saatlik ofseti olan bir saat dilimi, en fazla 31 gün geriye uzanan 1m bucket’larına ihtiyaç duyar.

Diğer okuma rotaları

Rota	İşlevi
`GET /api/telemetry/kinds`	Kuruluşunuzdaki okuma türleri (örneğin `iot_device`)
`GET /api/iot/devices/{deviceId}/elements`	Bir cihazın anahtarları (profilinde tanımlı veya gönderilmiş), en fazla 300, etiketleri ve birimleriyle

Yazma için cihazlar MQTT veya HTTP kullanır; REST API’de telemetri yazma rotası yoktur. Bkz. Cihaz HTTP API ve Telemetri ve öznitelik API’si.