API de télémétrie et d’attributs

La télémétrie correspond aux valeurs que les appareils mesurent et envoient dans le temps. Les attributs sont des valeurs nommées qui décrivent un appareil : ce qu’il indique de lui-même (client), ce que vous enregistrez à son sujet (serveur) et ce que vous souhaitez qu’il ait (partagé). Cette page liste les routes REST pour les deux. Les chemins se trouvent sous https://<votre hôte>/tenant/<tenantId>.

L’API REST lit la télémétrie mais ne l’écrit jamais. Les appareils écrivent la télémétrie via MQTT ou HTTP ; les flux écrivent les valeurs dérivées avec Save telemetry. Voir API HTTP des appareils et Valeurs dérivées.

Routes de télémétrie

Un appareil que vous ne pouvez pas lire répond 404, comme un appareil inexistant.

Dernières valeurs

GET /api/telemetry/latest?kind=iot_device&entityId={deviceId}&keys=temperature,humidity

Omettez keys (50 maximum) pour obtenir toutes les clés.

{
  "kind": "iot_device",
  "entityId": "6f1c…",
  "latest": {
    "temperature": { "ts": 1762681200000, "value": 21.5 },
    "humidity": { "ts": 1762681200000, "value": 40 }
  }
}

Historique

GET /api/telemetry/series?kind=iot_device&entityId={deviceId}&keys=temperature&from=1762594800000&to=1762681200000&bucket=1h&agg=max

Les intervalles journaliers correspondent aux jours UTC : pour les jours de votre propre fuseau horaire, lisez les intervalles horaires et additionnez-les. Les valeurs brutes sont conservées 90 jours au maximum, les intervalles par minute 31 jours au maximum. Les règles complètes des paramètres, la pagination des valeurs brutes et des exemples détaillés se trouvent dans L’API d’historique.

Les clés d’un appareil

GET /api/iot/devices/{deviceId}/elements

La réponse liste les éléments de l’appareil avec leurs libellés et les clés qu’il possède, déclarées dans son profil ou envoyées, au maximum 300. Sans la permission de lire les profils d’appareils, seules les clés que l’appareil a envoyées sont listées.

Routes des attributs

Les attributs client sont écrits uniquement par l’appareil. Une écriture sur client répond 405 : « Client attributes are written by the device only. »

Lecture

GET /api/iot/devices/{deviceId}/attributes?scope=server&keys=maxTempThreshold,site_code

scope vaut client, shared ou server (quelle que soit la casse) ; omettez-le pour les trois. keys contient jusqu’à 100 clés.

{
  "attributes": {
    "client": { "fw_version": { "value": "2.4.1", "updatedAt": 1762594800000 } },
    "shared": { "reportInterval": { "value": 60, "updatedAt": 1762500000000 } },
    "server": { "maxTempThreshold": { "value": 8, "updatedAt": 1762400000000 } }
  }
}

Les paramètres gérés par l’onglet Settings d’un appareil (clés cfg.* des appareils qui reçoivent leurs paramètres par section) ne sont pas affichés ici ; lisez-les via les routes de paramètres d’appareil, voir API de firmware et de paramètres des appareils.

Écriture

{
    "maxTempThreshold": 8,
    "site_code": "IST-04"
}

curl -X POST 'https://<your-host>/tenant/{tenantId}/api/iot/devices/{deviceId}/attributes/server' \
  -H 'Content-Type: application/json' \
  -d '{"maxTempThreshold":8,"site_code":"IST-04"}'

{
    "changed": [
        "maxTempThreshold",
        "site_code"
    ]
}

{
    "message": "One or more attribute keys are invalid or reserved.",
    "code": "VALIDATION_ERROR",
    "details": {
        "reason": "keys_invalid",
        "keys": [
            {
                "key": "fw_title",
                "reason": "reserved"
            }
        ]
    }
}

{
    "message": "Device not found.",
    "code": "NOT_FOUND"
}

Les attributs partagés sont envoyés à l’appareil immédiatement s’il est connecté, sinon à sa prochaine connexion. Une valeur partagée doit respecter la limite de liaison descendante du profil d’appareil : « An attribute value is larger than the device’s downlink limit. » (details.reason = value_too_large).

Suppression

DELETE /api/iot/devices/{deviceId}/attributes/shared?keys=reportInterval,mode

La réponse est { "deleted": ["mode", "reportInterval"] }, les clés qui existaient. Un appareil est informé des clés partagées supprimées.

Règles des clés d’attributs

Voir Attributs pour l’usage de chaque portée, et Clés et attributs réservés pour la liste complète.

Usages courants

• Limites par appareil issues d’un ERP ou d’un MES : écrivez maxTempThreshold comme attribut serveur ; les règles d’alarme peuvent le comparer. Voir Référence des conditions d’alarme.
• Paramètres souhaités pour un appareil tiers : écrivez une clé partagée que le firmware de l’appareil lit, et surveillez ses attributs client pour le résultat.
• Un rapport nocturne : lisez les series horaires d’hier et stockez-les dans votre entrepôt de données.