Deux points de lecture vous donnent la télémétrie des appareils : latest pour la valeur actuelle de chaque clé, et series pour l’historique. Les deux sont protégés par l’autorisation de lecture de la télémétrie et ne renvoient que les appareils que l’appelant est autorisé à lire. Cette page est la référence, avec des exemples ; voir Principes de base de l’API REST et Authentification pour les clés et les chemins.
Avant de commencer
- Créez une clé API avec l’autorisation de lire la télémétrie (et de lire les appareils, si vous les listez aussi). Le préréglage Lecture seule suffit. Restreignez les réseaux autorisés de la clé à vos serveurs.
- Trouvez l’identifiant de l’appareil (un UUID) sur la page de l’appareil ou avec
GET /api/iot/devices. - Tous les chemins se trouvent sous votre organisation :
https://<votre hôte>/tenant/<tenantId>/api/.... - Les heures sont exprimées en millisecondes depuis le 1er janvier 1970, UTC.
Valeurs actuelles
GET /tenant/{tenantId}/api/telemetry/latest?kind=iot_device&entityId={deviceId}&keys=temperature,humidity| Paramètre | Obligatoire | Signification |
|---|---|---|
kind | Oui | iot_device pour la télémétrie des appareils |
entityId | Oui | L’identifiant de l’appareil |
keys | Non | Clés séparées par des virgules, 50 au maximum. Omettez pour toutes les clés. |
{
"kind": "iot_device",
"entityId": "6f1c…",
"latest": {
"temperature": { "ts": 1759572000000, "value": 21.5 },
"humidity": { "ts": 1759572000000, "value": 40 }
}
}Une clé que l’appareil n’a jamais envoyée est absente de latest.
Séries
GET /tenant/{tenantId}/api/telemetry/series?kind=iot_device&entityId={deviceId}&keys=temperature&from=1759568400000&to=1759572000000&bucket=auto&agg=avg| Paramètre | Obligatoire | Valeurs | Par défaut |
|---|---|---|---|
kind | Oui | iot_device | |
entityId | Oui | L’identifiant de l’appareil | |
keys | Oui | Séparées par des virgules, de 1 à 50 clés, chacune respectant les règles de clés | |
from | Oui | Début, inclus (epoch en ms) | |
to | Oui | Fin, exclue (epoch en ms) ; doit être postérieure à from | |
bucket | Non | auto, raw, 1m, 1h, 1d | auto |
agg | Non | avg, min, max, last, sum, count, increase | avg |
limit | Non | Points par clé, de 1 à 10 000 | 10,000 |
{
"kind": "iot_device",
"entityId": "6f1c…",
"resolution": "1m",
"agg": "avg",
"series": {
"temperature": [
{ "ts": 1759568400000, "value": 21.2 },
{ "ts": 1759568460000, "value": 21.4 }
]
}
}resolutionest la résolution réellement utilisée. Avecbucket=auto, elle vautrawpour les fenêtres allant jusqu’à 24 heures, puis1m,1hou1d, selon la plus fine possible sous 10 000 intervalles.- Avec un intervalle,
tsest le début de l’intervalle (aligné sur UTC) etvaluel’agrégat. Les intervalles sans mesure sont absents, et non à zéro. - Avec
raw, chaque valeur stockée est renvoyée telle qu’elle a été stockée (nombres, texte, booléens, JSON), un point par horodatage, du plus ancien au plus récent ;aggest ignoré. - Les points sont triés par temps. Une clé sans données renvoie une liste vide.
Voir Agrégats et cumuls pour ce que renvoie chaque agg.
Limites
| Limite | Valeur |
|---|---|
| Clés par requête | 50 |
| Points par clé | 10 000 (limit) |
| Intervalles dans une fenêtre | 10 000 à la résolution choisie, sinon 400 range_too_large |
| Valeurs brutes | Uniquement dans votre rétention des données brutes (90 jours au maximum) |
| Intervalles d’une minute | Uniquement dans la rétention par minute (31 jours au maximum) |
| Requêtes | La limite de débit de l’API ; 429 avec Retry-After en cas de dépassement. Voir Erreurs et limites de débit. |
Erreurs
| Statut | Corps | Cause |
|---|---|---|
| 400 | { "message": "to must be after from" } | to n’est pas postérieur à from |
| 400 | { "message": "bad keys" } | keys vide, plus de 50, ou une clé qui ne respecte pas les règles de clés |
| 400 | { "message": "…", "code": "range_too_large" } | Trop d’intervalles pour la fenêtre ; utilisez un bucket plus grossier |
| 401 / 403 | Aucune clé valide, ou la clé n’a pas l’autorisation | |
| 404 | { "message": "Not found" } | L’appareil n’existe pas, ou vous n’êtes pas autorisé à le lire (même réponse dans les deux cas) |
| 429 | Limite de débit |
Parcourir les valeurs brutes
Une lecture brute renvoie au maximum 10 000 points par clé, du plus ancien au plus récent. Pour en lire davantage :
- Demandez
bucket=raw&limit=10000pour votre fenêtre. - Si une clé a renvoyé 10 000 points, redemandez avec
fromégal autsdu dernier point + 1. - Répétez jusqu’à ce qu’une clé renvoie moins de
limitpoints.
Pour les longues périodes, préférez les intervalles 1m ou 1h : ils contiennent le min, le max, la somme, le nombre et la dernière valeur de chaque intervalle, en une valeur chacun.
Exemples
Valeurs actuelles avec curl :
curl -s -H "Authorization: Bearer $HERMETRY_KEY" \
"https://$HOST/tenant/$TENANT/api/telemetry/latest?kind=iot_device&entityId=$DEVICE&keys=level,pump_running"Maximum horaire d’une pression sur les 7 derniers jours :
TO=$(date +%s000); FROM=$((TO - 7*24*3600*1000))
curl -s -H "Authorization: Bearer $HERMETRY_KEY" \
"https://$HOST/tenant/$TENANT/api/telemetry/series?kind=iot_device&entityId=$DEVICE&keys=pressure&from=$FROM&to=$TO&bucket=1h&agg=max"Énergie consommée par heure (un compteur kWh qui ne fait que croître) sur une journée :
curl -s -H "Authorization: Bearer $HERMETRY_KEY" \
"https://$HOST/tenant/$TENANT/api/telemetry/series?kind=iot_device&entityId=$DEVICE&keys=energy_kwh&from=1762642800000&to=1762729200000&bucket=1h&agg=increase"Totaux journaliers dans votre fuseau horaire
Les intervalles d’un jour sont des jours UTC. Pour un jour local, lisez le increase (ou le sum) horaire et additionnez les heures qui appartiennent à chaque jour local :
// Node.js 18+: daily energy per local day (Europe/Istanbul) for the last 7 days
const tz = 'Europe/Istanbul';
const to = Date.now();
const from = to - 7 * 24 * 3600 * 1000;
const url = `https://${host}/tenant/${tenant}/api/telemetry/series?kind=iot_device&entityId=${device}`
+ `&keys=energy_kwh&from=${from}&to=${to}&bucket=1h&agg=increase`;
const res = await fetch(url, { headers: { Authorization: `Bearer ${key}` } });
const { series } = await res.json();
const days = {};
for (const p of series.energy_kwh) {
const day = new Date(p.ts).toLocaleDateString('en-CA', { timeZone: tz }); // YYYY-MM-DD
days[day] = (days[day] ?? 0) + p.value;
}
console.log(days);La première heure de la fenêtre ne compte que ce qui a augmenté à l’intérieur de celle-ci ; commencez donc la fenêtre une heure avant le premier jour local voulu, et écartez cette heure. Un fuseau avec un décalage d’une demi-heure nécessite des intervalles 1m, qui remontent au plus à 31 jours.
Autres routes de lecture
| Route | Fonction |
|---|---|
GET /api/telemetry/kinds | Les types de mesures de votre organisation (par exemple iot_device) |
GET /api/iot/devices/{deviceId}/elements | Les clés d’un appareil (déclarées dans son profil ou envoyées), 300 au maximum, avec libellés et unités |
Pour les écritures, les appareils utilisent MQTT ou HTTP ; l’API REST n’a aucune route d’écriture de télémétrie. Voir API HTTP des appareils et API de télémétrie et d’attributs.