Telemetri, cihazların zaman içinde ölçüp gönderdiği verilerdir. Öznitelikler, bir cihazı tanımlayan adlandırılmış değerlerdir: cihazın kendisi hakkında bildirdikleri (client), sizin onun hakkında sakladıklarınız (server) ve ona sahip olmasını istediğiniz değerler (shared). Bu sayfa her ikisi için REST rotalarını listeler. Yollar https://<your host>/tenant/<tenantId> altındadır.
REST API telemetriyi yalnızca okur, asla yazmaz. Cihazlar telemetriyi MQTT veya HTTP üzerinden yazar; akışlar türetilmiş değerleri Save telemetry ile yazar. Bkz. Device HTTP API ve Derived values.
Telemetri rotaları
| Yöntem | Yol | İzin | İşlevi |
|---|---|---|---|
| GET | /api/telemetry/latest | telemetry.read | Bir cihazın her anahtarının en son değeri |
| GET | /api/telemetry/series | telemetry.read | Bir zaman aralığında en fazla 50 anahtarın geçmişi |
| GET | /api/telemetry/kinds | telemetry.read | Kuruluşunuzdaki okuma türleri (örneğin iot_device) |
| GET | /api/iot/devices/{deviceId}/elements | telemetry.read | Bir cihazın anahtarları; cihaz profilinde tanımlı ya da gönderilmiş, en fazla 300 |
Okuma izniniz olmayan bir cihaz, var olmayan bir cihazla aynı şekilde 404 yanıtı verir.
Son değerler
GET /api/telemetry/latest?kind=iot_device&entityId={deviceId}&keys=temperature,humidity
Her anahtar için keys alanını boş bırakın (en fazla 50).
{
"kind": "iot_device",
"entityId": "6f1c…",
"latest": {
"temperature": { "ts": 1762681200000, "value": 21.5 },
"humidity": { "ts": 1762681200000, "value": 40 }
}
}
Geçmiş
GET /api/telemetry/series?kind=iot_device&entityId={deviceId}&keys=temperature&from=1762594800000&to=1762681200000&bucket=1h&agg=max
| Parametre | Değerler | Varsayılan |
|---|---|---|
keys | 1 ila 50, virgülle ayrılmış | zorunlu |
from, to | epoch’tan itibaren milisaniye; to, from değerinden sonra olmalı | zorunlu |
bucket | auto, raw, 1m, 1h, 1d | auto |
agg | avg, min, max, last, sum, count, increase | avg |
limit | anahtar başına nokta, 1 ila 10.000 | 10,000 |
Gün bucket’ları UTC günleridir: kendi saat diliminizdeki günler için saatlik bucket’ları okuyup toplayın. Ham değerler en fazla 90 gün, dakikalık bucket’lar en fazla 31 gün tutulur. Parametre kurallarının tamamı, ham değerlerde sayfalama ve çalışılmış örnekler History API sayfasındadır.
Bir cihazın anahtarları
GET /api/iot/devices/{deviceId}/elements
Yanıt, cihazın etiketleriyle birlikte elementlerini ve sahip olduğu anahtarları listeler; bunlar cihaz profilinde tanımlı ya da gönderilmiş olup en fazla 300’dür. Cihaz profillerini okuma izni olmadan yalnızca cihazın gönderdiği anahtarlar listelenir.
Öznitelik rotaları
| Yöntem | Yol | İzin | İşlevi |
|---|---|---|---|
| GET | /api/iot/devices/{deviceId}/attributes | iot_device.attributes.read | Tüm kapsamların özniteliklerini okur |
| POST | /api/iot/devices/{deviceId}/attributes/server | iot_device.attributes.write | Server öznitelikleri yazar |
| POST | /api/iot/devices/{deviceId}/attributes/shared | iot_device.attributes.write | Shared öznitelikleri yazar; cihaz bunları alır |
| DELETE | /api/iot/devices/{deviceId}/attributes/{scope}?keys=a,b | iot_device.attributes.write | Server veya shared anahtarlarını siler |
Client öznitelikleri yalnızca cihaz tarafından yazılır. client kapsamına yazma 405 yanıtı verir: “Client attributes are written by the device only.”
Okuma
GET /api/iot/devices/{deviceId}/attributes?scope=server&keys=maxTempThreshold,site_code
scope değeri client, shared veya server olabilir (büyük/küçük harf fark etmez); üçü için boş bırakın. keys en fazla 100 anahtar içerir.
{
"attributes": {
"client": { "fw_version": { "value": "2.4.1", "updatedAt": 1762594800000 } },
"shared": { "reportInterval": { "value": 60, "updatedAt": 1762500000000 } },
"server": { "maxTempThreshold": { "value": 8, "updatedAt": 1762400000000 } }
}
}
Bir cihazın Settings sekmesinin yönettiği ayarlar (bölümlere göre ayar alan cihazlarda cfg.* anahtarları) burada gösterilmez; bunları cihaz ayar rotaları üzerinden okuyun, bkz. Firmware and device settings API.
Yazma
POST/tenant/{tenantId}/api/iot/devices/{deviceId}/attributes/server
Anahtar ve değerlerden oluşan düz bir JSON nesnesi: istek başına 1 ila 100 anahtar. Bir değer sayı, metin, boolean, nesne veya liste olabilir, ancak null olamaz (bunun yerine anahtarı silin). Yalnızca değeri değişen anahtarlar saklanır; yanıt bunları adlandırır. Her değişiklik akışlara attributes_updated iletisi olarak ulaşır ve denetim günlüğüne yazılır (değerler değil, anahtarlar).
İstek gövdesi application/json
{
"maxTempThreshold": 8,
"site_code": "IST-04"
}
Örnek curl
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"}'
Yanıtlar
200OK
{
"changed": [
"maxTempThreshold",
"site_code"
]
}
400Bad Request
{
"message": "One or more attribute keys are invalid or reserved.",
"code": "VALIDATION_ERROR",
"details": {
"reason": "keys_invalid",
"keys": [
{
"key": "fw_title",
"reason": "reserved"
}
]
}
}
404Not Found
{
"message": "Device not found.",
"code": "NOT_FOUND"
}
Shared öznitelikler, cihaz bağlıysa hemen gönderilir; değilse bağlandığında gönderilir. Bir shared değer, cihaz profilinin downlink sınırına sığmalıdır: “An attribute value is larger than the device’s downlink limit.” (details.reason = value_too_large).
Silme
DELETE /api/iot/devices/{deviceId}/attributes/shared?keys=reportInterval,mode
Yanıt { "deleted": ["mode", "reportInterval"] } biçimindedir; var olan anahtarlardır. Bir cihaza silinen shared anahtarlar bildirilir.
Öznitelik anahtarı kuralları
| Kural | Ayrıntı |
|---|---|
| Karakterler | harfler, rakamlar, _, ., -; 1 ila 128; büyük/küçük harf duyarlı |
| Asla | deleted; _ ile başlayan anahtar |
| Platform veya cihaz için ayrılmış | fw_*, current_fw_*, .state ya da .reason ile biten anahtarlar ve cihazın kendi kayıt anahtarları (cfg_rejected, cfg_applied_ts, cfg_hash, attr_error, rpc_result, cert_not_after, time_quality) |
cfg.* | İstenen yapılandırma: yalnızca shared, en fazla 128 karakter. Ayarları Settings sekmesinde yönetilen bir cihazda yazma 409 yanıtı verir: “This device’s configuration (cfg.*) is managed in its Settings; change it there.” |
| Diğer shared anahtarları | en fazla 57 karakter |
| Değer boyutu | server değerleri en fazla 64 KiB JSON; shared değerleri cihazın downlink sınırına kadar; iç içe geçme en fazla 8 seviye |
Her kapsamın ne için olduğu için Attributes, tam liste için Reserved keys and attributes sayfasına bakın.
Tipik kullanımlar
- ERP veya MES’ten cihaz bazlı limitler:
maxTempThresholddeğerini server özniteliği olarak yazın; alarm kuralları bununla karşılaştırma yapabilir. Bkz. Alarm conditions reference. - Üçüncü taraf bir cihaz için istenen ayarlar: cihazın firmware’inin okuduğu bir shared anahtarı yazın ve sonucu için client özniteliklerini izleyin.
- Gecelik rapor: dünün saatlik
seriesverisini okuyun ve veri ambarınızda saklayın.

