Cihazlar ve profiller API’si

These routes manage devices and device profiles from code. Paths are under https://<your host>/tenant/<tenantId>. Conventions (paging, strict bodies, times) are in REST API basics.

Cihazlar

Cihazları listele

GET /api/iot/devices (sayfalar 1’den başlar)

{
  "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
}

Çevrimiçi kuralı Yalnızca son görülme olan bir profilde online değeri null olur. GET /api/iot/devices/{deviceId} aynı alanların yanında profileName ve profileTransport ile birlikte { "device": {...} } yanıtını verir.

Cihaz oluştur

{
    "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"
    }
}

Cihazı değiştir

PATCH /api/iot/devices/{deviceId}, şu alanlardan herhangi birini kabul eder: name, label, type, deviceProfileId, isGateway, additionalInfo, status (ACTIVE veya DISABLED). Yalnızca değişenleri gönderin. Karantinadaki bir cihaz burada değil, provizyon yoluyla onaylanır: “A quarantined device is activated through provisioning, not edited here.” Yeni bir ad, yeni bir profil veya devre dışı bırakma, cihazın etkin oturumunu sonlandırır; cihaz yeni ayarlarla yeniden bağlanır.

Cihazı sil

DELETE yanıtı { "message": "Device deleted." } olur. Cihazın okumaları arka planda silinir. Hâlâ kullanımda olan bir cihaz 409 ile reddedilir; örneğin “The device is still in use by 1 asset placement or relation (iot_asset).” Önce varlığından çıkarın ve ilişkilerini kaldırın: bkz. Cihazların yerleştirilmesi ve İlişkiler.

Bağlantı ayrıntıları

GET /api/iot/devices/{deviceId}/connection gizli hiçbir bilgi döndürmez:

{
  "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" }]
  }
}

Profil bu dinleyicide MQTT’yi reddediyorsa mqtt değeri null olur; Legacy compatible şemasında rpcRequest ve rpcResponse değerleri null olur.

Günlükler

• GET .../connections?page=1&pageSize=50: bağlanmalar ve bağlantı kesmeler, en yenisi önce (sayfalar 1’den başlar, pageSize en fazla 100).
• GET .../log?page=1&pageSize=50&source=connection|audit: bağlantı günlüğü ve cihazın denetim kayıtları birleştirilmiş, en yenisi önce. page × pageSize en fazla 1.000 olabilir.

Cihaz kimlik bilgileri

Hepsi iot_device.credentials.manage iznini gerektirir. Geçiş, yenileme ve iptal, eski kimlik bilgisini hemen sonlandırır (bekleme süresi yoktur) ve cihazın bağlantısını keser.

PUT gövdeleri:

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

MQTT_BASIC için, oluşturulmuş bir parola almak üzere password alanını çıkarın (veya null yapın). Seçilen bir parola en az 16 karakter, çeşitli olmalı ve kullanıcı adını veya istemci kimliğini içermemelidir. provision kullanıcı adı ayrılmıştır. Yanıt { "credential": {...}, "secret": { "token": "…" } } veya { ..., "secret": { "password": "…" } } biçimindedir ve bir kez gösterilir; X.509 kimlik bilgisinin gizli anahtarı yoktur. X.509 kimlik bilgisi, yeni bir sertifika eklenerek yenilenir: “An X.509 credential is rotated by attaching a new certificate.” Bkz. Cihaz kimlik bilgileri.

Cihaz profilleri

Sıralama alanları: name, transport, online, updated. Liste { "profiles": [...], "total": n } yanıtını verir; tek profil { "profile": {...} } olarak döner.

Profil oluştur

Yeni bir profil bir name (en fazla 128 karakter) ve bir onlineRule gerektirir: LIVE_SOCKET (Canlı bağlantı), UPLINK_WINDOW (Son mesaj, ayrıca expectedIntervalS gerektirir, 60 ile 604.800 arası) veya LAST_SEEN_ONLY (Yalnızca son görülme). Diğer her alan varsayılanını alır.

{
  "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 }
  ]
}

Seçili alanlar ve aralıkları:

Her alanı mevcut değeriyle görmek için önce mevcut bir profili okuyun; profil düzenleyicisi aynı alanları açıklamalarıyla kapsar, bkz. Cihaz profilleri.

Reddetmeler

Bir alan kuralını bozan gövde, sorunları issues içinde, her biri path ve message ile birlikte, 400 döner; örneğin online_rule_required (yeni bir profilin çevrimiçi kuralı olmalı), expected_interval_required (Son mesaj expectedIntervalS gerektirir) veya online_rule_not_allowed (çevrimiçi kuralı taşımaya uymaz).

Diğer reddetmeler details.reason içerir, örneğin: