Neu: Die KI-Firewall überwacht die gesamte Plattform und erklärt jeden Vorfall in einfachen Worten. So funktioniert es

Commands API

Befehle an Geräte senden, auf deren Ergebnisse warten oder sie abfragen, Befehle abbrechen und den Befehlskatalog eines Profils über REST verwalten – Felder, Zustände, Grenzwerte und Fehler.

Ein Befehl (ein RPC) fordert ein Gerät auf, etwas zu tun, und wartet, sofern er nicht einseitig ist, auf die Antwort des Geräts. Jeder Befehl wird als Anfrage mit einem Status gespeichert, sodass Sie ihn jetzt senden und das Ergebnis später abrufen können. Wie Befehle für Nutzer in der App funktionieren, steht unter Befehle an Geräte senden. Pfade liegen unter https://<your host>/tenant/<tenantId>.

Routen

MethodePfadBerechtigungFunktion
POST/api/iot/devices/{deviceId}/rpciot_rpc.read plus die Stufe des BefehlsEinen Befehl senden
GET/api/iot/devices/{deviceId}/rpciot_rpc.readDer Befehlsverlauf des Geräts
GET/api/iot/rpc/{rpcId}iot_rpc.readEin Befehl mit seiner Antwort
POST/api/iot/rpc/{rpcId}/canceliot_rpc.read plus die Stufe des BefehlsEinen wartenden oder gesendeten Befehl abbrechen
GET/api/iot/devices/{deviceId}/rpc-commandsiot_rpc.send.basicDie Befehle, die eine Dashboard-Steuerung an dieses Gerät senden darf
GET/api/iot/rpc-commands/{profileId}iot_rpc.readDer Befehlskatalog eines Profils (?format=export für das Importformat)
POST/api/iot/rpc-commands/{profileId}iot_rpc.commands.manageEinen Befehl zum Katalog hinzufügen
PUT/api/iot/rpc-commands/{profileId}iot_rpc.commands.manageDen gesamten Katalog ersetzen
PATCH, DELETE/api/iot/rpc-commands/{profileId}/{commandId}iot_rpc.commands.manageEinen Befehl ändern oder entfernen

Wer was senden darf

Jeder Befehl im Katalog eines Profils hat eine Stufe. Die Stufe bestimmt die Berechtigung:

StufeBerechtigungStandardrolleKann ein API-Schlüssel sie besitzen?
basiciot_rpc.send.basicBenutzerJa
privilegediot_rpc.send.privilegedAdministratorJa
criticaliot_rpc.send.criticalAdministratorJa
raw (eine Methode, die nicht im Katalog steht)iot_rpc.send.rawEigentümerNein

Ein API-Schlüssel kann daher nur Methoden senden, die im Katalog des Geräteprofils stehen.

Einen Befehl senden

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

Felder: method (erforderlich, namespace.verb, bis zu 64 Zeichen), params (beliebiges JSON, höchstens 16 KiB), oneway, persistent, timeoutMs (1.000 bis 600.000; Standard ist der Wert des Katalogs oder des Profils, sonst 10.000), expiresInS (1 bis 604.800, für einen persistenten Befehl; Standard 86.400), wait, confirm, confirmText, source (api, console oder dashboard_control). Ein zweiseitiger, nicht persistenter Befehl mit einem Timeout von höchstens 30 Sekunden wartet auf sein Ende und antwortet mit 200; alles andere antwortet mit 202 und läuft weiter.

Anfragetext application/json

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

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

Antworten

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"
    }
}
  • Einseitig (oneway: true): Der Befehl gilt als erfolgreich, sobald er zugestellt ist; es wird keine Antwort erwartet.
  • Persistent (persistent: true): Ist das Gerät offline, wartet der Befehl bis zu expiresInS auf es und endet danach mit EXPIRED.
  • wait: true erzwingt das Warten (wird mit „A synchronous call waits at most 30 s; use wait: false for a longer timeout.“ abgelehnt, wenn der Befehl nicht in 30 s enden kann); false antwortet immer sofort mit 202.
  • Befehle mit hoher Wirkung benötigen "confirm": true und die eingegebene Phrase in confirmText, wenn der Katalogbefehl eine solche hat. Ohne diese Angaben: „This command needs confirm: true.“ Sie werden beim Senden und beim Beenden im Audit-Protokoll erfasst und höchstens einmal gesendet.

Für diese Route gibt es keinen Idempotenz-Schlüssel: Jedes POST erstellt einen neuen Befehl. Läuft Ihr Aufruf im Netzwerk in ein Timeout, lesen Sie den Verlauf des Geräts, bevor Sie erneut senden.

