Neu: Die KI-Firewall überwacht die gesamte Plattform und erklärt jeden Vorfall in einfachen Worten. So funktioniert es

Rules-API

Regeln der Regelkarte per REST auflisten, anlegen, testen, ändern, ein- und ausschalten, ausführen und löschen sowie einen Ort zwischen Manuell und Automatisch umschalten.

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

MethodePfadBerechtigungFunktion
GET/api/iot/rules?placeType=&placeId=&subtree=iot_rules.readDie Regeln eines Ortes (und mit subtree=true bei einem Asset alles darunter)
GET/api/iot/rules/scope?placeType=&placeId=iot_rules.readWorauf eine Regel an diesem Ort verweisen darf: seine Geräte und deren Werte, Gerätprofile und deren Befehle
POST/api/iot/rules/testiot_rules.readPrüft eine gespeicherte oder ungespeicherte Regel gegen die aktuell gespeicherten Werte; es wird nichts ausgeführt
POST/api/iot/rulesiot_rules.manageEine Regel anlegen
GET/api/iot/rules/{ruleId}iot_rules.readEine Regel mit Definition und Status
PATCH/api/iot/rules/{ruleId}iot_rules.manageName oder Definition ändern
DELETE/api/iot/rules/{ruleId}iot_rules.manageRegel und ihren Flow löschen
POST/api/iot/rules/{ruleId}/enablediot_rules.manageRegel ein- oder ausschalten
POST/api/iot/rules/{ruleId}/runiot_rules.runJetzt ausführen
GET/api/iot/rules/{ruleId}/runs?limit=iot_rules.readDie letzten Läufe, neueste zuerst
GET/api/iot/rule-modes/{placeType}/{placeId}iot_rules.readDer Modus des Ortes
PUT/api/iot/rule-modes/{placeType}/{placeId}iot_rules.modeOrt in Manual setzen
DELETE/api/iot/rule-modes/{placeType}/{placeId}?applyNow=trueiot_rules.modeZurück zu Auto

placeType ist asset oder device; placeId ist die ID des Assets bzw. des Geräts.

Berechtigungen und API-Schlüssel

BerechtigungStandardrolle
iot_rules.readBenutzer
iot_rules.runBenutzer
iot_rules.modeBenutzer
iot_rules.manageAdministrator

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 hatDer Schlüssel benötigt außerdem
Eine Aktion Befehl sendenDie 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 Auswirkungautomation.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
  }
}
FeldBedeutung
homeDas Asset oder Gerät, zu dem die Regel gehört. Es kann nach dem Anlegen nicht geändert werden.
enabledDer eigene Schalter der Regel. Er ist getrennt von Manual: Die Rückkehr zu Auto schaltet nie eine Regel ein, die jemand ausgeschaltet hat.
statusok, oder needs_attention, wenn ein Gerät oder Ort, auf den sie verweist, gelöscht wurde. statusReason erklärt den Grund in Worten.
flowIdDer Flow, als der die Regel läuft. In der Flow-API ist er nur lesbar.
updatedAtMillisekunden 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)

kindFelder
valuetarget, key, change (any, above, below, equals, not_equals, between, outside), value, value2 (die Obergrenze eines Bereichs), forSec (0 bis 86.400)
statustarget, to (online, offline, inactive)
alarmtarget (ein Geräteverweis oder { "home": true }), event (raised, cleared), optional minSeverity, alarmType
timeat, optional days
everyminutes (1 bis 1.440)
sunevent (sunrise, sunset), optional offsetMin (-180 bis 180), days
dateat, sowie daysOfMonth und/oder months, oder days (nicht beides, daysOfMonth und days)
manualKeine 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:

kindFelder
valuetarget, key, op (>, >=, <, <=, ==, !=, between), value, value2
statustarget, is (online, offline)
alarmtarget (oder { "home": true }), active (true oder false), optional minSeverity
timeoptional after, before, days
sunis (day, night)
datemonths, daysOfMonth, und/oder ein Fenster from und to (MM-DD, beides oder keines)
holidayis (true oder false): Heute ist ein Feiertag im Kalender Ihrer Organisation
exprexpr: 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)

kindFelder
commandtarget, command (eine Methode des Katalogs des Profils), optional params
settingtarget, key, value
notifyrecipients (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
alarmop (raise, clear), target (oder { "home": true }), alarmType, optional severity
waitsec (1 bis 86.400)
wait_untilcondition, timeoutSec (1 bis 86.400), onTimeout (continue, stop)
choosebranches (1 bis 5 aus { "if": condition, "then": [actions] }), optional else
ruleop (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

FeldWerte
overlap (erforderlich)ignore, queue, parallel, restart
max1 bis 10, nur mit queue oder parallel
runInManualtrue 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

AufrufBodyAntwort
POST /api/iot/rules/testhomeType, 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}/runKeiner202 { "accepted": true, "entryId": "…" }. Bedingungen und Manuell gelten weiterhin.
GET /api/iot/rules/{ruleId}/runs?limit=20Keiner{ "runs": [ { "at", "text", "ok" } ] }, Standard 20, höchstens 30
DELETE /api/iot/rules/{ruleId}Keiner204

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: PUT mit { "until": <Millisekunden>, "reason": "…" }. Beide sind optional: Ohne until bleibt Manuell so lange aktiv, bis jemand zurückschaltet. until muss in der Zukunft und innerhalb eines Jahres liegen; reason darf bis zu 500 Zeichen lang sein. Ein erneutes Senden ersetzt das Ende und den Grund.
  • Automatisch: DELETE. Mit ?applyNow=true starten 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 mit 409.

Fehler

StatusMeldung oder Grund
400Validation 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.“
402QUOTA_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.“
409details.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.“
422details.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

LimitWert
Name120 Zeichen
Auslöser10
Bedingungen in einer Gruppe, Verschachtelung16, 4 Ebenen
Aktionen, einschließlich derer in Auswahlen20
Zweige einer Auswahl, Verschachtelung von Auswahlen5, 2 Ebenen
forSec, wait, wait_until24 Stunden
Empfänger der Benachrichtigung, Text20, 1.000 Zeichen
max Läufe, die warten oder parallel laufen1 bis 10
Laufverlauf30 Läufe
Manuell until, reasonInnerhalb 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.