Geräte- und Profil-API

Diese Routen verwalten Geräte und Geräteprofile per Code. Die Pfade liegen unter https://<your host>/tenant/<tenantId>. Konventionen (Paginierung, strikte Bodies, Zeiten) stehen in REST API basics.

Geräte

Geräte auflisten

GET /api/iot/devices (Seiten ab 1)

{
  "devices": [
    {
      "deviceId": "6f1c…",
      "name": "pump-station-04",
      "label": "Pump station 4",
      "type": "pump-controller",
      "serial": null,
      "deviceProfileId": "a1b2…",
      "status": "ACTIVE",
      "isGateway": false,
      "gatewayDeviceId": null,
      "model": null,
      "fwTitle": null,
      "fwVersion": null,
      "online": true,
      "active": true,
      "lastConnectAt": "2026-11-08T06:12:03.000Z",
      "lastDisconnectAt": null,
      "lastActivityAt": "2026-11-09T09:41:10.000Z",
      "lastRemoteIp": "203.0.113.20",
      "lastTransport": "mqtts",
      "additionalInfo": {},
      "createdAt": "2026-10-01T08:00:00.000Z",
      "updatedAt": "2026-11-08T06:12:03.000Z"
    }
  ],
  "total": 1
}

online ist null bei einem Profil, dessen Online-Regel Nur zuletzt gesehen ist. GET /api/iot/devices/{deviceId} antwortet mit { "device": {...} } mit denselben Feldern plus profileName und profileTransport.

Gerät anlegen

{
    "name": "pump-station-04",
    "label": "Pump station 4",
    "deviceProfileId": "a1b2…"
}

curl -X POST 'https://<your-host>/tenant/{tenantId}/api/iot/devices' \
  -H 'Content-Type: application/json' \
  -d '{"name":"pump-station-04","label":"Pump station 4","deviceProfileId":"a1b2…"}'

{
    "device": {
        "deviceId": "6f1c…",
        "name": "pump-station-04",
        "status": "ACTIVE",
        "…": "…"
    },
    "credential": {
        "credential": {
            "credentialId": "…",
            "type": "ACCESS_TOKEN",
            "…": "…"
        },
        "secret": {
            "token": "Xq3…"
        }
    }
}

{
    "message": "The device limit of this account is reached.",
    "code": "FORBIDDEN",
    "details": {
        "key": "max_devices",
        "limit": 43,
        "current": 43,
        "adding": 1
    }
}

{
    "message": "A device with this name already exists.",
    "code": "CONFLICT",
    "details": {
        "reason": "name_taken"
    }
}

Gerät ändern

PATCH /api/iot/devices/{deviceId} akzeptiert beliebige der Felder name, label, type, deviceProfileId, isGateway, additionalInfo, status (ACTIVE oder DISABLED). Nur geänderte Werte senden. Ein unter Quarantäne stehendes Gerät wird über die Bereitstellung freigegeben, nicht hier: „Ein unter Quarantäne stehendes Gerät wird über die Bereitstellung aktiviert, nicht hier bearbeitet.“ Ein neuer Name, ein neues Profil oder das Deaktivieren beendet die aktive Sitzung des Geräts; es verbindet sich mit den neuen Einstellungen erneut.

Gerät löschen

DELETE antwortet mit { "message": "Device deleted." }. Die Messwerte des Geräts werden im Hintergrund entfernt. Ein Gerät, das noch verwendet wird, wird mit 409 abgelehnt, zum Beispiel: „The device is still in use by 1 asset placement or relation (iot_asset).“ Entfernen Sie es zuvor von seinem Asset und löschen Sie seine Relationen: siehe Placing devices und Relations.

Verbindungsdetails

GET /api/iot/devices/{deviceId}/connection gibt nichts Geheimes zurück:

{
  "connection": {
    "mqtt": { "host": "mqtt.example.com", "port": 8883, "tls": true },
    "httpBase": "https://acme.example.com",
    "topics": { "telemetry": "v1/telemetry", "attributes": "v1/attributes", "rpcRequest": "v1/rpc/req/+", "rpcResponse": "v1/rpc/res/{id}" },
    "telemetryKeys": [{ "key": "temperature", "type": "number" }]
  }
}

mqtt ist null, wenn das Profil MQTT an diesem Listener ablehnt; rpcRequest und rpcResponse sind null beim Schema Legacy compatible.

Protokolle

• GET .../connections?page=1&pageSize=50: Verbindungsaufbau und -abbau, neueste zuerst (Seiten ab 1, pageSize bis 100).
• GET .../log?page=1&pageSize=50&source=connection|audit: das Verbindungsprotokoll und die Audit-Einträge des Geräts, zusammengeführt, neueste zuerst. page × pageSize darf höchstens 1.000 ergeben.

Gerätezugangsdaten

Alle benötigen iot_device.credentials.manage. Wechsel, Rotation und Widerruf beenden die alten Zugangsdaten sofort (es gibt kein Übergangsfenster) und trennen das Gerät.

PUT-Bodies:

{ "type": "ACCESS_TOKEN" }
{ "type": "MQTT_BASIC", "username": "pump04", "clientId": "pump04", "password": null }
{ "type": "X509_CERTIFICATE", "certificateId": "…" }

Bei MQTT_BASIC lassen Sie password weg (oder setzen null), um ein generiertes Passwort zu erhalten. Ein gewähltes Passwort braucht mindestens 16 Zeichen, Vielfalt und darf den Benutzernamen oder die Client-ID nicht enthalten. Der Benutzername provision ist reserviert. Die Antwort ist { "credential": {...}, "secret": { "token": "…" } } oder { ..., "secret": { "password": "…" } }, nur einmal angezeigt; ein X.509-Zertifikat hat kein Geheimnis. Ein X.509-Zugang wird rotiert, indem ein neues Zertifikat angehängt wird: „Ein X.509-Zugang wird durch Anhängen eines neuen Zertifikats rotiert.“ Siehe Device credentials.

Geräteprofile

Sortierfelder: name, transport, online, updated. Eine Liste antwortet mit { "profiles": [...], "total": n }; ein Profil mit { "profile": {...} }.

Ein Profil anlegen

Ein neues Profil braucht einen name (bis 128 Zeichen) und eine onlineRule: LIVE_SOCKET (Live-Verbindung), UPLINK_WINDOW (Letzte Nachricht, braucht zusätzlich expectedIntervalS, 60 bis 604.800) oder LAST_SEEN_ONLY (Nur zuletzt gesehen). Jedes andere Feld erhält seinen Standardwert.

{
  "name": "Cold room sensor",
  "onlineRule": "UPLINK_WINDOW",
  "expectedIntervalS": 300,
  "transportType": "MQTT",
  "telemetrySchema": [
    { "key": "temperature", "type": "number", "unit": "°C", "label": "Temperature", "min": -30, "max": 10, "decimals": 1 }
  ]
}

Ausgewählte Felder und ihre Bereiche:

Lesen Sie zuerst ein bestehendes Profil, um jedes Feld mit seinem aktuellen Wert zu sehen; der Profil-Editor deckt dieselben Felder mit Erläuterungen ab, siehe Geräteprofile.

Ablehnungen

Ein Body, der eine Feldregel verletzt, ergibt ein 400 mit den Problemen in issues, jeweils mit path und message, zum Beispiel online_rule_required (ein neues Profil benötigt eine Online-Regel), expected_interval_required (Letzte Nachricht benötigt expectedIntervalS) oder online_rule_not_allowed (die Online-Regel passt nicht zum Transport).

Andere Ablehnungen enthalten details.reason, zum Beispiel: