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

Kurallar API’si

Rules card kurallarını REST üzerinden listeleyin, oluşturun, test edin, değiştirin, açın veya kapatın, çalıştırın ve silin; bir konumu Manuel ile Otomatik arasında geçirin.

Bu rotalar bir programın Kurallar kartının kurallarını ve bir yerin Manuel / Otomatik modunu yönetmesini sağlar. Kuralların insanlar için nasıl davrandığı Kurallar kartı ve Manuel ve Otomatik modlar sayfalarında anlatılmıştır. Kurallar API’si Kurallar kartının bulunduğu her yerde kullanılabilir: Automation ile birlikte gelir.

Yollar https://<your host>/tenant/<tenantId> altındadır. Her çağrıda Authorization: Bearer <API key> gönderin; bkz. Kimlik doğrulama ve REST API temelleri.

Rotalar

MetotYolİzinİşlevi
GET/api/iot/rules?placeType=&placeId=&subtree=iot_rules.readBir yerin kuralları (bir varlıkta subtree=true ile altındaki her şeyin kuralları)
GET/api/iot/rules/scope?placeType=&placeId=iot_rules.readBu yerdeki bir kuralın adlandırabileceği şeyler: cihazları ve değerleri, cihaz profilleri ve komutları
POST/api/iot/rules/testiot_rules.readKaydedilmiş veya kaydedilmemiş bir kuralı şu anda saklanan değerlere göre denetler; hiçbir şey çalıştırılmaz
POST/api/iot/rulesiot_rules.manageBir kural oluştur
GET/api/iot/rules/{ruleId}iot_rules.readTanımı ve durumuyla birlikte tek bir kural
PATCH/api/iot/rules/{ruleId}iot_rules.manageAdı veya tanımı değiştir
DELETE/api/iot/rules/{ruleId}iot_rules.manageKuralı ve akışını sil
POST/api/iot/rules/{ruleId}/enablediot_rules.manageKuralı açar veya kapatır
POST/api/iot/rules/{ruleId}/runiot_rules.runŞimdi çalıştır
GET/api/iot/rules/{ruleId}/runs?limit=iot_rules.readEn son çalıştırmalar, en yenisi önce
GET/api/iot/rule-modes/{placeType}/{placeId}iot_rules.readYerin modu
PUT/api/iot/rule-modes/{placeType}/{placeId}iot_rules.modeYeri Manuel moda al
DELETE/api/iot/rule-modes/{placeType}/{placeId}?applyNow=trueiot_rules.modeOtomatik moda geri dön

placeType asset veya device olur; placeId varlığın veya cihazın kimliğidir.

İzinler ve API anahtarları

İzinVarsayılan rol
iot_rules.readKullanıcı
iot_rules.runKullanıcı
iot_rules.modeKullanıcı
iot_rules.manageYönetici

Bir API anahtarı dördünü de taşıyabilir. Her çağrı ayrıca kuralın veya modun ilgili olduğu yere erişim gerektirir; böylece erişim politikalarınız bir anahtarın hangi yerlere ulaşabileceğini daraltabilir.

Bir kural, anahtarın üyesi adına dağıtılan bir akış olarak kaydedilir; bu nedenle anahtar, kuralın yaptığı işleri yapmaya da izinli olmalıdır:

Kuralın içindeAnahtarın ayrıca ihtiyacı olan
Bir Komut gönder eylemiKomutun cihaz profilinin kataloğunda bulunduğu her kademe için gönderme izni (iot_rpc.send.basic, iot_rpc.send.privileged, iot_rpc.send.critical)
Yüksek etkili bir komutayrıca automation.manage_privileged

Bir kuralı kaydetmek için anahtarın automation.manage iznine ihtiyacı yoktur. Gerekli bir izin yoksa kaydetme, eksik kimliklerle birlikte details.missing içinde 403 “Bu kuralın ihtiyaç duyduğu izne sahip değilsiniz: …” yanıtını verir. Kademeler için bkz. Komutlar API’si.

Kural nesnesi

