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öntem | Yol | İzin | İşlevi |
|---|---|---|---|
| POST | /api/iot/devices/{deviceId}/rpc | iot_rpc.read artı komutun düzeyi | Komut gönder |
| GET | /api/iot/devices/{deviceId}/rpc | iot_rpc.read | Cihazın komut geçmişi |
| GET | /api/iot/rpc/{rpcId} | iot_rpc.read | Bir komut ve yanıtı |
| POST | /api/iot/rpc/{rpcId}/cancel | iot_rpc.read artı komutun düzeyi | Sıradaki veya gönderilmiş bir komutu iptal et |
| GET | /api/iot/devices/{deviceId}/rpc-commands | iot_rpc.send.basic | Bir gösterge paneli kontrolünün bu cihaza gönderebileceği komutlar |
| GET | /api/iot/rpc-commands/{profileId} | iot_rpc.read | Bir profilin komut kataloğu (içe aktarma biçimi için ?format=export) |
| POST | /api/iot/rpc-commands/{profileId} | iot_rpc.commands.manage | Kataloğa komut ekle |
| PUT | /api/iot/rpc-commands/{profileId} | iot_rpc.commands.manage | Tüm kataloğu değiştir |
| PATCH, DELETE | /api/iot/rpc-commands/{profileId}/{commandId} | iot_rpc.commands.manage | Bir 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 | İzin | Varsayılan rol | Bir API anahtarı bunu tutabilir mi? |
|---|---|---|---|
| basic | iot_rpc.send.basic | Kullanıcı | Evet |
| privileged | iot_rpc.send.privileged | Yönetici | Evet |
| critical | iot_rpc.send.critical | Yönetici | Evet |
| raw (kataloğda olmayan bir yöntem) | iot_rpc.send.raw | Sahip | Hayı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 fazlaexpiresInSsüre boyunca onu bekler, sonraEXPIREDdurumuyla sona erer. - wait:
truebeklemeyi 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);falseher zaman hemen202yanıtı verir. - Yüksek etkili komutların
"confirm": truegerekir; katalogdaki komutta bir onay ifadesi varsa,confirmTextiç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.
| Durum | Anlamı |
|---|---|
SUCCESSFUL | Yanıt geldi veya tek yönlü bir komut iletildi |
FAILED | Cihaz reddetti veya komut gönderilemedi |
TIMEOUT | Zamanında yanıt gelmedi. Sonuç bilinmiyor: cihaz işlemi yapmış olabilir. outcome değeri unknowndur. |
EXPIRED | Son kullanma süresinden önce cihaza hiç ulaşmadı |
CANCELLED | Sı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ır | Varsayılan |
|---|---|
| Cihaz başına komut | Dakikada 10 (429, Retry-After: 60) |
| Kuruluş başına komut | Dakikada 600 (429 “Too many requests for your plan. Please upgrade or try again later.”) |
| Parametreler | 16 KiB JSON |
| Saklanan yanıt | 64 KiB |
| Profil kataloğu başına komut | 200 |
Reddetmeler
| Durum | details.reason | Mesaj |
|---|---|---|
| 400 | bad_params | Parametreler komutla eşleşmiyor. |
| 400 | wait_too_long | A synchronous call waits at most 30 s; use wait: false for a longer timeout. |
| 400 | confirm_required, confirm_text_mismatch | This command needs confirm: true. / The typed confirmation does not match. |
| 400 | method_refused | Fabrika ayarlarına dönme, eşleştirme, Wi-Fi unutma ve bulut bağlantısını unutma buluttan asla gönderilmez. |
| 400 | payload_too_large | İstek cihazın kabul ettiğinden büyük. |
| 403 | rpc_method_reserved | Yö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. |
| 404 | Cihaz bulunamadı. | |
| 409 | rpc_not_supported_by_profile | Cihaz profili yalnızca RPC taşımayan Legacy konularını destekler. |
| 409 | device_not_active | Cihaz devre dışı bırakılmış veya karantinaya alınmıştır. |
| 409 | not_cancellable | Yalnızca sıradaki veya gönderilmiş bir istek iptal edilebilir. |
| 429 | device_rate_limited | Bu 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.

