Alarms API

Diese Routen ermöglichen es einem Ticketsystem, einer Betriebszentrale oder einem Skript, mit Alarmen zu arbeiten. Wie sich Alarme verhalten, wird unter Alarme und Mit Alarmen arbeiten erklärt. Die Pfade liegen unter https://<your host>/tenant/<tenantId>.

Routen

Standardrollen: Lesen und Bestätigen sind Benutzerberechtigungen; Beheben, Stummschalten und Ändern der Regeln sind Administratorberechtigungen.

Alarme auflisten

GET /api/iot/alarms (Seiten ab 1). Unbekannte Parameter werden abgelehnt.

Eine Liste mit RESOLVED oder any erfordert immer einen Zeitraum von höchstens 92 Tagen: „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
}

Alarmzeiten sind Millisekunden seit der Epoche. resolveReason ist clear (seine Regel oder sein Ablauf hat ihn aufgehoben), manual (eine Person) oder originator_deleted (sein Gerät wurde gelöscht).

GET /api/iot/alarms/{alarmId} antwortet mit { "alarm": {...} } mit denselben Feldern sowie dem Runbook der Regel. Ein Alarm einer anderen Organisation ergibt 404.

Anzahlen

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

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

Nur Alarme, die nicht behoben sind, werden gezählt. Lassen Sie deviceId weg, um die gesamte Organisation zu erfassen.

Bestätigen und beheben

{
    "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 nimmt denselben Anfragetext entgegen und antwortet genauso. Ein behobener Alarm ist endgültig; ist die Bedingung weiterhin erfüllt, öffnet die Regel einen neuen Alarm. Das manuelle Beheben eines CRITICAL-Alarms wird im Audit-Log protokolliert.

Eine Notiz hinzufügen, ohne den Status zu ändern:

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

Die Antwort lautet 201 { "ok": true }. Notizen erscheinen im Verlauf (GET .../events).

Alarmregeln

GET /api/iot/alarm-rules/{profileId} antwortet mit { "rules": [...] }. PUT ersetzt den gesamten Regelsatz des Profils: Regeln, die Sie weglassen, werden gelöscht, und ihre offenen Alarme werden behoben.

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

Regeln des Schemas:

Bedingungsschlüssel werden gegen die Schlüssel des Profils geprüft. Die vollständige Bedeutung jedes Feldes steht unter Alarmregeln auf Geräteprofilen und Referenz der Alarmbedingungen.

Stummschaltungen

Eine Stummschaltung muss in der Zukunft enden und höchstens 90 Tage dauern. Alarme werden auch während der Stummschaltung aufgezeichnet; niemand wird benachrichtigt. Siehe Gerät für Wartung stummschalten.

Fehler

Ereignisse statt Abfragen

Abonnieren Sie einen Webhook für alarm.created, alarm.acknowledged und alarm.cleared, um Änderungen sofort zu erfahren. Die Nutzdaten stehen in der Referenz der Webhook-Ereignisse.