Komutlar API’si

Bir komut (RPC), cihazdan bir işi yapmasını ister ve tek yönlü değilse cihazın yanıtını bekler. Her komut bir durumu olan bir istek olarak saklanır; böylece komutu şimdi gönderip sonucu daha sonra okuyabilirsiniz. Komutların uygulamada kullanıcılar için nasıl çalıştığı Cihazlara komut gönderme sayfasında anlatılmıştır. Yollar https://<your host>/tenant/<tenantId> altındadır.

Geliştirme aşamasında: Bir ağ geçidinin arkasındaki cihazlara (ağ geçidinin alt cihazlarına) komut gönderme geliştirme aşamasındadır. Kendi kendine bağlanan cihazlara komut gönderin.

Yollar

Kim neyi gönderebilir

Bir profilin kataloğundaki her komutun bir seviyesi vardır. Seviye izni belirler:

Yani bir API anahtarı yalnızca cihaz profilinin kataloğunda bulunan yöntemleri gönderebilir.

Komut gönder

{
    "method": "pump.start",
    "params": {
        "speed": 80
    },
    "timeoutMs": 15000
}

curl -X POST 'https://<your-host>/tenant/{tenantId}/api/iot/devices/{deviceId}/rpc' \
  -H 'Content-Type: application/json' \
  -d '{"method":"pump.start","params":{"speed":80},"timeoutMs":15000}'

{
    "rpc": {
        "rpcId": "c0de…",
        "deviceId": "6f1c…",
        "method": "pump.start",
        "status": "SUCCESSFUL",
        "outcome": null,
        "response": {
            "ok": true
        },
        "error": null,
        "tier": "privileged",
        "highImpact": false,
        "source": "api",
        "createdAt": "2026-11-09T09:00:00.000Z",
        "completedAt": "2026-11-09T09:00:01.200Z",
        "…": "…"
    }
}

{
    "rpc": {
        "rpcId": "c0de…",
        "status": "QUEUED",
        "…": "…"
    }
}

{
    "message": "You are not permitted to perform this action",
    "code": "FORBIDDEN"
}

{
    "message": "The device is disabled or quarantined; it takes no commands.",
    "code": "CONFLICT",
    "details": {
        "reason": "device_not_active"
    }
}

{
    "message": "Too many commands to this device; try again in a minute.",
    "code": "RATE_LIMIT_EXCEEDED",
    "details": {
        "reason": "device_rate_limited"
    }
}

• Tek yönlü (oneway: true): komut iletildiğinde başarılı sayılır; yanıt beklenmez.
• Kalıcı (persistent: true): cihaz çevrimdışıysa komut en fazla expiresInS süresince onu bekler, sonra EXPIRED durumuyla sona erer.
• wait: true beklemeyi zorunlu kılar (komut 30 saniyede tamamlanamıyorsa “A synchronous call waits at most 30 s; use wait: false for a longer timeout.” mesajıyla reddedilir); false her zaman hemen 202 yanıtı verir.
• Yüksek etkili komutlar "confirm": true gerektirir; katalogdaki komutta bir onay ifadesi varsa, confirmText içine o ifade yazılmalıdır. Bu olmadan şu mesaj döner: “This command needs confirm: true.” Bu komutlar gönderildiğinde ve sona erdiğinde denetim günlüğüne yazılır ve en fazla bir kez gönderilir.

Bu yolda bir idempotency anahtarı yoktur: her POST yeni bir komut oluşturur. Çağrınız ağda zaman aşımına uğrarsa, yeniden göndermeden önce cihazın geçmişini okuyun.

Durumlar

QUEUED → SENT → DELIVERED → SUCCESSFUL, ya da FAILED, TIMEOUT, EXPIRED, CANCELLED durumlarından biri.

outcome ayrıntı verir: running (cihaz uzun süren bir komutu kabul etti), unknown (zaman aşımı) veya late (yanıt, sonlandıktan sonra geldi). Sonuçlar varsayılan olarak 90 gün saklanır.

Sonuçları okuma

Durum nihai olana kadar GET /api/iot/rpc/{rpcId} adresini sorgulayın; ya da rpc.completed ve rpc.failed webhook olaylarına abone olun ve bir olay geldiğinde yanıtı okuyun. Bkz. Webhook olay başvurusu.

Bir cihazın geçmişi, en yeniden en eskiye:

GET /api/iot/devices/{deviceId}/rpc?status=FAILED&limit=50

page olmadan geçmiş bir imleçle okunur: status, method, from, to (tarihler), limit (1 ile 100 arası, varsayılan 25) ve cursor. Yanıt { "requests": [...], "nextCursor": "…" } biçimindedir; nextCursor değeri null olana kadar onu cursor olarak geri gönderin. page (0’dan başlar) ile liste, olağan liste kurallarını izler: pageSize, search, sort (method, status, source, createdAt, completedAt), status ve source virgüllü liste olarak, createdFrom, createdTo; yanıt { "requests": [...], "total": n } biçimindedir. Gizli parametreler her yanıtta maskelenir.

İptal

POST /api/iot/rpc/{rpcId}/cancel, QUEUED veya SENT durumundaki bir komutu CANCELLED durumuna taşır ve { "rpc": {...} } yanıtı verir. Diğer durumlarda 409 döner: “Only a queued or sent request can be cancelled.” İptal etmek, göndermekle aynı seviye izni gerektirir. İptal bir webhook göndermez.

Sınırlar

Reddetmeler

Komut kataloğu

Bir katalog komutunun şu alanları vardır: method, label (en fazla 120), description, paramsSchema (en fazla 50 alan; her biri label ve text, textarea, number, boolean, select, multi-select ya da json türünde type ile, isteğe bağlı olarak required, min, max, step, options alanlarıyla), maskedParams (gizli alanlar hiçbir zaman geri gösterilmez), tier (basic, privileged, critical), highImpact, oneway, long, defaultTimeoutMs, persistentDefault, confirmText (yalnızca yüksek etkili komutlar için).

{
  "method": "valve.set",
  "label": "Set valve position",
  "tier": "privileged",
  "paramsSchema": { "position": { "label": "Position (%)", "type": "number", "min": 0, "max": 100, "required": true } }
}

GET ...?format=export, kimlikleri olmayan { "commands": [...] } döndürür; bu, bir kataloğu başka bir profile kopyalamak için PUT ile geri gönderilir.