Yeni: Yapay zekâ güvenlik duvarı tüm platformu izliyor ve her olayı sade bir dille açıklıyor. Nasıl çalıştığını görün

Telemetri ve öznitelik API’si

Son değerleri ve geçmişi okuyun, bir cihazın anahtarlarını listeleyin ve server ile shared öznitelikleri REST üzerinden okuyun, yazın ve silin – anahtar kuralları ve hatalarla birlikte.

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öntemYolİzinİşlevi
GET/api/telemetry/latesttelemetry.readBir cihazın her anahtarının en son değeri
GET/api/telemetry/seriestelemetry.readBir zaman aralığında en fazla 50 anahtarın geçmişi
GET/api/telemetry/kindstelemetry.readKuruluşunuzdaki okuma türleri (örneğin iot_device)
GET/api/iot/devices/{deviceId}/elementstelemetry.readBir 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
ParametreDeğerlerVarsayılan
keys1 ila 50, virgülle ayrılmışzorunlu
from, toepoch’tan itibaren milisaniye; to, from değerinden sonra olmalızorunlu
bucketauto, raw, 1m, 1h, 1dauto
aggavg, min, max, last, sum, count, increaseavg
limitanahtar başına nokta, 1 ila 10.00010,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öntemYolİzinİşlevi
GET/api/iot/devices/{deviceId}/attributesiot_device.attributes.readTüm kapsamların özniteliklerini okur
POST/api/iot/devices/{deviceId}/attributes/serveriot_device.attributes.writeServer öznitelikleri yazar
POST/api/iot/devices/{deviceId}/attributes/sharediot_device.attributes.writeShared öznitelikleri yazar; cihaz bunları alır
DELETE/api/iot/devices/{deviceId}/attributes/{scope}?keys=a,biot_device.attributes.writeServer 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ı

KuralAyrıntı
Karakterlerharfler, rakamlar, _, ., -; 1 ila 128; büyük/küçük harf duyarlı
Asladeleted; _ 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 boyutuserver 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: maxTempThreshold değ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 series verisini okuyun ve veri ambarınızda saklayın.