Siteler ve varlıklar API’si

Bu rotalar Hermetry Twin varlık ağacını yönetir: siteler, binalar, katlar, odalar, hatlar, makineler ve kendi tanımladığınız türler; her cihazın nerede yerleştirildiği ve varlıklarla cihazlar arasındaki ilişkiler. Kavramlar Varlık hiyerarşisi başlığında yer alır. Yollar https://<your host>/tenant/<tenantId> altındadır.

Rotalar

Varsayılan roller: okuma bir Kullanıcı iznidir; varlıkları, yerleşimleri ve ilişkileri değiştirmek bir Yönetici iznidir. Her değişiklik denetim günlüğüne yazılır (değişen alan adları, asla değerleri).

Varlık

Yanıtlardaki salt okunur alanlar: iotAssetId, path (baştan itibaren kodlar, örneğin /IST/BLD-A/GF), depth, createdAt, updatedAt.

{
    "name": "Compressor room",
    "kind": "ROOM",
    "code": "CR1",
    "parentId": "e5f6…",
    "timezone": "Europe/Istanbul",
    "attributes": {
        "area_m2": 42
    }
}

curl -X POST 'https://<your-host>/tenant/{tenantId}/api/iot/assets' \
  -H 'Content-Type: application/json' \
  -d '{"name":"Compressor room","kind":"ROOM","code":"CR1","parentId":"e5f6…","timezone":"Europe/Istanbul","attributes":{"area_m2":42}}'

{
    "asset": {
        "iotAssetId": "77aa…",
        "parentId": "e5f6…",
        "path": "/IST/BLD-A/GF/CR1",
        "depth": 4,
        "code": "CR1",
        "name": "Compressor room",
        "kind": "ROOM",
        "timezone": "Europe/Istanbul",
        "attributes": {
            "area_m2": 42
        },
        "…": "…"
    }
}

{
    "message": "Another asset already uses this code.",
    "code": "CONFLICT",
    "details": {
        "reason": "code_taken"
    }
}

PATCH, parentId dışında aynı alanları alır. Yeni bir code, altındaki her varlığın yollarını aynı adımda yeniden yazar.

GET /api/iot/assets/{assetId}, ancestors (önce kök, her biri id, code, name, kind ile), effectiveTimezone (kendisininki, yoksa en yakın atasınınki), childCount ve deviceCount ekler.

Liste ve ağaç

view ile GET /api/iot/assets:

Alarm bilgileri yalnızca çağıranın alarmları okuma yetkisi varsa eklenir.

Taşıma

POST /api/iot/assets/{assetId}/move
{ "parentId": "c3d4…" }

null onu üst düzey bir varlık yapar. Altındaki her şey onunla birlikte taşınır. Bir varlığı kendi altına veya kendi alt öğelerinden birinin altına taşımak reddedilir: “Bir varlık kendi altına veya kendi alt öğelerinden birinin altına taşınamaz.” (400, cycle). Bir yol en fazla 1.024 karakter olabilir (too_deep).

Silme

Alt varlıkları olan bir varlık reddedilir: “Bu varlığın hâlâ alt varlıkları var: önce onları taşıyın veya silin.” (409, has_children). Başka bir modül varlığı hâlâ kullandığını bildirirse, silme, o modülü adıyla anan 409 ile reddedilir. Bir varlığı silmek, cihaz yerleşimlerini ve ilişkilerini sonlandırır; cihazların kendisi kalır.

Cihazları yerleştir

POST /api/iot/assets/{assetId}/devices
{ "deviceIds": ["6f1c…", "8b2d…"] }

Her cihazın en fazla bir yeri vardır: buraya yerleştirmek, cihazı bulunduğu yerden taşır. Taşınanları listeleyen yanıt { "changes": [...] }‘dir. Bir seferde bir cihaz:

PUT /api/iot/devices/{deviceId}/placement
{ "iotAssetId": "77aa…" }      // or null to remove the placement

Hem .../placement için GET hem de PUT yanıtı { "placement": { "iotAssetId": "77aa…", "path": [ { "iotAssetId": "…", "code": "IST", "name": "Istanbul plant", "kind": "SITE" }, … ] } } biçimindedir, kök önce gelir. Yeri olmayan bir cihazın iotAssetId: null değeri vardır.

GET /api/iot/assets/{assetId}/devices, varsayılan olarak varlık üzerine yerleştirilmiş cihazları ve altındakileri listeler (yalnızca varlığın kendisi için recursive=false): search, online=true|false, sort=name|connection:asc|desc, 1’den başlayan page, en fazla 200 olan pageSize. Yanıt { items, total, page, pageSize }‘dir.

İlişkiler

Bir ilişki, her biri ASSET veya DEVICE olan iki ucu, bir türle bağlar: CONTAINS, MANAGES, FEEDS, MONITORS veya kendi türleriniz (harf, rakam, _, en fazla 32, büyük harfle saklanır).

{
    "fromType": "DEVICE",
    "fromId": "8b2d…",
    "toType": "DEVICE",
    "toId": "6f1c…",
    "type": "FEEDS",
    "additionalInfo": {
        "line": "DN150"
    }
}

curl -X POST 'https://<your-host>/tenant/{tenantId}/api/iot/relations' \
  -H 'Content-Type: application/json' \
  -d '{"fromType":"DEVICE","fromId":"8b2d…","toType":"DEVICE","toId":"6f1c…","type":"FEEDS","additionalInfo":{"line":"DN150"}}'

{
    "relation": {
        "relationId": "…",
        "fromType": "DEVICE",
        "fromId": "8b2d…",
        "toType": "DEVICE",
        "toId": "6f1c…",
        "type": "FEEDS",
        "…": "…"
    }
}

{
    "message": "This relation already exists.",
    "code": "CONFLICT",
    "details": {
        "reason": "relation_exists"
    }
}

Kurallar:

• Bir varlıktan bir cihaza CONTAINS, cihazın yerleşimidir (yerleşim rotalarını kullanın). Diğer biçimlerdeki CONTAINS reddedilir (placement_shape); bir varlığın başka bir varlığın içinde olması ise bir ilişkiyle değil, taşınmasıyla belirlenir (parentage_is_move).
• Bir ilişkinin iki farklı ucu olmalıdır (self_relation).
• Eksik bir uç 404 döner (end_not_found).

GET /api/iot/relations?entityType=ASSET&entityId={assetId}, bir ucun ilişkilerini iki yönde listeler; ya da fromType, fromId, toType, toId, type ile filtreleyin. limit 1 ila 500 (varsayılan 200). Yanıt { "relations": [...] }‘dir.

Seçici için cihaz ara

GET /api/iot/devices/search?q=pump&limit=20&near=iot_asset:{assetId}, { "devices": [{ "id", "name", "code", "hint" }] } yanıtını verir: ada göre en fazla 20 cihaz; verilen cihazın veya varlığın cihazları önce gelir, hint her birinin nerede yerleştirildiğini belirtir. Hem iot_asset.assets.read hem de iot_device.devices.read gerektirir.