API Alarms

Ces routes permettent à un système de tickets, à un centre d’exploitation ou à un script de travailler avec les alarmes. Le fonctionnement des alarmes est expliqué dans Alarms et Working with alarms. Les chemins sont sous https://<your host>/tenant/<tenantId>.

Routes

Rôles par défaut : la lecture et l’acquittement sont des permissions User ; la résolution, la mise en sourdine et la modification des règles sont des permissions Admin.

Lister les alarmes

GET /api/iot/alarms (pages à partir de 1). Les paramètres inconnus sont refusés.

Une liste RESOLVED ou any lit toujours une plage de dates, d’au maximum 92 jours : « An alarm history range may span at most 92 days. »

{
  "items": [
    {
      "alarmId": "9a7e…",
      "type": "high_temperature",
      "severity": "CRITICAL",
      "status": "OPEN",
      "originator": { "type": "DEVICE", "id": "6f1c…", "name": "cold-room-2" },
      "deviceId": "6f1c…",
      "deviceName": "cold-room-2",
      "profileId": "a1b2…",
      "ruleId": "3c4d…",
      "title": "Temperature too high",
      "details": { "temperature": 9.4 },
      "topic": null,
      "startTs": 1762678800000,
      "openedAt": 1762678800000,
      "acknowledgedAt": null,
      "acknowledgedBy": null,
      "resolvedAt": null,
      "resolvedBy": null,
      "resolveReason": null,
      "occurrences": 3,
      "flapping": false,
      "isAuto": true
    }
  ],
  "total": 1
}

Les heures des alarmes sont exprimées en millisecondes depuis l’époque. resolveReason vaut clear (sa règle ou son flux l’a effacée), manual (une personne) ou originator_deleted (son appareil a été supprimé).

GET /api/iot/alarms/{alarmId} répond { "alarm": {...} } avec les mêmes champs, plus la procédure d’intervention de la règle. Une alarme d’une autre organisation renvoie un 404.

Nombres

GET /api/iot/alarms/counts?deviceId={deviceId}

{ "open": 4, "acknowledged": 1, "bySeverity": { "CRITICAL": 1, "MAJOR": 2, "MINOR": 0, "WARNING": 2, "INFO": 0 } }

Seules les alarmes non résolues sont comptées. Omettez deviceId pour l’ensemble de l’organisation.

Acquitter et résoudre

{
    "alarmIds": [
        "9a7e…",
        "b81f…"
    ],
    "note": "Technician on the way, ticket INC-4411"
}

curl -X POST 'https://<your-host>/tenant/{tenantId}/api/iot/alarms/acknowledge' \
  -H 'Content-Type: application/json' \
  -d '{"alarmIds":["9a7e…","b81f…"],"note":"Technician on the way, ticket INC-4411"}'

{
    "results": [
        {
            "alarmId": "9a7e…",
            "ok": true
        },
        {
            "alarmId": "b81f…",
            "ok": false,
            "reason": "not_active"
        }
    ]
}

POST /api/iot/alarms/resolve accepte le même corps et répond de la même façon. Une alarme résolue est définitive ; si la condition est toujours vraie, la règle ouvre une nouvelle alarme. La résolution manuelle d’une alarme CRITICAL est consignée dans le journal d’audit.

Ajouter une note sans modifier l’état :

POST /api/iot/alarms/{alarmId}/comments
{ "text": "Spare part ordered" }

La réponse est 201 { "ok": true }. Les notes apparaissent dans la chronologie (GET .../events).

Règles d’alarme

GET /api/iot/alarm-rules/{profileId} répond { "rules": [...] }. PUT remplace l’ensemble des règles du profil : les règles omises sont supprimées, et leurs alarmes ouvertes sont résolues.

{
  "rules": [
    {
      "type": "high_temperature",
      "title": "Temperature too high",
      "severities": [
        { "severity": "CRITICAL", "condition": { "key": "temperature", "op": ">", "value": { "attribute": "maxTempThreshold" } } },
        { "severity": "WARNING", "condition": { "key": "temperature", "op": ">", "value": 6 } }
      ],
      "debounce": { "mode": "duration", "raise": 300, "clear": 120 },
      "hysteresis": 0.5,
      "notify": { "recipients": [{ "kind": "role", "role": "ADMIN" }], "minSeverity": "WARNING", "repeatEverySec": 3600 },
      "runbook": "Check the door seal, then the compressor."
    },
    {
      "type": "device_offline",
      "title": "Sensor offline",
      "inactivity": { "afterSec": 900, "severity": "WARNING" }
    }
  ]
}

Règles du schéma :

Les clés de condition sont vérifiées par rapport aux clés du profil. La signification complète de chaque champ se trouve dans Alarm rules on device profiles et Alarm conditions reference.

Mises en sourdine

Une mise en sourdine doit se terminer dans le futur et durer au maximum 90 jours. Les alarmes continuent d’être enregistrées pendant la mise en sourdine ; personne n’est notifié. Voir Muting a device for maintenance.

Erreurs

Des événements plutôt que des interrogations

Abonnez un webhook à alarm.created, alarm.acknowledged et alarm.cleared pour être informé des changements au fur et à mesure. Les charges utiles sont décrites dans la Webhook event reference.