Nouveau : le pare-feu IA surveille toute la plateforme et explique chaque incident en termes simples. Découvrez comment ça marche

API Rules

Listez, créez, testez, modifiez, activez ou désactivez, exécutez et supprimez les règles de la carte Rules par REST, et basculez un lieu entre Manuel et Auto.

Ces routes permettent à un programme de gérer les règles de la carte Règles et le mode Manuel / Auto d’un lieu. Le fonctionnement des règles pour les utilisateurs est expliqué dans La carte Règles et Modes Manuel et Auto. L’API des règles est disponible partout où se trouve la carte Règles : elle est incluse dans Automation.

Les chemins se trouvent sous https://<your host>/tenant/<tenantId>. Envoyez Authorization: Bearer <API key> à chaque appel ; voir Authentification et Bases de l’API REST.

Routes

MéthodeCheminPermissionFonction
GET/api/iot/rules?placeType=&placeId=&subtree=iot_rules.readLes règles d’un lieu (et, avec subtree=true sur un actif, de tout ce qui se trouve en dessous)
GET/api/iot/rules/scope?placeType=&placeId=iot_rules.readCe qu’une règle de ce lieu peut citer : ses appareils et leurs valeurs, les profils d’appareils et leurs commandes
POST/api/iot/rules/testiot_rules.readVérifie une règle enregistrée ou non enregistrée par rapport aux valeurs stockées actuellement ; rien ne s’exécute
POST/api/iot/rulesiot_rules.manageCréer une règle
GET/api/iot/rules/{ruleId}iot_rules.readUne règle avec sa définition et son statut
PATCH/api/iot/rules/{ruleId}iot_rules.manageModifie le nom ou la définition
DELETE/api/iot/rules/{ruleId}iot_rules.manageSupprime la règle et son flux
POST/api/iot/rules/{ruleId}/enablediot_rules.manageActive ou désactive la règle
POST/api/iot/rules/{ruleId}/runiot_rules.runExécuter maintenant
GET/api/iot/rules/{ruleId}/runs?limit=iot_rules.readLes dernières exécutions, les plus récentes en premier
GET/api/iot/rule-modes/{placeType}/{placeId}iot_rules.readLe mode du lieu
PUT/api/iot/rule-modes/{placeType}/{placeId}iot_rules.modePasse le lieu en Manuel
DELETE/api/iot/rule-modes/{placeType}/{placeId}?applyNow=trueiot_rules.modeRetour en Auto

placeType vaut asset ou device ; placeId est l’identifiant de l’actif ou de l’appareil.

Permissions et clés API

PermissionRôle par défaut
iot_rules.readUtilisateur
iot_rules.runUtilisateur
iot_rules.modeUtilisateur
iot_rules.manageAdministrateur

Une clé API peut détenir les quatre. Chaque appel nécessite aussi l’accès au lieu concerné par la règle ou le mode, de sorte que vos politiques d’accès peuvent restreindre les lieux auxquels une clé accède.

Une règle est enregistrée comme un flux déployé au nom du membre de la clé ; la clé doit donc aussi être autorisée à faire ce que fait la règle :

La règle comporteLa clé a aussi besoin de
Une action Envoyer une commandeLa permission d’envoi de chaque niveau que la commande possède dans le catalogue du profil d’appareil (iot_rpc.send.basic, iot_rpc.send.privileged, iot_rpc.send.critical)
Une commande à fort impactautomation.manage_privileged également

La clé n’a pas besoin de automation.manage pour enregistrer une règle. Sans une permission nécessaire, l’enregistrement répond 403 « Vous ne détenez pas la permission dont cette règle a besoin : … », avec les identifiants manquants dans details.missing. Voir API des commandes pour les niveaux.

L’objet règle

{
  "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
  }
}
ChampSignification
homeL’actif ou l’appareil auquel la règle appartient. Il ne peut pas être modifié après la création.
enabledL’interrupteur propre à la règle. Il est distinct du mode Manuel : repasser en Auto n’active jamais une règle désactivée par quelqu’un.
statusok, ou needs_attention lorsqu’un appareil ou un lieu qu’elle cite a été supprimé. statusReason explique pourquoi, en mots.
flowIdLe flux dans lequel la règle s’exécute. Il est en lecture seule dans l’API des flux.
updatedAtMillisecondes depuis l’époque

La liste GET /api/iot/rules répond { "rules": [...], "can": {...} }. Chaque ligne ajoute lastRun ({ at, text, ok } ou null) et nextAt (le prochain démarrage en millisecondes pour une règle avec un déclencheur horaire, de date ou solaire, sinon null). can indique ce que l’appelant peut faire ici : manage, run, mode et sendCommands, chacun à true ou false.