Status

QUEUED → SENT → DELIVERED → SUCCESSFUL, oder einer der Zustände FAILED, TIMEOUT, EXPIRED, CANCELLED.

StatusBedeutung
SUCCESSFULDie Antwort ist eingetroffen, oder ein einseitiger Befehl wurde zugestellt
FAILEDDas Gerät hat ihn abgelehnt, oder er konnte nicht gesendet werden
TIMEOUTKeine Antwort rechtzeitig. Das Ergebnis ist unbekannt: Das Gerät könnte es ausgeführt haben. outcome ist unknown.
EXPIREDEr hat das Gerät vor Ablauf nie erreicht
CANCELLEDAbgebrochen, während er wartete oder gesendet war

outcome liefert Details: running (das Gerät hat einen länger laufenden Befehl angenommen), unknown (ein Timeout) oder late (eine Antwort kam nach dem Ende an). Ergebnisse werden standardmäßig 90 Tage aufbewahrt.

Ergebnisse abrufen

Fragen Sie GET /api/iot/rpc/{rpcId} ab, bis der Status endgültig ist, oder abonnieren Sie die Webhook-Ereignisse rpc.completed und rpc.failed und lesen Sie die Antwort, sobald eines eintrifft. Siehe die Referenz der Webhook-Ereignisse.

Verlauf eines Geräts, neueste zuerst:

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

Ohne page wird der Verlauf mit einem Cursor gelesen: status, method, from, to (Datumsangaben), limit (1 bis 100, Standard 25) und cursor. Die Antwort lautet { "requests": [...], "nextCursor": "…" }; übergeben Sie nextCursor als cursor zurück, bis er null ist. Mit page (ab 0) folgt die Liste den üblichen Listenregeln: pageSize, search, sort (method, status, source, createdAt, completedAt), status und source als kommagetrennte Listen, createdFrom, createdTo; die Antwort lautet { "requests": [...], "total": n }. Geheime Parameter werden in jeder Antwort maskiert.

Abbrechen

POST /api/iot/rpc/{rpcId}/cancel setzt einen Befehl im Status QUEUED oder SENT auf CANCELLED und antwortet mit { "rpc": {...} }. Andere Status: 409 „Only a queued or sent request can be cancelled.“ Zum Abbrechen wird dieselbe Berechtigung der Stufe benötigt wie zum Senden. Ein Abbruch sendet kein Webhook.

Grenzwerte

GrenzwertStandard
Befehle pro Gerät10 pro Minute (429, Retry-After: 60)
Befehle pro Organisation600 pro Minute (429 „Too many requests for your plan. Please upgrade or try again later.“)
Parameter16 KiB JSON
Gespeicherte Antwort64 KiB
Befehle pro Profilkatalog200

Ablehnungen

Statusdetails.reasonMeldung
400bad_paramsDie Parameter passen nicht zum Befehl.
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. / Die eingegebene Bestätigung stimmt nicht überein.
400method_refusedWerkseinstellungen zurücksetzen, Kopplung, Wi-Fi vergessen und das Vergessen der Cloud werden nie aus der Cloud gesendet.
400payload_too_largeDie Anfrage ist größer, als das Gerät akzeptiert.
403rpc_method_reservedDie Methode gehört zu einem eigenen Modul (zum Beispiel Fernzugriff) und wird nur von diesem gesendet; details.owner nennt das Modul.
404Gerät nicht gefunden.
409rpc_not_supported_by_profileDas Geräteprofil spricht nur die Legacy-Topics, die keinen RPC übertragen.
409device_not_activeDas Gerät ist deaktiviert oder in Quarantäne.
409not_cancellableNur eine wartende oder gesendete Anfrage kann abgebrochen werden.
429device_rate_limitedZu viele Befehle an dieses Gerät; versuchen Sie es in einer Minute erneut.

Der Befehlskatalog

Ein Katalogbefehl enthält: method, label (bis zu 120), description, paramsSchema (bis zu 50 Felder, jeweils mit label, type von text, textarea, number, boolean, select, multi-select oder json sowie optional required, min, max, step, options), maskedParams (geheime Felder werden nie wieder angezeigt), tier (basic, privileged, critical), highImpact, oneway, long, defaultTimeoutMs, persistentDefault, confirmText (nur bei High-Impact-Befehlen).

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

GET ...?format=export gibt { "commands": [...] } ohne IDs zurück, die PUT wieder entgegennimmt, um einen Katalog in ein anderes Profil zu kopieren.