Öznitelikler – Hermetry

Öznitelikler, bir cihazı tanımlayan veya yapılandıran adlandırılmış değerlerdir; zaman serisi olan telemetriden farklıdır. Bir yazılım sürümü, seri numarası, raporlama aralığı, cihaza özgü bir alarm sınırı veya bir oda numarası birer özniteliktir. Her öznitelik yalnızca güncel değerini ve en son ne zaman değiştiğini saklar.

Üç kapsam

Kapsam	Görünen adı	Yazan	Cihaz tarafından görülür	Tipik kullanım
Client	Client	cihaz	kendisi	Yazılım sürümü, IP adresi, yetenekler, uygulanan yapılandırma
Shared	Shared	bulut: kişiler, API, kurallar, akışlar, yazılım güncellemeleri	evet, değişiklikte itilir	İstenen yapılandırma (`cfg.`), yazılım teklifleri (`fw_`)
Server	Server	bulut	hiçbir zaman	Alarm kuralları için cihaza özgü sınırlar, notlar, varlık numaraları, gösterge paneli verileri

“Shared öznitelikleri cihaza gönderilir.” “Server öznitelikleri platformda kalır.” “Client öznitelikleri cihaz tarafından raporlanır ve burada değiştirilemez.”

Öznitelikler sekmesi

Cihazı ve Attributes sekmesini açın. Kapsamı seçin (Server, Shared, Client) ve Search keys and values alanını kullanın. Her satırda Key, Value, Updated alanında son güncelleme zamanı ve yapılandırma anahtarları için senkronizasyon durumu gösterilir.

Bir değer eklemek veya değiştirmek için Write server and shared device attributes iznine ihtiyacınız vardır (varsayılan olarak yöneticiler):

Add attribute (veya bir satırda Edit) seçin.
New key ve Value alanlarını JSON olarak girin: bir sayı (300), true veya false, tırnak içinde "metin", bir dizi veya bir nesne.
Kaydedin. Delete, Delete key? onayından sonra bir anahtarı kaldırır.

Write-only olarak işaretlenen değerler gizli yapılandırma değerleridir: ayarlanabilir, ancak geri okunamaz.

Anahtar kuralları

En fazla 128 karakter, A–Z a–z 0–9 _ . - karakterleri; büyük-küçük harfe duyarlıdır.
deleted hiçbir zaman anahtar olamaz ve _ ile başlayan anahtarlar platform için ayrılmıştır.
Kişiler, API ve akışlar, platformun veya cihazın sahip olduğu anahtarları yazamaz: fw_* ve current_fw_* (yazılım), .state veya .reason ile biten anahtarlar, cihaz kayıt anahtarları (cfg_rejected, cfg_applied_ts, cfg_hash, attr_error, rpc_result, cert_not_after, time_quality) ve session_limits.
cfg.* anahtarları yalnızca shared öznitelikleridir.
Diğer shared anahtarları en fazla 57 karakterdir; böylece cihazın <key>.reason yanıtı hâlâ 64 karakterlik cihaz anahtarı sınırına sığar.

Değer kuralları

Öğe	Sınır
İç içe geçme derinliği	8 seviye
Bir server veya client değeri	64 KiB
Bir shared değeri	Cihazın alt bağlantı (downlink) sınırına sığmalıdır (varsayılan 64 KiB, lisanslı cihazlar için 4 KiB)
`null`	Bir değer değildir: bunun yerine anahtarı silin

Cihaz tarafı

Send client attributes (yalnızca gönderilen anahtarlar değişir):

PUBLISH v1/attributes
{"current_fw_title": "boiler-fw", "current_fw_version": "26.10.2", "lan.ip": "192.168.1.1"}

Ask for attributes, örneğin her bağlantıdan sonra:

PUBLISH v1/attributes/req/7
{"clientKeys": "current_fw_version,lan.ip", "sharedKeys": "cfg.telemetry.interval_s"}