La définition

Une définition comporte quatre parties. Les champs inconnus sont refusés partout.

{
  "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" }
}

Chaque déclencheur et chaque action a un id : lettres minuscules, chiffres, - et _, jusqu’à 24 caractères, unique dans la règle. Une référence d’appareil est { "device": "<deviceId>" } pour un appareil, ou { "deviceType": "<deviceProfileId>" } pour chaque appareil de ce profil dans le périmètre du site. Les jours de la semaine vont de 1 (lundi) à 7 (dimanche). Les heures sont au format HH:MM dans le fuseau horaire du site. Les gravités sont en minuscules : critical, major, minor, warning, info.

Quand (1 à 10 déclencheurs, il suffit qu’un seul démarre la règle)

kindChamps
valuetarget, key, change (any, above, below, equals, not_equals, between, outside), value, value2 (la borne haute d’une plage), forSec (0 à 86 400)
statustarget, to (online, offline, inactive)
alarmtarget (une référence d’appareil ou { "home": true }), event (raised, cleared), minSeverity optionnel, alarmType
timeat, days optionnel
everyminutes (1 à 1 440)
sunevent (sunrise, sunset), offsetMin optionnel (-180 à 180), days
dateat, et daysOfMonth et/ou months, ou days (pas à la fois daysOfMonth et days)
manualAucun champ : la règle ne démarre que par Exécuter maintenant

Seulement si (facultatif, une condition)

Une condition est un groupe, { "all": [...] }, { "any": [...] } ou { "not": {...} }, ou l’une de celles-ci :

kindChamps
valuetarget, key, op (>, >=, <, <=, ==, !=, between), value, value2
statustarget, is (online, offline)
alarmtarget (ou { "home": true }), active (true ou false), minSeverity optionnel
timeafter, before, days optionnels
sunis (day, night)
datemonths, daysOfMonth, et/ou une fenêtre from et to (MM-DD, les deux ou aucun)
holidayis (true ou false) : aujourd’hui est un jour férié du calendrier de votre organisation
exprexpr : une formule, jusqu’à 500 caractères

La signification de chacun figure dans Carte Règles : conditions et Heure, lever/coucher du soleil, dates et jours fériés.

Alors (1 à 20 actions, dans l’ordre)

kindChamps
commandtarget, command (une méthode du catalogue du profil), params facultatif
settingtarget, key, value
notifyrecipients (de 1 à 20 de { "kind": "user", "userId" }, { "kind": "role", "role": "OWNER" } (ou ADMIN, USER), { "kind": "team", "teamId" }), text (jusqu’à 1 000 caractères), channels facultatif
alarmop (raise, clear), target (ou { "home": true }), alarmType, severity facultatif
waitsec (de 1 à 86 400)
wait_untilcondition, timeoutSec (de 1 à 86 400), onTimeout (continue, stop)
choosebranches (de 1 à 5 de { "if": condition, "then": [actions] }), else facultatif
ruleop (enable, disable, run), rule (l’identifiant d’une autre règle). run doit être la dernière étape.

Ce que fait chaque action est décrit dans Rules card : actions ; channels est expliqué dans Notifications from rules and flows.

Options

ChampValeurs
overlap (obligatoire)ignore, queue, parallel, restart
maxde 1 à 10, uniquement avec queue ou parallel
runInManualtrue uniquement pour une règle sans commandes, réglages ni actions de règle

Créer une règle

POST /api/iot/rules avec homeType, homeId, name (de 1 à 120 caractères), definition, et éventuellement enabled (par défaut true) et confirmed.

Une règle qui agit d’elle-même, par exemple une règle qui envoie des commandes ou modifie des réglages, doit être confirmée. Sans "confirmed": true, une telle règle répond 409 avec details.needsConfirmation: true et les motifs dans details.reasons, soit la même confirmation que celle demandée par la carte. Renvoyez-la avec "confirmed": true. Envoyer confirmed à chaque enregistrement d’une règle que vous destinez à agir est sans risque.

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"}}}'

La réponse est 201 { "rule": {...} }. Une définition comportant des problèmes répond 422 avec chaque problème et le chemin de sa ligne :

{
  "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." } ] }
}

Lisez d’abord GET /api/iot/rules/scope pour connaître les identifiants des appareils, les clés de valeur et les commandes du catalogue du lieu. Une règle ne peut nommer que des appareils présents dans le périmètre de son site.

