Diese Routen ermöglichen es einem Programm, die Regeln der Rules-Karte sowie den Manual-/Auto-Modus eines Ortes zu verwalten. Wie Regeln sich für Personen verhalten, wird erklärt in The Rules card und Manual and Auto modes. Die Rules-API ist überall dort verfügbar, wo die Rules-Karte verfügbar ist: Sie gehört zu Automation.
Pfade liegen unter https://<your host>/tenant/<tenantId>. Senden Sie bei jedem Aufruf Authorization: Bearer <API key>; siehe Authentication und REST API basics.
Routen
| Methode | Pfad | Berechtigung | Funktion |
|---|---|---|---|
| GET | /api/iot/rules?placeType=&placeId=&subtree= | iot_rules.read | Die Regeln eines Ortes (und mit subtree=true bei einem Asset alles darunter) |
| GET | /api/iot/rules/scope?placeType=&placeId= | iot_rules.read | Worauf eine Regel an diesem Ort verweisen darf: seine Geräte und deren Werte, Gerätprofile und deren Befehle |
| POST | /api/iot/rules/test | iot_rules.read | Prüft eine gespeicherte oder ungespeicherte Regel gegen die aktuell gespeicherten Werte; es wird nichts ausgeführt |
| POST | /api/iot/rules | iot_rules.manage | Eine Regel anlegen |
| GET | /api/iot/rules/{ruleId} | iot_rules.read | Eine Regel mit Definition und Status |
| PATCH | /api/iot/rules/{ruleId} | iot_rules.manage | Name oder Definition ändern |
| DELETE | /api/iot/rules/{ruleId} | iot_rules.manage | Regel und ihren Flow löschen |
| POST | /api/iot/rules/{ruleId}/enabled | iot_rules.manage | Regel ein- oder ausschalten |
| POST | /api/iot/rules/{ruleId}/run | iot_rules.run | Jetzt ausführen |
| GET | /api/iot/rules/{ruleId}/runs?limit= | iot_rules.read | Die letzten Läufe, neueste zuerst |
| GET | /api/iot/rule-modes/{placeType}/{placeId} | iot_rules.read | Der Modus des Ortes |
| PUT | /api/iot/rule-modes/{placeType}/{placeId} | iot_rules.mode | Ort in Manual setzen |
| DELETE | /api/iot/rule-modes/{placeType}/{placeId}?applyNow=true | iot_rules.mode | Zurück zu Auto |
placeType ist asset oder device; placeId ist die ID des Assets bzw. des Geräts.
Berechtigungen und API-Schlüssel
| Berechtigung | Standardrolle |
|---|---|
iot_rules.read | Benutzer |
iot_rules.run | Benutzer |
iot_rules.mode | Benutzer |
iot_rules.manage | Administrator |
Ein API-Schlüssel kann alle vier besitzen. Jeder Aufruf benötigt außerdem Zugriff auf den Ort, den die Regel oder der Modus betrifft, sodass Ihre Zugriffsrichtlinien einschränken können, welche Orte ein Schlüssel erreicht.
Eine Regel wird als Flow gespeichert, der im Namen des Mitglieds des Schlüssels bereitgestellt wird; daher muss der Schlüssel auch berechtigt sein, das zu tun, was die Regel tut:
| Die Regel hat | Der Schlüssel benötigt außerdem |
|---|---|
| Eine Aktion Befehl senden | Die Sendeberechtigung jeder Stufe, die der Befehl im Katalog des Gerätprofils hat (iot_rpc.send.basic, iot_rpc.send.privileged, iot_rpc.send.critical) |
| Ein Befehl mit hoher Auswirkung | automation.manage_privileged zusätzlich |
Der Schlüssel benötigt automation.manage nicht, um eine Regel zu speichern. Fehlt eine benötigte Berechtigung, antwortet das Speichern mit 403 „You do not hold the permission this rule needs: …“, wobei die fehlenden IDs in details.missing stehen. Stufen finden Sie unter Commands API.
Das Regelobjekt
{
"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
}
}
| Feld | Bedeutung |
|---|---|
home | Das Asset oder Gerät, zu dem die Regel gehört. Es kann nach dem Anlegen nicht geändert werden. |
enabled | Der eigene Schalter der Regel. Er ist getrennt von Manual: Die Rückkehr zu Auto schaltet nie eine Regel ein, die jemand ausgeschaltet hat. |
status | ok, oder needs_attention, wenn ein Gerät oder Ort, auf den sie verweist, gelöscht wurde. statusReason erklärt den Grund in Worten. |
flowId | Der Flow, als der die Regel läuft. In der Flow-API ist er nur lesbar. |
updatedAt | Millisekunden seit der Epoche |
Die Liste GET /api/iot/rules antwortet mit { "rules": [...], "can": {...} }. Jede Zeile enthält zusätzlich lastRun ({ at, text, ok } oder null) und nextAt (der nächste Start in Millisekunden für eine Regel mit Zeit-, Datums- oder Sonnen-Auslöser, sonst null). can gibt an, was der Aufrufer hier darf: manage, run, mode und sendCommands, jeweils true oder false.
Die Definition
Eine Definition hat vier Teile. Unbekannte Felder werden überall abgelehnt.
{
"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" }
}
Jeder Auslöser und jede Aktion hat eine id: Kleinbuchstaben, Ziffern, - und _, bis zu 24 Zeichen, innerhalb der Regel eindeutig. Ein Geräteverweis ist { "device": "<deviceId>" } für ein Gerät oder { "deviceType": "<deviceProfileId>" } für alle Geräte dieses Profils im Geltungsbereich des Hauses. Wochentage sind 1 (Montag) bis 7 (Sonntag). Zeiten sind HH:MM in der Zeitzone des Hauses. Schweregrade werden klein geschrieben: critical, major, minor, warning, info.
Wann (1 bis 10 Auslöser, jeder davon startet die Regel)
kind | Felder |
|---|---|
value | target, key, change (any, above, below, equals, not_equals, between, outside), value, value2 (die Obergrenze eines Bereichs), forSec (0 bis 86.400) |
status | target, to (online, offline, inactive) |
alarm | target (ein Geräteverweis oder { "home": true }), event (raised, cleared), optional minSeverity, alarmType |
time | at, optional days |
every | minutes (1 bis 1.440) |
sun | event (sunrise, sunset), optional offsetMin (-180 bis 180), days |
date | at, sowie daysOfMonth und/oder months, oder days (nicht beides, daysOfMonth und days) |
manual | Keine Felder: Die Regel startet nur über Jetzt ausführen |
Nur wenn (optional, eine Bedingung)
Eine Bedingung ist eine Gruppe, { "all": [...] }, { "any": [...] } oder { "not": {...} }, oder eine der folgenden:
kind | Felder |
|---|---|
value | target, key, op (>, >=, <, <=, ==, !=, between), value, value2 |
status | target, is (online, offline) |
alarm | target (oder { "home": true }), active (true oder false), optional minSeverity |
time | optional after, before, days |
sun | is (day, night) |
date | months, daysOfMonth, und/oder ein Fenster from und to (MM-DD, beides oder keines) |
holiday | is (true oder false): Heute ist ein Feiertag im Kalender Ihrer Organisation |
expr | expr: eine Formel, bis zu 500 Zeichen |
Die Bedeutung jedes Elements steht in Rules card: conditions und Time, sunrise/sunset, dates and holidays.
Dann (1 bis 20 Aktionen, in dieser Reihenfolge)
kind | Felder |
|---|---|
command | target, command (eine Methode des Katalogs des Profils), optional params |
setting | target, key, value |
notify | recipients (1 bis 20 aus { "kind": "user", "userId" }, { "kind": "role", "role": "OWNER" } (oder ADMIN, USER), { "kind": "team", "teamId" }), text (bis zu 1.000 Zeichen), optional channels |
alarm | op (raise, clear), target (oder { "home": true }), alarmType, optional severity |
wait | sec (1 bis 86.400) |
wait_until | condition, timeoutSec (1 bis 86.400), onTimeout (continue, stop) |
choose | branches (1 bis 5 aus { "if": condition, "then": [actions] }), optional else |
rule | op (enable, disable, run), rule (die ID einer anderen Regel). run muss der letzte Schritt sein. |
Was jede Aktion bewirkt, steht unter Regelkarte: Aktionen; channels wird unter Benachrichtigungen aus Regeln und Flows erklärt.
Optionen
| Feld | Werte |
|---|---|
overlap (erforderlich) | ignore, queue, parallel, restart |
max | 1 bis 10, nur mit queue oder parallel |
runInManual | true nur für eine Regel ohne Befehle, Einstellungen oder Regelaktionen |
Eine Regel anlegen
POST /api/iot/rules mit homeType, homeId, name (1 bis 120 Zeichen), definition und optional enabled (Standard true) und confirmed.
Eine Regel, die selbstständig handelt, zum Beispiel eine, die Befehle sendet oder Einstellungen ändert, muss bestätigt werden. Ohne "confirmed": true antwortet eine solche Regel mit 409 und details.needsConfirmation: true sowie den Gründen in details.reasons, dieselbe Bestätigung, die auch die Karte verlangt. Senden Sie sie erneut mit "confirmed": true. Das Senden von confirmed bei jedem Speichern einer Regel, die Sie handeln lassen wollen, ist unbedenklich.
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"}}}'
Die Antwort lautet 201 { "rule": {...} }. Eine Definition mit Problemen antwortet mit 422 und jedem Problem samt dem Pfad seiner Zeile:
{
"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." } ] }
}
Lesen Sie zuerst GET /api/iot/rules/scope, um die Geräte-IDs, Wertschlüssel und Katalogbefehle des Ortes zu erfahren. Eine Regel darf nur Geräte nennen, die im Umfang ihres Gebäudes liegen.
Testen, ändern, schalten, ausführen und löschen
| Aufruf | Body | Antwort |
|---|---|---|
POST /api/iot/rules/test | homeType, homeId, definition, optional name | { "result": { "triggers", "conditions", "actions", "mode", "wouldRun", "summary" } }. Es wird nichts gesendet oder geschrieben. |
PATCH /api/iot/rules/{ruleId} | name und/oder definition, optional confirmed | { "rule": {...} }. Dieselben Prüfungen wie beim Anlegen. |
POST /api/iot/rules/{ruleId}/enabled | { "enabled": true }, optional confirmed | { "rule": {...} } |
POST /api/iot/rules/{ruleId}/run | Keiner | 202 { "accepted": true, "entryId": "…" }. Bedingungen und Manuell gelten weiterhin. |
GET /api/iot/rules/{ruleId}/runs?limit=20 | Keiner | { "runs": [ { "at", "text", "ok" } ] }, Standard 20, höchstens 30 |
DELETE /api/iot/rules/{ruleId} | Keiner | 204 |
Eine Regel im Status needs_attention kann nicht eingeschaltet oder ausgeführt werden, bis sie mit einer gültigen Definition erneut gespeichert wird.
Manuell und Automatisch
GET /api/iot/rule-modes/{placeType}/{placeId} antwortet:
{ "mode": { "mode": "auto", "effective": "manual", "setOn": { "type": "asset", "id": "a1b2…" }, "until": 1762686000000, "setBy": "5d6e…", "setAt": 1762678800000, "reason": "Pump service" } }
mode ist die Einstellung des Ortes selbst; effective ist die tatsächlich geltende, Manuell, wenn der Ort oder ein darüberliegendes Objekt auf Manuell steht; setOn nennt dieses Objekt.
- Manuell:
PUTmit{ "until": <Millisekunden>, "reason": "…" }. Beide sind optional: Ohneuntilbleibt Manuell so lange aktiv, bis jemand zurückschaltet.untilmuss in der Zukunft und innerhalb eines Jahres liegen;reasondarf bis zu 500 Zeichen lang sein. Ein erneutes Senden ersetzt das Ende und den Grund. - Automatisch:
DELETE. Mit?applyNow=truestarten die Regeln des Ortes und aller darunterliegenden Objekte neu, ausgehend von den jetzt gespeicherten Werten; die Antwort{ "mode": {...}, "rearmed": n }zählt, was geweckt wurde. Ein Ort, der Manuell von einem darüberliegenden Objekt übernimmt, antwortet mit409.
Fehler
| Status | Meldung oder Grund |
|---|---|
| 400 | Validation error mit issues: ein Feld, das die Route nicht kennt, oder ein Wert mit falscher Form. „Wählen Sie ein Ende in der Zukunft, innerhalb eines Jahres.“ |
| 402 | QUOTA_EXCEEDED: Das Speichern der Regel würde ein Limit des Tarifs überschreiten; details.key nennt das Limit und details.limit seinen Wert |
| 403 | „Sie haben die Berechtigung nicht, die diese Regel benötigt: …“ (details.missing), oder der Schlüssel bzw. dessen Mitglied darf die Route oder den Ort nicht nutzen |
| 404 | „Diese Regel wurde nicht gefunden.“ / „Dieser Ort wurde nicht gefunden.“ / „Dieses Gerät wurde nicht gefunden.“ |
| 409 | details.needsConfirmation: Senden Sie confirmed: true. „Diese Regel ist ausgeschaltet; schalten Sie sie ein, um sie auszuführen.“ „Diese Regel braucht Aufmerksamkeit, bevor sie laufen kann.“ „Die Regel wurde geändert, während Sie sie bearbeiteten; laden Sie sie neu und speichern Sie erneut.“ „Dieser Ort folgt einem Ort darüber, der auf Manuell steht; schalten Sie diesen auf Automatisch.“ |
| 422 | details.problems: Die Definition kann nicht gespeichert werden. Zu den Codes gehören 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. |
| 503 | „Im Moment führt kein Worker die Regeln aus, daher würde die Regel nicht starten.“ (Jetzt ausführen) |
Der allgemeine Fehlerkörper und die Ratenlimits stehen unter Fehler und Ratenlimits.
Limits
| Limit | Wert |
|---|---|
| Name | 120 Zeichen |
| Auslöser | 10 |
| Bedingungen in einer Gruppe, Verschachtelung | 16, 4 Ebenen |
| Aktionen, einschließlich derer in Auswahlen | 20 |
| Zweige einer Auswahl, Verschachtelung von Auswahlen | 5, 2 Ebenen |
forSec, wait, wait_until | 24 Stunden |
| Empfänger der Benachrichtigung, Text | 20, 1.000 Zeichen |
max Läufe, die warten oder parallel laufen | 1 bis 10 |
| Laufverlauf | 30 Läufe |
Manuell until, reason | Innerhalb eines Jahres, 500 Zeichen |
Regeln zählen auf das Regel-Limit Ihres Tarifs, nicht auf das Flow-Limit. Die übrigen Limits (Geräte in einem Umfang, Geräte, auf die eine Zeile wirkt) stehen auf der Regelkarte.
Ereignisse statt Abfragen
Abonnieren Sie einen Webhook für rules.mode_changed (ein Ort wurde auf Manuell geschaltet, zurück auf Automatisch geschaltet oder sein Manuell-Modus endete) und rules.needs_attention (eine Regel wurde ausgeschaltet, weil etwas, das sie nennt, nicht mehr existiert). Die Nutzdaten stehen in der Referenz der Webhook-Ereignisse.