answer on v1/attributes/res/7
{"client": {...}, "shared": {...}}

Boş bir {} isteği tüm shared öznitelikleri döndürür. .* ile biten bir anahtar listesi girişi (örneğin cfg.*) o önekle başlayan tüm anahtarları ister.

v1/attributes/set üzerinde Receive shared changes alınır. Yalnızca değişen anahtarlar gönderilir. Kaldırılan bir anahtar {"deleted": ["cfg.wifi.guest.enabled"]} olarak gelir. Güncellemeleri idempotent uygulayın: bir mesaj iki kez gelebilir.

Her konu için bkz. MQTT topics and payload reference.

Yapılandırma anahtarları (`cfg.*`)

cfg. ile başlayan shared öznitelikleri istenen yapılandırmadır. Cihaz bunları uygular ve uygulanan değeri aynı anahtarla client özniteliği olarak raporlar. Hermetry ikisini karşılaştırır ve her anahtarın durumunu gösterir:

Durum	Anlamı
In sync	Cihaz, sizin ayarladığınız değeri raporlar.
Pending	Bir değer ayarladınız; cihaz henüz raporlamadı.
Rejected	Cihaz reddetti. Satır Reason: reason gösterir.
Drifted	Cihaz, ayarladığınızdan farklı bir değer raporlar.
Unknown key	Anahtar, profilin Configuration keys sekmesinde tanımlı değildir.

Cihazın uygulayamadığı bir anahtar, client özniteliği cfg_rejected içinde raporlanır:

{"cfg_rejected": {"cfg.wifi.radio0.channel": "out_of_range"}}

Nedenler: unknown_key, bad_type, out_of_range, apply_failed, read_only, busy.

Bir cihazın kabul ettiği anahtarları, tür, etiket ve sınırlarıyla birlikte profilin Configuration keys sekmesinde tanımlayın. Bkz. Device profiles. Lisanslı cihazlar tam yapılandırmaları için remote device settings kullanır.

Özniteliklerin kullanıldığı yerler

Cihaza özgü alarm sınırları. Bir alarm kuralının attribute:maxTemp değeri, cihazın maxTemp server özniteliğini okur (yoksa shared özniteliğini). Öznitelik olmayan bir cihazda bu sınır kontrol edilmez. Bkz. Alarm conditions reference.
Gösterge panelleri. Öznitelik kartları ve tabloları server ve shared özniteliklerini gösterir. Client öznitelikleri burada sunulmaz.
Akışlar. enrich.device bloğu, bir cihazın özniteliklerini bir iletiye ekler; akışlar öznitelik de yazabilir.
Gateway alt cihazları. Bir alt noktaya gönderilen shared özniteliği gateway tarafından uygulanır; gateway <key>.state ve <key>.reason raporlar.

API

Çağrı	İşlevi	İzin
`GET /tenant/{tenantId}/api/iot/devices/{deviceId}/attributes?scope=server&keys=a,b`	Öznitelikleri okur: `scope` `client`, `shared` veya `server` olabilir (atlanırsa hepsi), en fazla 100 anahtar	Cihaz özniteliklerini görüntüle
`POST …/attributes/server` veya `…/attributes/shared`	En fazla 100 anahtar yazar: `{"maxTemp": 80}`	Write server and shared device attributes
`DELETE …/attributes/server?keys=a,b`	Anahtarları sil	Write server and shared device attributes

Client öznitelikleri API üzerinden yazılamaz (405). API üzerinden yapılan bir yazma, saklanan değerin önüne geçer ve akışlarınıza bildirilir. Bkz. Telemetry and attributes API.

Denetim ve dışa aktarma

Her öznitelik kaydetme ve silme işlemi, anahtarlarla birlikte denetim günlüğüne ve cihazın Log sekmesine yazılır; değerler asla yazılmaz. Kuruluş dışa aktarımı öznitelikleri içerir; gizli görünen değerler maskelenir.