Tester, modifier, activer, exécuter et supprimer

AppelCorpsRéponse
POST /api/iot/rules/testhomeType, homeId, definition, name facultatif{ "result": { "triggers", "conditions", "actions", "mode", "wouldRun", "summary" } }. Rien n’est envoyé ni écrit.
PATCH /api/iot/rules/{ruleId}name et/ou definition, confirmed facultatif{ "rule": {...} }. Mêmes contrôles qu’à la création.
POST /api/iot/rules/{ruleId}/enabled{ "enabled": true }, confirmed facultatif{ "rule": {...} }
POST /api/iot/rules/{ruleId}/runAucun202 { "accepted": true, "entryId": "…" }. Les conditions et le mode Manuel s’appliquent toujours.
GET /api/iot/rules/{ruleId}/runs?limit=20Aucun{ "runs": [ { "at", "text", "ok" } ] }, 20 par défaut, 30 au maximum
DELETE /api/iot/rules/{ruleId}Aucun204

Une règle en needs_attention ne peut être ni activée ni exécutée tant qu’elle n’a pas été enregistrée à nouveau avec une définition valide.

Manuel et Auto

GET /api/iot/rule-modes/{placeType}/{placeId} répond :

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

mode est le réglage du lieu lui-même ; effective est celui qui s’applique, Manuel lorsque le lieu ou un actif au-dessus de lui est en Manuel ; setOn désigne cet actif.

  • Manuel : PUT avec { "until": <millisecondes>, "reason": "…" }. Les deux champs sont facultatifs : sans until, le mode Manuel reste actif jusqu’à ce que quelqu’un le repasse en Auto. until doit être dans le futur et à moins d’un an ; reason comporte jusqu’à 500 caractères. Un nouvel envoi remplace la fin et le motif.
  • Auto : DELETE. Avec ?applyNow=true, les règles du lieu et de tout ce qui se trouve dessous repartent à partir des valeurs stockées à cet instant ; la réponse { "mode": {...}, "rearmed": n } compte ce qui a été réveillé. Un lieu qui suit le mode Manuel d’un actif au-dessus répond 409.

Erreurs

StatutMessage ou motif
400Validation error avec issues : un champ inconnu de la route, ou une valeur de forme incorrecte. « Choisissez une fin dans le futur, à moins d’un an. »
402QUOTA_EXCEEDED : l’enregistrement de la règle dépasserait une limite de votre offre ; details.key désigne la limite et details.limit sa valeur
403« Vous ne disposez pas de l’autorisation nécessaire à cette règle : … » (details.missing), ou la clé ou son membre ne peut pas utiliser cette route ou ce lieu
404« Cette règle est introuvable. » / « Ce lieu est introuvable. » / « Cet appareil est introuvable. »
409details.needsConfirmation : envoyez confirmed: true. « Cette règle est désactivée ; activez-la pour l’exécuter. » « Cette règle doit être vérifiée avant de pouvoir être exécutée. » « La règle a été modifiée pendant votre édition ; rechargez-la et enregistrez à nouveau. » « Ce lieu suit un lieu au-dessus de lui qui est en Manuel ; passez celui-ci en Auto. »
422details.problems : la définition ne peut pas être enregistrée. Les codes incluent 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« Aucun worker n’exécute les règles pour le moment, la règle ne démarrerait donc pas. » (Exécuter maintenant)

Le corps d’erreur général et les limites de débit sont décrits dans Errors and rate limits.

Limites

LimiteValeur
Nom120 caractères
Déclencheurs10
Conditions dans un groupe, imbrication16, 4 niveaux
Actions, y compris celles figurant dans des choix20
Branches d’un choix, imbrication des choix5, 2 niveaux
forSec, wait, wait_until24 heures
Destinataires de la notification, texte20, 1 000 caractères
max exécutions en attente ou en parallèle1 à 10
Historique d’exécution30 exécutions
Manuel : until, reasonMoins d’un an, 500 caractères

Les règles comptent dans la limite de règles de votre offre, et non dans sa limite de flux. Les autres limites (appareils d’un périmètre, appareils qu’une ligne pilote) figurent sur The Rules card.

Événements au lieu d’interrogation

Abonnez un webhook à rules.mode_changed (un lieu passé en Manuel, repassé en Auto, ou dont le mode Manuel a pris fin) et à rules.needs_attention (une règle désactivée parce qu’un élément qu’elle nomme n’existe plus). Les charges utiles sont décrites dans la Webhook event reference.