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
| Metot | Yol | İzin | İşlevi |
|---|---|---|---|
| GET | /api/iot/rules?placeType=&placeId=&subtree= | iot_rules.read | Bir yerin kuralları (bir varlıkta subtree=true ile altındaki her şeyin kuralları) |
| GET | /api/iot/rules/scope?placeType=&placeId= | iot_rules.read | Bu yerdeki bir kuralın adlandırabileceği şeyler: cihazları ve değerleri, cihaz profilleri ve komutları |
| POST | /api/iot/rules/test | iot_rules.read | Kaydedilmiş veya kaydedilmemiş bir kuralı şu anda saklanan değerlere göre denetler; hiçbir şey çalıştırılmaz |
| POST | /api/iot/rules | iot_rules.manage | Bir kural oluştur |
| GET | /api/iot/rules/{ruleId} | iot_rules.read | Tanımı ve durumuyla birlikte tek bir kural |
| PATCH | /api/iot/rules/{ruleId} | iot_rules.manage | Adı veya tanımı değiştir |
| DELETE | /api/iot/rules/{ruleId} | iot_rules.manage | Kuralı ve akışını sil |
| POST | /api/iot/rules/{ruleId}/enabled | iot_rules.manage | Kuralı açar veya kapatır |
| POST | /api/iot/rules/{ruleId}/run | iot_rules.run | Şimdi çalıştır |
| GET | /api/iot/rules/{ruleId}/runs?limit= | iot_rules.read | En son çalıştırmalar, en yenisi önce |
| GET | /api/iot/rule-modes/{placeType}/{placeId} | iot_rules.read | Yerin modu |
| PUT | /api/iot/rule-modes/{placeType}/{placeId} | iot_rules.mode | Yeri Manuel moda al |
| DELETE | /api/iot/rule-modes/{placeType}/{placeId}?applyNow=true | iot_rules.mode | Otomatik moda geri dön |
placeType asset veya device olur; placeId varlığın veya cihazın kimliğidir.
İzinler ve API anahtarları
| İzin | Varsayılan rol |
|---|---|
iot_rules.read | Kullanıcı |
iot_rules.run | Kullanıcı |
iot_rules.mode | Kullanıcı |
iot_rules.manage | Yö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çinde | Anahtarın ayrıca ihtiyacı olan |
|---|---|
| Bir Komut gönder eylemi | Komutun 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 komut | ayrı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
}
}
| Alan | Anlamı |
|---|---|
home | Kuralın ait olduğu varlık veya cihaz. Oluşturulduktan sonra değiştirilemez. |
enabled | Kuralın kendi anahtarı. Manuel’den ayrıdır: Otomatik moda dönmek, birinin kapattığı bir kuralı asla açmaz. |
status | ok veya, adı geçen bir cihaz ya da yer silindiğinde, needs_attention. statusReason nedenini açıklar. |
flowId | Kuralın çalıştığı akış. Akış API’sinde salt okunurdur. |
updatedAt | Epoch’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)
kind | Alanlar |
|---|---|
value | target, key, change (any, above, below, equals, not_equals, between, outside), value, value2 (aralığın üst sınırı), forSec (0 ila 86,400) |
status | target, to (online, offline, inactive) |
alarm | target (bir cihaz referansı veya { "home": true }), event (raised, cleared), isteğe bağlı minSeverity, alarmType |
time | at, isteğe bağlı days |
every | minutes (1 ila 1,440) |
sun | event (sunrise, sunset), isteğe bağlı offsetMin (-180 ila 180), days |
date | at, ve daysOfMonth ve/veya months, ya da days (hem daysOfMonth hem de days birlikte olamaz) |
manual | Alan 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:
kind | Alanlar |
|---|---|
value | target, key, op (>, >=, <, <=, ==, !=, between), value, value2 |
status | target, is (online, offline) |
alarm | target (veya { "home": true }), active (true veya false), isteğe bağlı minSeverity |
time | isteğe bağlı after, before, days |
sun | is (day, night) |
date | months, daysOfMonth ve/veya bir pencere from ve to (MM-DD, ikisi birden veya hiçbiri) |
holiday | is (true veya false): bugün kuruluşunuzun takvimindeki resmi bir tatildir |
expr | expr: 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)
kind | Alanlar |
|---|---|
command | target, command (profilin kataloğundaki bir yöntem), isteğe bağlı params |
setting | target, key, value |
notify | recipients ({ "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 |
alarm | op (raise, clear), target (veya { "home": true }), alarmType, isteğe bağlı severity |
wait | sec (1 ila 86.400) |
wait_until | condition, timeoutSec (1 ila 86.400), onTimeout (continue, stop) |
choose | branches ({ "if": condition, "then": [actions] } öğelerinden 1 ila 5 adet), isteğe bağlı else |
rule | op (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
| Alan | Değerler |
|---|---|
overlap (zorunlu) | ignore, queue, parallel, restart |
max | 1 ila 10, yalnızca queue veya parallel ile |
runInManual | true, 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övde | Yanıt |
|---|---|---|
POST /api/iot/rules/test | homeType, 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}/run | Yok | 202 { "accepted": true, "entryId": "…" }. Koşullar ve Manuel mod yine geçerlidir. |
GET /api/iot/rules/{ruleId}/runs?limit=20 | Yok | { "runs": [ { "at", "text", "ok" } ] }, varsayılan 20, en fazla 30 |
DELETE /api/iot/rules/{ruleId} | Yok | 204 |
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:
PUTile{ "until": <milisaniye>, "reason": "…" }. İkisi de isteğe bağlıdır:untilyoksa Manuel, biri tekrar Otomatik’e alana kadar sürer.untilgelecekte ve bir yıl içinde olmalıdır;reasonen fazla 500 karakter olabilir. Tekrar gönderilirse bitiş zamanı ve neden değiştirilir. - Otomatik:
DELETE.?applyNow=trueile 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 konum409yanıtı verir.
Hatalar
| Durum | Mesaj veya neden |
|---|---|
| 400 | issues 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.” |
| 402 | QUOTA_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ı.” |
| 409 | details.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.” |
| 422 | details.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ır | Değer |
|---|---|
| Ad | 120 karakter |
| Tetikleyiciler | 10 |
| Bir gruptaki koşullar, iç içe geçme | 16, 4 seviye |
| Eylemler, seçimlerin içindekiler dahil | 20 |
| Bir seçimin dalları, seçimlerin iç içe geçmesi | 5, 2 seviye |
forSec, wait, wait_until | 24 saat |
| Bildirim alıcıları, metin | 20, 1.000 karakter |
Bekleyen veya yan yana çalışan max çalıştırma | 1 ila 10 |
| Çalıştırma geçmişi | 30 çalıştırma |
Manuel until, reason | Bir 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.

