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öntem | Yol | Yetki | İşlev |
|---|---|---|---|
| GET | /api/iot/devices | iot_device.devices.read | Cihazları listele |
| POST | /api/iot/devices | iot_device.devices.create | Bir cihaz ve erişim belirteci oluştur |
| GET | /api/iot/devices/{deviceId} | iot_device.devices.read | Tek bir cihazı oku |
| PATCH | /api/iot/devices/{deviceId} | iot_device.devices.update | Adı, etiketi, türü, profili, durumu, ek bilgiyi değiştir |
| DELETE | /api/iot/devices/{deviceId} | iot_device.devices.delete | Bir cihazı sil |
| GET | /api/iot/devices/{deviceId}/connection | iot_device.devices.read | Cihazın nereye bağlandığı |
| GET | /api/iot/devices/{deviceId}/connections | iot_device.devices.read | Bağlantı günlüğü |
| GET | /api/iot/devices/{deviceId}/log | iot_device.devices.read | Bağlantı günlüğü ve denetim satırları, birleştirilmiş |
Cihazları listele
GET /api/iot/devices (sayfalar 1’den başlar)
| Parametre | Değerler |
|---|---|
page | 1’den başlar (varsayılan 1) |
pageSize | 1 ile 100 arası (varsayılan 20) |
search | en fazla 128 karakter: ad, etiket veya seri numarası |
deviceProfileId | bir profil kimliği |
status | ACTIVE, QUARANTINED veya DISABLED |
isGateway | true veya false |
online | true, false veya unknown |
sort | name, 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,pageSizeen 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×pageSizeen fazla 1.000 olabilir.
Cihaz kimlik bilgileri
| Yöntem | Yol | İşlev |
|---|---|---|
| GET | /api/iot/devices/{deviceId}/credentials | Etkin kimlik bilgisi, gizli anahtarı olmadan |
| PUT | /api/iot/devices/{deviceId}/credentials | Başka bir kimlik bilgisine geç |
| POST | /api/iot/devices/{deviceId}/credentials/rotate | Aynı türde yeni bir gizli anahtar (201) |
| DELETE | /api/iot/devices/{deviceId}/credentials | Kimlik 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öntem | Yol | Yetki | İşlev |
|---|---|---|---|
| GET | /api/iot/device-profiles | iot_device_profile.profiles.read | Listele (page 1’den, pageSize, search, transportType, onlineRule, sort) |
| POST | /api/iot/device-profiles | iot_device_profile.profiles.write | Oluştur |
| GET | /api/iot/device-profiles/{profileId} | .profiles.read | Oku |
| PATCH | /api/iot/device-profiles/{profileId} | .profiles.write | Değiştir; expectedVersion gönderin |
| DELETE | /api/iot/device-profiles/{profileId} | .profiles.write | Sil |
| POST | /api/iot/device-profiles/{profileId}/default | .profiles.write | Varsayı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.read | Bu anahtarları kimler okuyor (kurallar, kartlar, akışlar) |
| GET, PUT, POST | /api/iot/device-profiles/{profileId}/provisioning | iot_device_profile.provisioning.manage | Provizyon 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ı:
| Alan | Aralık |
|---|---|
transportType | MQTT, HTTP, ANY veya kayıtlı bir protokol |
allowedAuthModes | ACCESS_TOKEN, MQTT_BASIC, X509_CERTIFICATE değerlerinden 1 ila 3 tanesi |
mqttTransport | TLS_REQUIRED (varsayılan) veya PLAINTEXT_ALLOWED |
allowedNetworks | en fazla 64 ağ veya adres |
payloadMaxBytes | 1.024 ile 65.536 arası |
downlinkMaxBytes | 1.024 ile 65.536 arası |
inactivityTimeoutSec | 10 ile 604.800 arası |
maxGatewayChildren | 0 ile 10.000 arası |
rpcTimeoutDefaultSec | 1 ile 300 arası |
onlineWindowFactor | 1,5 ile 10 arası, bir ondalık basamak |
telemetrySchema, cfgSchema | her biri en fazla 500 anahtar |
rateLimits | aile 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:
| Neden | Anlamı |
|---|---|
stale_profile | Profil, siz okuduktan sonra başka biri tarafından kaydedildi (409) |
name_taken | Bu ada sahip başka bir profil var |
default_profile | Varsayılan profil silinemez |
builtin_profile | Yerleşik bir profil bu yolla değiştirilemez |
still_referenced | Cihazlar veya başka kayıtlar hâlâ profili kullanıyor |
reference_unverifiable | Profili kullanabilecek bir modüle sorulamadı; yeniden deneyin |

