Yeni: Yapay zekâ güvenlik duvarı tüm platformu izliyor ve her olayı sade bir dille açıklıyor. Nasıl çalıştığını görün

Commands API

Cihazlara komut gönderin, sonuçlarını bekleyin veya yoklayın, iptal edin ve bir profilin komut kataloğunu REST üzerinden yönetin – alanlar, durumlar, sınırlar ve hatalar.

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 insanlar için nasıl çalıştığı Cihazlara komut gönderme bölümünde anlatılır. Yollar https://<your host>/tenant/<tenantId> altındadır.

Yollar

YöntemYolİzinİşlevi
POST/api/iot/devices/{deviceId}/rpciot_rpc.read artı komutun düzeyiKomut gönder
GET/api/iot/devices/{deviceId}/rpciot_rpc.readCihazın komut geçmişi
GET/api/iot/rpc/{rpcId}iot_rpc.readBir komut ve yanıtı
POST/api/iot/rpc/{rpcId}/canceliot_rpc.read artı komutun düzeyiSıradaki veya gönderilmiş bir komutu iptal et
GET/api/iot/devices/{deviceId}/rpc-commandsiot_rpc.send.basicBir gösterge paneli kontrolünün bu cihaza gönderebileceği komutlar
GET/api/iot/rpc-commands/{profileId}iot_rpc.readBir profilin komut kataloğu (içe aktarma biçimi için ?format=export)
POST/api/iot/rpc-commands/{profileId}iot_rpc.commands.manageKataloğa komut ekle
PUT/api/iot/rpc-commands/{profileId}iot_rpc.commands.manageTüm kataloğu değiştir
PATCH, DELETE/api/iot/rpc-commands/{profileId}/{commandId}iot_rpc.commands.manageBir komutu değiştir veya kaldır

Kim neyi gönderebilir

Bir profilin kataloğundaki her komutun bir düzeyi vardır. Düzey izni belirler:

DüzeyİzinVarsayılan rolBir API anahtarı bunu tutabilir mi?
basiciot_rpc.send.basicKullanıcıEvet
privilegediot_rpc.send.privilegedYöneticiEvet
criticaliot_rpc.send.criticalYöneticiEvet
raw (kataloğda olmayan bir yöntem)iot_rpc.send.rawSahipHayır

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

Komut gönder

POST/tenant/{tenantId}/api/iot/devices/{deviceId}/rpc

Alanlar: method (zorunlu, namespace.verb, en fazla 64 karakter), params (herhangi bir JSON, en fazla 16 KiB), oneway, persistent, timeoutMs (1.000 ile 600.000 arası; varsayılan, kataloğun veya profilin değeri, yoksa 10.000), expiresInS (1 ile 604.800 arası, kalıcı bir komut için; varsayılan 86.400), wait, confirm, confirmText, source (api, console veya dashboard_control). Zaman aşımı en fazla 30 saniye olan, çift yönlü ve kalıcı olmayan bir komut sonlanmasını bekler ve 200 yanıtı verir; diğer her durumda 202 yanıtı verilir ve komut çalışmaya devam eder.

İstek gövdesi application/json

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

Örnek curl

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

Yanıtlar

200OK
{
    "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",
        "…": "…"
    }
}
202Accepted
{
    "rpc": {
        "rpcId": "c0de…",
        "status": "QUEUED",
        "…": "…"
    }
}
403Forbidden
{
    "message": "You are not permitted to perform this action",
    "code": "FORBIDDEN"
}
409Conflict
{
    "message": "The device is disabled or quarantined; it takes no commands.",
    "code": "CONFLICT",
    "details": {
        "reason": "device_not_active"
    }
}
429Too Many Requests
{
    "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ı olur; yanıt beklenmez.
  • Kalıcı (persistent: true): cihaz çevrimdışıysa komut en fazla expiresInS süre boyunca onu bekler, sonra EXPIRED durumuyla sona erer.
  • wait: true beklemeyi zorunlu kılar (komut 30 saniyede tamamlanamazsa “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ın "confirm": true gerekir; katalogdaki komutta bir onay ifadesi varsa, confirmText içinde yazılan ifade de gerekir. Bunlar olmadan: “This command needs confirm: true.” Gönderildiklerinde ve sona erdiklerinde denetim günlüğüne yazılırlar ve en fazla bir kez gönderilirler.

Bu yolda 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 veya şunlardan biri: FAILED, TIMEOUT, EXPIRED, CANCELLED.

DurumAnlamı
SUCCESSFULYanıt geldi veya tek yönlü bir komut iletildi
FAILEDCihaz reddetti veya komut gönderilemedi
TIMEOUTZamanında yanıt gelmedi. Sonuç bilinmiyor: cihaz işlemi yapmış olabilir. outcome değeri unknowndur.
EXPIREDSon kullanma süresinden önce cihaza hiç ulaşmadı
CANCELLEDSıradayken veya gönderilmişken iptal edildi

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

Sonuçları okuma

Durum son hale gelene kadar GET /api/iot/rpc/{rpcId} çağrısını tekrarlayın veya rpc.completed ve rpc.failed webhook olaylarına abone olup bir yanıt geldiğinde 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ş 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 cursor olarak geri gönderin. page (0’dan başlayarak) ile liste, alışılmış liste kurallarını izler: pageSize, search, sort (method, status, source, createdAt, completedAt), status ve source virgülle ayrılmış listeler 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 geçirir ve { "rpc": {...} } yanıtı verir. Diğer durumlar: 409 “Only a queued or sent request can be cancelled.” İptal etmek, göndermekle aynı düzey iznini gerektirir. İptal webhook göndermez.

Sınırlar

SınırVarsayılan
Cihaz başına komutDakikada 10 (429, Retry-After: 60)
Kuruluş başına komutDakikada 600 (429 “Too many requests for your plan. Please upgrade or try again later.”)
Parametreler16 KiB JSON
Saklanan yanıt64 KiB
Profil kataloğu başına komut200

Reddetmeler

Durumdetails.reasonMesaj
400bad_paramsParametreler komutla eşleşmiyor.
400wait_too_longA synchronous call waits at most 30 s; use wait: false for a longer timeout.
400confirm_required, confirm_text_mismatchThis command needs confirm: true. / The typed confirmation does not match.
400method_refusedFabrika ayarlarına dönme, eşleştirme, Wi-Fi unutma ve bulut bağlantısını unutma buluttan asla gönderilmez.
400payload_too_largeİstek cihazın kabul ettiğinden büyük.
403rpc_method_reservedYöntem kendi modülüne aittir (örneğin uzaktan erişim) ve yalnızca o modül tarafından gönderilir; details.owner modülün adını verir.
404Cihaz bulunamadı.
409rpc_not_supported_by_profileCihaz profili yalnızca RPC taşımayan Legacy konularını destekler.
409device_not_activeCihaz devre dışı bırakılmış veya karantinaya alınmıştır.
409not_cancellableYalnızca sıradaki veya gönderilmiş bir istek iptal edilebilir.
429device_rate_limitedBu cihaza çok fazla komut; bir dakika sonra tekrar deneyin.

Komut kataloğu

Bir katalog komutunun şu alanları vardır: method, label (en fazla 120), description, paramsSchema (en fazla 50 alan; her alanın label değeri ve text, textarea, number, boolean, select, multi-select veya json türünden bir type değeri vardır; isteğe bağlı olarak required, min, max, step, options da bulunabilir), maskedParams (gizli alanlar geri gösterilmez), tier (basic, privileged, critical), highImpact, oneway, long, defaultTimeoutMs, persistentDefault, confirmText (yalnızca yüksek etkili komutlarda).

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

GET ...?format=export ifadesi, kimlik (id) içermeyen { "commands": [...] } yanıtını döndürür; bu yanıt, bir kataloğu başka bir profile kopyalamak için PUT isteğiyle geri gönderilebilir.