{
  "rule": {
    "ruleId": "3c4d…",
    "home": { "type": "asset", "id": "a1b2…" },
    "name": "Fan on when hot",
    "enabled": true,
    "definition": { "v": 1, "when": [], "then": [], "options": { "overlap": "ignore" } },
    "status": "ok",
    "statusReason": null,
    "flowId": "9e8f…",
    "updatedAt": 1762678800000
  }
}
AlanAnlamı
homeKuralın ait olduğu varlık veya cihaz. Oluşturulduktan sonra değiştirilemez.
enabledKuralın kendi anahtarı. Manuel’den ayrıdır: Otomatik moda dönmek, birinin kapattığı bir kuralı asla açmaz.
statusok veya, adı geçen bir cihaz ya da yer silindiğinde, needs_attention. statusReason nedenini açıklar.
flowIdKuralın çalıştığı akış. Akış API’sinde salt okunurdur.
updatedAtEpoch’tan itibaren milisaniye

GET /api/iot/rules listesi { "rules": [...], "can": {...} } yanıtını verir. Her satır lastRun ({ at, text, ok } veya null) ve zamanı, tarihi ya da güneş tetikleyicisi olan bir kural için bir sonraki başlangıcı milisaniye olarak veren nextAt (diğer durumlarda null) alanını ekler. can, çağıranın burada neler yapabileceğini belirtir: manage, run, mode ve sendCommands, her biri true veya false.

Tanım

Bir tanımın dört bölümü vardır. Tanımındaki bilinmeyen alanlar her yerde reddedilir.

{
  "v": 1,
  "when": [ { "id": "hot", "kind": "value", "target": { "device": "6f1c…" }, "key": "temperature", "change": "above", "value": 28, "forSec": 300 } ],
  "onlyIf": { "kind": "time", "after": "08:00", "before": "18:00", "days": [1, 2, 3, 4, 5] },
  "then": [ { "id": "fan", "kind": "command", "target": { "device": "7a2d…" }, "command": "fan.on" } ],
  "options": { "overlap": "ignore" }
}

Her tetikleyicinin ve eylemin bir id‘si vardır: küçük harf, rakam, - ve _, en fazla 24 karakter, kural içinde benzersiz. Bir cihaz referansı, tek bir cihaz için { "device": "<deviceId>" }, evin kapsamındaki o profildeki her cihaz için ise { "deviceType": "<deviceProfileId>" } biçimindedir. Haftanın günleri 1 (Pazartesi) ile 7 (Pazar) arasındadır. Saatler, evin saat diliminde HH:MM biçimindedir. Önem dereceleri küçük harftir: critical, major, minor, warning, info.

Ne zaman (1 ila 10 tetikleyici, bunlardan herhangi biri kuralı başlatır)

kindAlanlar
valuetarget, key, change (any, above, below, equals, not_equals, between, outside), value, value2 (aralığın üst sınırı), forSec (0 ila 86,400)
statustarget, to (online, offline, inactive)
alarmtarget (bir cihaz referansı veya { "home": true }), event (raised, cleared), isteğe bağlı minSeverity, alarmType
timeat, isteğe bağlı days
everyminutes (1 ila 1,440)
sunevent (sunrise, sunset), isteğe bağlı offsetMin (-180 ila 180), days
dateat, ve daysOfMonth ve/veya months, ya da days (hem daysOfMonth hem de days birlikte olamaz)
manualAlan yok: kural yalnızca Şimdi çalıştır ile başlar

Yalnızca eğer (isteğe bağlı, tek koşul)

Bir koşul bir grup, { "all": [...] }, { "any": [...] } veya { "not": {...} } ya da şunlardan biridir:

kindAlanlar
valuetarget, key, op (>, >=, <, <=, ==, !=, between), value, value2
statustarget, is (online, offline)
alarmtarget (veya { "home": true }), active (true veya false), isteğe bağlı minSeverity
timeisteğe bağlı after, before, days
sunis (day, night)
datemonths, daysOfMonth ve/veya bir pencere from ve to (MM-DD, ikisi birden veya hiçbiri)
holidayis (true veya false): bugün kuruluşunuzun takvimindeki resmi bir tatildir
exprexpr: en fazla 500 karakterlik bir formül

Her birinin anlamı Kurallar kartı: koşullar ve Zaman, gündoğumu/batımı, tarihler ve tatiller sayfalarında yer alır.

Sonra (1 ila 20 eylem, sırayla)

