Nouveau : le pare-feu IA surveille toute la plateforme et explique chaque incident en termes simples. Découvrez comment ça marche

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

Lisez les dernières valeurs et l'historique, listez les clés d'un appareil, et lisez, écrivez et supprimez les attributs serveur et partagés via REST, avec les règles de clés et les erreurs.

La télémétrie correspond aux mesures que les appareils effectuent et envoient dans le temps. Les attributs sont des valeurs nommées qui décrivent un appareil : ce qu’il indique sur lui-même (client), ce que vous stockez à son sujet (serveur) et ce que vous voulez qu’il possède (partagé). Cette page liste les routes REST pour ces deux types. Les chemins se trouvent sous https://<your host>/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 Device HTTP API et Derived values.

Routes de télémétrie

MéthodeCheminPermissionFonction
GET/api/telemetry/latesttelemetry.readLa dernière valeur de chaque clé d’un appareil
GET/api/telemetry/seriestelemetry.readHistorique de jusqu’à 50 clés sur une fenêtre temporelle
GET/api/telemetry/kindstelemetry.readLes types de relevés de votre organisation (par exemple iot_device)
GET/api/iot/devices/{deviceId}/elementstelemetry.readLes clés d’un appareil, déclarées dans son profil ou envoyées, 300 au maximum

Un appareil que vous ne pouvez pas lire renvoie 404, comme un appareil inexistant.

Dernières valeurs

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

Omettez keys (50 au 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
ParamètreValeursPar défaut
keysde 1 à 50, séparées par des virgulesobligatoire
from, tomillisecondes depuis l’epoch ; to postérieur à fromobligatoire
bucketauto, raw, 1m, 1h, 1dauto
aggavg, min, max, last, sum, count, increaseavg
limitpoints par clé, de 1 à 10 00010,000

Les compartiments journaliers sont des jours UTC : pour des jours dans votre propre fuseau horaire, lisez les compartiments horaires et additionnez-les. Les valeurs brutes sont conservées 90 jours au maximum, les compartiments par minute 31 jours au maximum. Les règles complètes des paramètres, la pagination des valeurs brutes et des exemples sont 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, 300 au maximum. Sans la permission de lire les profils d’appareils, seules les clés envoyées par l’appareil sont listées.

Routes d’attributs

MéthodeCheminPermissionFonction
GET/api/iot/devices/{deviceId}/attributesiot_device.attributes.readLire les attributs de toutes les portées
POST/api/iot/devices/{deviceId}/attributes/serveriot_device.attributes.writeÉcrire les attributs serveur
POST/api/iot/devices/{deviceId}/attributes/sharediot_device.attributes.writeÉcrire les attributs partagés ; l’appareil les reçoit
DELETE/api/iot/devices/{deviceId}/attributes/{scope}?keys=a,biot_device.attributes.writeSupprimer des clés serveur ou partagées

Les attributs client ne sont écrits que par l’appareil. Une écriture sur client renvoie 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 accepte 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.* sur les appareils qui acceptent des paramètres par section) ne sont pas affichés ici ; lisez-les via les routes de paramètres d’appareil, voir Firmware and device settings API.

Écriture

POST/tenant/{tenantId}/api/iot/devices/{deviceId}/attributes/server

Un objet JSON plat de clés et de valeurs : de 1 à 100 clés par requête. Une valeur peut être un nombre, un texte, un booléen, un objet ou une liste, mais pas null (supprimez alors la clé). Seules les clés dont la valeur a changé sont stockées ; la réponse les nomme. Chaque modification est transmise aux flux sous forme de message attributes_updated et inscrite dans le journal d’audit (les clés, jamais les valeurs).

Corps de la requête application/json

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

Exemple curl

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

Réponses

200OK
{
    "changed": [
        "maxTempThreshold",
        "site_code"
    ]
}
400Bad Request
{
    "message": "One or more attribute keys are invalid or reserved.",
    "code": "VALIDATION_ERROR",
    "details": {
        "reason": "keys_invalid",
        "keys": [
            {
                "key": "fw_title",
                "reason": "reserved"
            }
        ]
    }
}
404Not Found
{
    "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"] }, soit les clés qui existaient. L’appareil est informé des clés partagées supprimées.

Règles des clés d’attributs

RègleDétail
Caractèreslettres, chiffres, _, ., - ; de 1 à 128 ; sensible à la casse
Jamaisdeleted ; une clé commençant par _
Réservées à la plateforme ou à l’appareilfw_*, current_fw_*, clés se terminant par .state ou .reason, et les clés de gestion internes de l’appareil (cfg_rejected, cfg_applied_ts, cfg_hash, attr_error, rpc_result, cert_not_after, time_quality)
cfg.*Configuration souhaitée : partagée uniquement, 128 caractères au maximum. Sur un appareil dont les paramètres sont gérés dans son onglet Settings, une écriture renvoie 409 « This device’s configuration (cfg.*) is managed in its Settings; change it there. »
Autres clés partagées57 caractères au maximum
Taille des valeursvaleurs serveur jusqu’à 64 KiB de JSON ; valeurs partagées jusqu’à la limite de liaison descendante de l’appareil ; imbrication de 8 niveaux au maximum

Voir Attributes pour l’usage de chaque portée, et Reserved keys and attributes 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 Alarm conditions reference.
  • Paramètres souhaités pour un appareil tiers : écrivez une clé partagée que le firmware de l’appareil lit, puis suivez ses attributs client pour voir le résultat.
  • Un rapport nocturne : lisez les series horaires d’hier et stockez-les dans votre entrepôt de données.