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

Cihazlar ve profiller API’si

Cihazlar, cihaz kimlik bilgileri, bağlantı ayrıntıları, cihaz günlüğü ve cihaz profilleri için REST yolları; parametreler, yanıtlar ve hatalarla birlikte.

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

YöntemYolYetkiİşlev
GET/api/iot/devicesiot_device.devices.readCihazları listele
POST/api/iot/devicesiot_device.devices.createBir cihaz ve erişim belirteci oluştur
GET/api/iot/devices/{deviceId}iot_device.devices.readTek bir cihazı oku
PATCH/api/iot/devices/{deviceId}iot_device.devices.updateAdı, etiketi, türü, profili, durumu, ek bilgiyi değiştir
DELETE/api/iot/devices/{deviceId}iot_device.devices.deleteBir cihazı sil
GET/api/iot/devices/{deviceId}/connectioniot_device.devices.readCihazın nereye bağlandığı
GET/api/iot/devices/{deviceId}/connectionsiot_device.devices.readBağlantı günlüğü
GET/api/iot/devices/{deviceId}/logiot_device.devices.readBağlantı günlüğü ve denetim satırları, birleştirilmiş

Cihazları listele

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

ParametreDeğerler
page1’den başlar (varsayılan 1)
pageSize1 ile 100 arası (varsayılan 20)
searchen fazla 128 karakter: ad, etiket veya seri numarası
deviceProfileIdbir profil kimliği
statusACTIVE, QUARANTINED veya DISABLED
isGatewaytrue veya false
onlinetrue, false veya unknown
sortname, connection, lastSeen, createdAt; :asc veya :desc ile
{
  "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ı Son görülme yalnızca olan bir profilde online null olur. GET /api/iot/devices/{deviceId}, aynı alanların yanı sıra profileName ve profileTransport ile birlikte { "device": {...} } yanıtını verir.

Cihaz oluştur

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

Alanlar: name (zorunlu, 1 ile 128 karakter, benzersiz), label (en fazla 255), type (en fazla 64), deviceProfileId (yoksa varsayılan profil), isGateway, additionalInfo (en fazla 50 anahtar ve 8 KiB içeren bir nesne). Yanıt cihazı içerir; cihazları kendi kendine giriş yapan profiller için credential.secret.token içinde bir erişim belirteci de bulunur. Belirteç yalnızca bu yanıtta gösterilir.

İstek gövdesi application/json

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

Örnek curl

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

Yanıtlar

201Oluşturuldu
{
    "device": {
        "deviceId": "6f1c…",
        "name": "pump-station-04",
        "status": "ACTIVE",
        "…": "…"
    },
    "credential": {
        "credential": {
            "credentialId": "…",
            "type": "ACCESS_TOKEN",
            "…": "…"
        },
        "secret": {
            "token": "Xq3…"
        }
    }
}
403Yasak
{
    "message": "The device limit of this account is reached.",
    "code": "FORBIDDEN",
    "details": {
        "key": "max_devices",
        "limit": 43,
        "current": 43,
        "adding": 1
    }
}
409Çakışma
{
    "message": "A device with this name already exists.",
    "code": "CONFLICT",
    "details": {
        "reason": "name_taken"
    }
}

Cihazı değiştir

PATCH /api/iot/devices/{deviceId} şunlardan herhangi birini alır: name, label, type, deviceProfileId, isGateway, additionalInfo, status (ACTIVE veya DISABLED). Yalnızca değişeni 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 canlı oturumunu sonlandırır; cihaz yeni ayarlarla yeniden bağlanır.

Cihazı sil

DELETE şu yanıtı verir: { "message": "Device deleted." }. Cihazın okumaları arka planda silinir. Hâlâ kullanılan bir cihaz 409 ile reddedilir; örneğin “The device is still in use by 1 asset placement or relation (iot_asset).” Önce onu bağlı olduğu varlıktan çı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 şey 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 o dinleyicide MQTT’yi reddediyorsa mqtt null olur; Legacy compatible şemasında rpcRequest ve rpcResponse 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 satırları birleştirilmiş, en yenisi önce. page × pageSize en fazla 1.000 olabilir.

Cihaz kimlik bilgileri

YöntemYolİşlev
GET/api/iot/devices/{deviceId}/credentialsEtkin kimlik bilgisi, gizli anahtarı olmadan
PUT/api/iot/devices/{deviceId}/credentialsBaşka bir kimlik bilgisine geç
POST/api/iot/devices/{deviceId}/credentials/rotateAynı türde yeni bir gizli anahtar (201)
DELETE/api/iot/devices/{deviceId}/credentialsKimlik bilgisini iptal et

Hepsi iot_device.credentials.manage gerektirir. Geçiş, döndürme 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ı bırakın (veya null yapın). Seçilen bir parola en az 16 karakter, çeşitli olmalı ve kullanıcı adını ya da istemci kimliğini içermemelidir. provision kullanıcı adı ayrılmıştır. Yanıt { "credential": {...}, "secret": { "token": "…" } } ya da { ..., "secret": { "password": "…" } } biçimindedir ve bir kez gösterilir; X.509 kimlik bilgisinin gizli anahtarı yoktur. X.509 kimlik bilgisi, yeni bir sertifika eklenerek döndürülür: “An X.509 credential is rotated by attaching a new certificate.” Bkz. Cihaz kimlik bilgileri.

Cihaz profilleri

YöntemYolYetkiİşlev
GET/api/iot/device-profilesiot_device_profile.profiles.readListele (page 1’den, pageSize, search, transportType, onlineRule, sort)
POST/api/iot/device-profilesiot_device_profile.profiles.writeOluştur
GET/api/iot/device-profiles/{profileId}.profiles.readOku
PATCH/api/iot/device-profiles/{profileId}.profiles.writeDeğiştir; expectedVersion gönderin
DELETE/api/iot/device-profiles/{profileId}.profiles.writeSil
POST/api/iot/device-profiles/{profileId}/default.profiles.writeVarsayılan yap
POST/api/iot/device-profiles/{profileId}/duplicate.profiles.write“Cold room sensor (copy)” adıyla kopyala
GET/api/iot/device-profiles/{profileId}/key-usage?keys=a,b.profiles.readBu anahtarları kimler okuyor (kurallar, kartlar, akışlar)
GET, PUT, POST/api/iot/device-profiles/{profileId}/provisioningiot_device_profile.provisioning.manageProvizyon ayarları; POST bir provizyon anahtarını döndürür veya iptal eder

Sıralama alanları: name, transport, online, updated. Bir liste { "profiles": [...], "total": n } yanıtını verir; tek bir profil { "profile": {...} }.

Profil oluştur

Yeni bir profil için bir name (en fazla 128 karakter) ve bir onlineRule gerekir: 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çilen alanlar ve aralıkları:

AlanAralık
transportTypeMQTT, HTTP, ANY veya kayıtlı bir protokol
allowedAuthModesACCESS_TOKEN, MQTT_BASIC, X509_CERTIFICATE değerlerinden 1 ila 3 tanesi
mqttTransportTLS_REQUIRED (varsayılan) veya PLAINTEXT_ALLOWED
allowedNetworksen fazla 64 ağ veya adres
payloadMaxBytes1.024 ile 65.536 arası
downlinkMaxBytes1.024 ile 65.536 arası
inactivityTimeoutSec10 ile 604.800 arası
maxGatewayChildren0 ile 10.000 arası
rpcTimeoutDefaultSec1 ile 300 arası
onlineWindowFactor1,5 ile 10 arası, bir ondalık basamak
telemetrySchema, cfgSchemaher biri en fazla 500 anahtar
rateLimitsaile başına count:seconds[,count:seconds], örneğin "telemetry_msgs": "10:1,300:60"

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.

Reddedilme durumları

Bir alan kuralını bozan gövde, 400 yanıtı alır ve sorunlar issues içinde, her biri kendi path ve message değeriyle listelenir; örneğin online_rule_required (yeni bir profilin çevrimiçi kuralı olmalıdır), expected_interval_required (Son mesaj için expectedIntervalS gerekir) veya online_rule_not_allowed (çevrimiçi kuralı aktarım türüne uymaz).

Diğer reddedilmeler details.reason alanını taşır, örneğin:

NedenAnlamı
stale_profileProfil, siz okuduktan sonra başka biri tarafından kaydedildi (409)
name_takenBu ada sahip başka bir profil var
default_profileVarsayılan profil silinemez
builtin_profileYerleşik bir profil bu yolla değiştirilemez
still_referencedCihazlar veya başka kayıtlar hâlâ profili kullanıyor
reference_unverifiableProfili kullanabilecek bir modüle sorulamadı; yeniden deneyin