kindAlanlar
commandtarget, command (profilin kataloğundaki bir yöntem), isteğe bağlı params
settingtarget, key, value
notifyrecipients ({ "kind": "user", "userId" }, { "kind": "role", "role": "OWNER" } (veya ADMIN, USER), { "kind": "team", "teamId" } öğelerinden 1 ila 20 adet), text (en fazla 1.000 karakter), isteğe bağlı channels
alarmop (raise, clear), target (veya { "home": true }), alarmType, isteğe bağlı severity
waitsec (1 ila 86.400)
wait_untilcondition, timeoutSec (1 ila 86.400), onTimeout (continue, stop)
choosebranches ({ "if": condition, "then": [actions] } öğelerinden 1 ila 5 adet), isteğe bağlı else
ruleop (enable, disable, run), rule (başka bir kuralın kimliği). run son adım olmalıdır.

Her eylemin ne yaptığı Rules card: actions sayfasında anlatılır; channels ise Notifications from rules and flows sayfasında açıklanır.

Seçenekler

AlanDeğerler
overlap (zorunlu)ignore, queue, parallel, restart
max1 ila 10, yalnızca queue veya parallel ile
runInManualtrue, yalnızca komut, ayar veya kural eylemi içermeyen kurallar için

Kural oluşturma

homeType, homeId, name (1 ila 120 karakter), definition ile POST /api/iot/rules çağrısı yapın; isteğe bağlı olarak enabled (varsayılan true) ve confirmed de gönderebilirsiniz.

Kendi başına eylem yapan bir kural (örneğin komut gönderen veya ayar değiştiren) onaylanmalıdır. "confirmed": true olmadan, böyle bir kural 409 yanıtı verir; details.needsConfirmation: true ve nedenleri details.reasons içinde döner. Kartın istediği onayın aynısıdır. "confirmed": true ile yeniden gönderin. Eylem yapacağınız bir kuralı her kaydettiğinizde confirmed göndermek güvenlidir.

curl -X POST "https://<your host>/tenant/<tenantId>/api/iot/rules" \
  -H "Authorization: Bearer sk_live_…" \
  -H "Content-Type: application/json" \
  -d '{"homeType":"asset","homeId":"a1b2…","name":"Fan on when hot","confirmed":true,"definition":{"v":1,"when":[{"id":"hot","kind":"value","target":{"device":"6f1c…"},"key":"temperature","change":"above","value":28,"forSec":300}],"then":[{"id":"fan","kind":"command","target":{"device":"7a2d…"},"command":"fan.on"}],"options":{"overlap":"ignore"}}}'

Yanıt 201 { "rule": {...} } şeklindedir. Sorunlu bir tanım 422 yanıtı verir; her sorun ve satırının yolu ile birlikte listelenir:

{
  "message": "Type the value to compare with.",
  "code": "VALIDATION_ERROR",
  "details": { "problems": [ { "path": ["when", 0, "value"], "code": "value_missing", "message": "Type the value to compare with." } ] }
}

Önce, yerin cihaz kimliklerini, değer anahtarlarını ve katalog komutlarını öğrenmek için GET /api/iot/rules/scope çağrısını yapın. Bir kural yalnızca kendi konumunun kapsamındaki cihazları adlandırabilir.

Test etme, değiştirme, açma/kapama, çalıştırma ve silme

ÇağrıGövdeYanıt
POST /api/iot/rules/testhomeType, homeId, definition, isteğe bağlı name{ "result": { "triggers", "conditions", "actions", "mode", "wouldRun", "summary" } }. Hiçbir şey gönderilmez veya yazılmaz.
PATCH /api/iot/rules/{ruleId}name ve/veya definition, isteğe bağlı confirmed{ "rule": {...} }. Oluşturmayla aynı kontroller uygulanır.
POST /api/iot/rules/{ruleId}/enabled{ "enabled": true }, isteğe bağlı confirmed{ "rule": {...} }
POST /api/iot/rules/{ruleId}/runYok202 { "accepted": true, "entryId": "…" }. Koşullar ve Manuel mod yine geçerlidir.
GET /api/iot/rules/{ruleId}/runs?limit=20Yok{ "runs": [ { "at", "text", "ok" } ] }, varsayılan 20, en fazla 30
DELETE /api/iot/rules/{ruleId}Yok204

needs_attention durumundaki bir kural, geçerli bir tanımla yeniden kaydedilene kadar açılamaz veya çalıştırılamaz.

Manuel ve Otomatik

GET /api/iot/rule-modes/{placeType}/{placeId} şu yanıtı verir:

{ "mode": { "mode": "auto", "effective": "manual", "setOn": { "type": "asset", "id": "a1b2…" }, "until": 1762686000000, "setBy": "5d6e…", "setAt": 1762678800000, "reason": "Pump service" } }

mode, konumun kendisinin ayarlı olduğu moddur; effective ise geçerli olan moddur ve konum veya üstündeki bir varlık Manuel ise Manuel olur; setOn o varlığın adını verir.

  • Manuel: PUT ile { "until": <milisaniye>, "reason": "…" }. İkisi de isteğe bağlıdır: until yoksa Manuel, biri tekrar Otomatik’e alana kadar sürer. until gelecekte ve bir yıl içinde olmalıdır; reason en fazla 500 karakter olabilir. Tekrar gönderilirse bitiş zamanı ve neden değiştirilir.
  • Otomatik: DELETE. ?applyNow=true ile birlikte kullanıldığında konumun ve altındaki her şeyin kuralları, şimdi saklanan değerlerden yeniden başlar; { "mode": {...}, "rearmed": n } yanıtı uyandırılan sayıyı verir. Üstteki bir varlıktan Manuel modu izleyen bir konum 409 yanıtı verir.

Hatalar

DurumMesaj veya neden
400issues içeren Validation error: rotanın tanımadığı bir alan veya yanlış biçimde bir değer. “Gelecekte, bir yıl içinde bir bitiş zamanı seçin.”
402QUOTA_EXCEEDED: kuralı kaydetmek bir plan sınırını aşacaksa; details.key sınırın adını, details.limit ise değerini verir
403“Bu kuralın gerektirdiği izne sahip değilsiniz: …” (details.missing) veya anahtarın ya da üyesinin bu rotayı ya da konumu kullanma yetkisi yoktur
404“Bu kural bulunamadı.” / “Bu konum bulunamadı.” / “Bu cihaz bulunamadı.”
409details.needsConfirmation: confirmed: true gönderin. “Bu kural kapalı; çalıştırmak için açın.” “Bu kuralın çalışabilmesi için önce dikkat gerektiriyor.” “Kural siz düzenlerken değişti; yeniden yükleyip tekrar kaydedin.” “Bu konum, Manuel durumdaki üstteki bir konumu izliyor; o konumu Otomatik’e alın.”
422details.problems: tanım kaydedilemiyor. Kodlar arasında value_missing, range_missing, duplicate_id, device_out_of_scope, too_many_devices, bad_param, run_not_last, self_reference, run_in_manual_with_equipment, max_without_queue bulunur.
503“Şu anda kuralları çalıştıran bir işçi yok, bu nedenle kural başlamayacak.” (Şimdi çalıştır)

Genel hata gövdesi ve hız sınırları için Errors and rate limits sayfasına bakın.

Sınırlar

SınırDeğer
Ad120 karakter
Tetikleyiciler10
Bir gruptaki koşullar, iç içe geçme16, 4 seviye
Eylemler, seçimlerin içindekiler dahil20
Bir seçimin dalları, seçimlerin iç içe geçmesi5, 2 seviye
forSec, wait, wait_until24 saat
Bildirim alıcıları, metin20, 1.000 karakter
Bekleyen veya yan yana çalışan max çalıştırma1 ila 10
Çalıştırma geçmişi30 çalıştırma
Manuel until, reasonBir yıl içinde, 500 karakter

Kurallar, planınızın akış sınırına değil, kural sınırına sayılır. Diğer sınırlar (bir kapsamdaki cihazlar, bir satırın işlem yaptığı cihazlar) The Rules card sayfasında yer alır.

Sorgulamak yerine olaylar

Bir webhook’u rules.mode_changed (bir konum Manuel’e alındığında, Otomatik’e döndüğünde veya Manuel’i sona erdiğinde) ve rules.needs_attention (adlandırdığı bir şey ortadan kalktığı için bir kural kapatıldığında) olaylarına abone edin. Veri yükleri Webhook event reference sayfasındadır.