Alarms API

Bu rotalar bir bilet sistemi, bir operasyon merkezi veya bir betiğin alarmlarla çalışmasını sağlar. Alarmların nasıl davrandığı Alarmlar ve Alarmlarla çalışmak sayfalarında anlatılmıştır. Yollar https://<your host>/tenant/<tenantId> altındadır.

Rotalar

Varsayılan roller: okuma ve onaylama Kullanıcı izinleridir; çözme, sessizleştirme ve kuralları değiştirme Yönetici izinleridir.

Alarmları listele

GET /api/iot/alarms (sayfalar 1’den başlar). Bilinmeyen parametreler reddedilir.

Bir RESOLVED veya any listesi her zaman bir zaman aralığı okur; en fazla 92 gün: “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
}

Alarm zamanları epoch’tan itibaren milisaniye cinsindendir. resolveReason değerleri: clear (kuralı veya akışı temizledi), manual (bir kişi), originator_deleted (cihazı silindi).

GET /api/iot/alarms/{alarmId} aynı alanlarla birlikte kuralın çalışma kılavuzunu da içeren { "alarm": {...} } yanıtını verir. Başka bir kuruluşa ait bir alarm 404 döner.

Sayımlar

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

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

Yalnızca çözülmemiş alarmlar sayılır. Tüm kuruluş için deviceId parametresini bırakın.

Onaylama ve çözme

{
    "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 aynı gövdeyi alır ve aynı biçimde yanıt verir. Çözülmüş bir alarm kesindir; durum hâlâ geçerliyse kural yeni bir alarm açar. Bir CRITICAL alarmın elle çözülmesi denetim günlüğüne yazılır.

Durumu değiştirmeden not ekleyin:

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

Yanıt 201 { "ok": true } şeklindedir. Notlar zaman çizelgesinde görünür (GET .../events).

Alarm kuralları

GET /api/iot/alarm-rules/{profileId} { "rules": [...] } yanıtını verir. PUT profilin tüm kural kümesini değiştirir: bıraktığınız kurallar silinir ve açık alarmları çözülür.

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

Şemanın kuralları:

Koşul anahtarları profilin anahtarlarına göre denetlenir. Her alanın tam anlamı Cihaz profillerindeki alarm kuralları ve Alarm koşulları başvuru kılavuzu sayfalarında yer alır.

Sessizleştirmeler

Bir sessizleştirme gelecekte bitmeli ve en fazla 90 gün sürmelidir. Sessizleştirme sırasında alarmlar yine kaydedilir; kimseye bildirim gönderilmez. Bkz. Bakım için cihaz sessizleştirme.

Hatalar

Yoklama yerine olaylar

Değişiklikleri anında öğrenmek için bir webhook’u alarm.created, alarm.acknowledged ve alarm.cleared olaylarına abone edin. Yük içerikleri Webhook olay başvurusunda yer alır.