Telemetri ve öznitelik API’si

Q: 200OK

{ "changed": [ "maxTempThreshold", "site_code" ] }

Q: 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" } ] } }

Q: 404Not Found

{ "message": "Device not found.", "code": "NOT_FOUND" }

Telemetri, cihazların zaman içinde ölçüp gönderdiği değerlerdir. Öznitelikler (attributes), bir cihazı tanımlayan adlandırılmış değerlerdir: cihazın kendi hakkında bildirdikleri (client), sizin onun hakkında sakladıklarınız (server) ve ona vermek 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 pencerede en fazla 50 anahtarın geçmişi
GET	`/api/telemetry/kinds`	`telemetry.read`	Organizasyonunuzdaki okuma türleri (örneğin `iot_device`)
GET	`/api/iot/devices/{deviceId}/elements`	`telemetry.read`	Bir cihazın anahtarları; profilinde tanımlanan ya da gönderilen, en fazla 300

Okuyamayacağınız bir cihaz, var olmayan bir cihazla aynı şekilde 404 yanıtı verir.

En son değerler

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

Tüm anahtarlar 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 ile 50 arası, 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 ile 10.000 arası	10,000

Gün kovaları UTC günleridir; kendi saat diliminizdeki günler için saatlik kovaları okuyup toplayın. Ham değerler en fazla 90 gün, dakikalık kovalar en fazla 31 gün saklanır. Parametrelerin tüm kuralları, ham değerlerde sayfalama ve çalışılmış örnekler The history API sayfasındadır.

Bir cihazın anahtarları

GET /api/iot/devices/{deviceId}/elements

Yanıt, cihazın elemanlarını etiketleriyle ve sahip olduğu anahtarları listeler; bunlar profilinde tanımlanan ya da gönderilen, en fazla 300 anahtardır. Cihaz profillerini okuma izniniz yoksa 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`	Her kapsamdaki öznitelikleri okur
POST	`/api/iot/devices/{deviceId}/attributes/server`	`iot_device.attributes.write`	Sunucu özniteliklerini yazar
POST	`/api/iot/devices/{deviceId}/attributes/shared`	`iot_device.attributes.write`	Paylaşılan öznitelikleri yazar; cihaz bunları alır
DELETE	`/api/iot/devices/{deviceId}/attributes/{scope}?keys=a,b`	`iot_device.attributes.write`	Sunucu ya da paylaşılan anahtarları siler

Client öznitelikleri yalnızca cihaz tarafından yazılır. client alanı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 cihazlardaki 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 ile 100 anahtar. Değer bir sayı, metin, boolean, nesne ya da 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 mesajı olarak iletilir ve denetim günlüğüne yazılır (anahtarlar yazılır, değerler yazılmaz).

İ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"
}

Paylaşılan öznitelikler, cihaz bağlıysa hemen gönderilir; değilse bağlandığında gönderilir. Paylaşılan bir 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 anahtarları içerir. Cihaz, silinen paylaşılan anahtarlar hakkında bilgilendirilir.

Öznitelik anahtarı kuralları

Kural	Ayrıntı
Karakterler	harfler, rakamlar, `_`, `.`, `-`; 1 ile 128; büyük/küçük harf duyarlı
Asla	`deleted`; `_` ile başlayan anahtar
Platform ya da cihaz için ayrılmıştır	`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 paylaşılan, 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 paylaşılan anahtarlar	en fazla 57 karakter
Değer boyutu	sunucu değerleri en fazla 64 KiB JSON; paylaşılan değerler cihazın downlink sınırına kadar; iç içelik 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: maxTempThreshold değerini sunucu ö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 yazılımının okuduğu bir paylaşılan anahtar yazın ve sonucu için client özniteliklerini izleyin.
Gece raporu: dünün saatlik series verisini okuyun ve veri ambarınızda saklayın.