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éthode | Chemin | Permission | Fonction |
|---|---|---|---|
| GET | /api/telemetry/latest | telemetry.read | La dernière valeur de chaque clé d’un appareil |
| GET | /api/telemetry/series | telemetry.read | Historique de jusqu’à 50 clés sur une fenêtre temporelle |
| GET | /api/telemetry/kinds | telemetry.read | Les types de relevés de votre organisation (par exemple iot_device) |
| GET | /api/iot/devices/{deviceId}/elements | telemetry.read | Les 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ètre | Valeurs | Par défaut |
|---|---|---|
keys | de 1 à 50, séparées par des virgules | obligatoire |
from, to | millisecondes depuis l’epoch ; to postérieur à from | obligatoire |
bucket | auto, raw, 1m, 1h, 1d | auto |
agg | avg, min, max, last, sum, count, increase | avg |
limit | points par clé, de 1 à 10 000 | 10,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éthode | Chemin | Permission | Fonction |
|---|---|---|---|
| GET | /api/iot/devices/{deviceId}/attributes | iot_device.attributes.read | Lire les attributs de toutes les portées |
| POST | /api/iot/devices/{deviceId}/attributes/server | iot_device.attributes.write | Écrire les attributs serveur |
| POST | /api/iot/devices/{deviceId}/attributes/shared | iot_device.attributes.write | Écrire les attributs partagés ; l’appareil les reçoit |
| DELETE | /api/iot/devices/{deviceId}/attributes/{scope}?keys=a,b | iot_device.attributes.write | Supprimer 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ègle | Détail |
|---|---|
| Caractères | lettres, chiffres, _, ., - ; de 1 à 128 ; sensible à la casse |
| Jamais | deleted ; une clé commençant par _ |
| Réservées à la plateforme ou à l’appareil | fw_*, 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ées | 57 caractères au maximum |
| Taille des valeurs | valeurs 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
maxTempThresholdcomme 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
serieshoraires d’hier et stockez-les dans votre entrepôt de données.

