Modele de donnees et format de payload MQTT

Cette page technique decrit l'API MQTT exacte de la fonctionnalite d'export MQTT. Utilisez ce format lorsque vous construisez un subscriber, un parser ou une pipeline de donnees qui consomme des messages EnergieID.

Pret a relier votre broker a EnergieID ? Pour les etapes de configuration, les droits et les messages d'erreur, consultez Export MQTT.

Concepts de base

• Workspace : l'environnement d'une organisation dans EnergieID.
• Record : un dossier dans un Workspace, le plus souvent un batiment ou une installation.
• Meter : une serie temporelle dans un dossier, par exemple la consommation de gaz, la production solaire ou le stockage batterie.
• Device (twin) : un appareil ou point de donnees connecte qui peut fournir des messages en temps reel.
• Channel : un canal de mesure dans les donnees d'appareil (key-value), par exemple la puissance, la tension, le courant ou la temperature.

Quels flux de donnees existent ?

• Donnees de compteur : lectures de compteur traitees provenant du dossier. Ces donnees ne sont pas en temps reel et sont publiees periodiquement. La frequence depend de l'integration et du type de compteur.
• Donnees d'appareil : donnees d'appareil en temps reel par connexion/integration. Toutes les integrations ne fournissent pas de donnees en temps reel ; certaines ne publient que des donnees de compteur.

Toutes les donnees d'appareil sont egalement publiees comme donnees de compteur, eventuellement agregees apres traitement, mais toutes les donnees de compteur ne sont pas publiees comme donnees d'appareil, car toutes les integrations ne fournissent pas de donnees en temps reel. Pour les analyses, il vaut donc mieux utiliser les donnees de compteur, car elles sont plus completes. Si vous voulez construire un tableau de bord en temps reel, utilisez plutot les donnees d'appareil.

Donnees de compteur

Topic par defaut : energyid/workspace/{{workspaceId}}/record/{{recordNumber}}/meter/{{meterId}}

Les donnees de compteur sont publiees sous la forme d'un objet JSON contenant des metadonnees et un tableau data.

{
  "workspaceId": "7e8f2f7e-2c9f-4e90-bf2e-8e1c6b6f5f6c",
  "recordNumber": "EA-1234567",
  "meterId": "3c2a6b8f-7f0a-45b4-9d4a-6f73b30e30aa",
  "metric": "electricityImport",
  "unit": "kWh",
  "readingType": "PostmarkedInterval",
  "interval": "PT15M",
  "data": [
    {
      "timestamp": "2026-08-06 10:15:00+02:00",
      "value": 1.42,
      "min": 1.21,
      "max": 1.55,
      "mean": 1.39
    }
  ]
}

Champs

• workspaceId : GUID du Workspace.
• recordNumber : numero du dossier.
• meterId : GUID du compteur.
• metric : code de metrique indiquant ce qui est mesure.
• unit : unite associee a cette metrique.
• readingType : type de mesure, qui precise comment interpreter une valeur, par exemple Counter ou Gauge.
• interval : periodicite de mesure ISO-8601, par exemple PT5M, PT15M, PT1H, P1D, ou manual pour les mesures non periodiques.
• data[].timestamp : timestamp avec offset.
• data[].value : valeur principale de la mesure.
• data[].min / max / mean : uniquement pertinent pour des donnees de type gauge ; peut manquer ou etre null pour d'autres types.

Important : Les champs metric, unit et readingType sont des Enums, il existe donc un ensemble fixe de valeurs possibles. Pour une vue a jour de toutes les valeurs possibles, consultez la documentation API des ressources meter : EnergyID API reference - Meters.

Donnees d'appareil

Topic par defaut : energyid/workspace/{{workspaceId}}/record/{{recordNumber}}/device/{{twinId}}

Les donnees d'appareil sont publiees evenement par evenement au format JSON.

{
  "recordNumber": "EA-1234567",
  "twinId": "f2a13f6d-1d7a-4f14-b5e8-a53c9f638f1c",
  "timestamp": 1754477700,
  "channels": {
    "pwr": 430.2,
    "el": 230.1
  }
}

Champs

• recordNumber : numero du dossier.
• twinId : GUID de l'appareil/digital twin.
• timestamp : timestamp Unix (secondes).
• channels : map key-value avec les canaux de mesure et des valeurs numeriques.

Detail des channels

Les cles exactes dans channels dependent du type d'appareil et de l'integration connectee. EnergieID traite les channels comme un ensemble de mesures flexible, de sorte que l'ensemble des cles peut varier selon le message ou le type d'appareil.

Caracteristiques typiques des channels :

• Chaque cle est un nom de mesure, par exemple el, pwr, bat ou heat.
• Chaque valeur est numerique (floating point).
• Toutes les cles ne sont pas toujours presentes ; les subscribers doivent gerer defensivement les cles manquantes ou supplementaires.
• La signification et l'unite d'une cle de channel dependent de l'integration et du type d'appareil.

Ci-dessous, vous trouverez une liste des channels standards et la maniere dont nous les mappont dans nos systemes :

QoS et comportement retain

• Les messages sont publies avec la QoS AtLeastOnce (QoS 1).
• Pour les donnees de compteur, le publisher utilise un flag retain afin que le dernier payload connu puisse etre conserve sur le topic par le broker.
• Pour les donnees d'appareil en temps reel, les messages sont publies sans retain.

Erreurs et robustesse

• En cas d'echec de connexion ou de publication, EnergieID journalise un echec de livraison specifique au broker dans les parametres du Workspace.
• Apres un echec, le publisher reessaie avec une nouvelle connexion.
• Lors du premier echec, un administrateur du Workspace recoit un message dans le centre de messages.