Transmission des données

Format d'un Stream

Les données suivent le même format en HTTPS et MQTTS.

info

Deux versions sont supportées :

• v2 : sans sécurité supplémentaire
• v3 : ajoute un checksum pour garantir l'intégrité des données

Champs

Champ	Type	Description	Protocoles
device	string	Identifiant unique de l'équipement (Device developer ID). Visible dans Administration.	v2, v3
at	number	Horodatage Unix du stream.	v2, v3
protocol	string	Version du protocole (v2 ou v3).	v2, v3
data	objet	Contient les datasets (ensembles de données).	v2, v3
checksum	string	Hash SHA1 pour vérifier l'intégrité (v3 uniquement).	v3

Exemple de Stream

{
  "protocol": "v3",
  "device": "000000-0000-0000-000000",
  "at": 1554884039,
  "checksum": "xxxxxxxxxxx", // un commentaire
  "data": {
    "ver": "S1",
    "dataset": []
  }
}

---

Format d'un Dataset

Chaque stream contient une liste de datasets, chacun représentant un ensemble de mesures.

Champs

Champ	Type	Description
ref	string	Référence de la variable. Peut suivre la syntaxe <itemType>|<itemIndex>|<serviceId> ou simplement <serviceId>. Une variable est créée automatiquement si la référence n'existe pas.
at	number	Horodatage Unix de la mesure.
value	number	Valeur de la donnée.

Exemple simple

{
  "ref": "variableId",
  "at": 1554884039,
  "value": 42
}

Format complet d'un Dataset

{
  "protocol": "v3",
  "device": "000000-0000-0000-000000",
  "at": 1554884039,
  "checksum": "xxxxxxxxxxx",
  "data": {
    "ver": "S1",
    "dataset": [
      { "at": 1554884039, "ref": "variableId1", "value": 21 },
      { "at": 1554884039, "ref": "variableId2", "value": 42 }
    ]
  }
}

Chaque dataset contient donc :

• une référence (ref) identifiant la variable concernée ;
• un timestamp (at) correspondant à la date de mesure (Unix timestamp) ;
• une valeur numérique (value).

---

Format compact (columns et values)

Ce format permet de réduire la taille du payload.

Champ	Type	Description
columns	Liste<string>	Liste des champs décrits dans values.
values	Liste<Liste>	Liste des valeurs dans le même ordre que columns.

Exemple : plusieurs mesures au même instant

{
  "protocol": "v3",
  "device": "000000-0000-0000-000000",
  "at": 1554884039,
  "checksum": "xxxxxxxxxxx",
  "data": {
    "ver": "S1",
    "dataset": [
      {
        "at": 1554884039,
        "columns": ["ref", "value"],
        "values": [
          ["variableId1", 21],
          ["variableId2", 42]
        ]
      }
    ]
  }
}

Exemple : même variable à plusieurs instants

{
  "protocol": "v3",
  "device": "000000-0000-0000-000000",
  "at": 1554884039,
  "checksum": "xxxxxxxxxxx",
  "data": {
    "ver": "S1",
    "dataset": [
      {
        "ref": "variableId",
        "columns": ["at", "value"],
        "values": [
          ["1554884039", 21],
          ["1554910094", 22]
        ]
      }
    ]
  }
}

Exemple : valeurs, timestamps et références multiples

{
  "protocol": "v3",
  "device": "000000-0000-0000-000000",
  "at": 1554884039,
  "checksum": "xxxxxxxxxxx",
  "data": {
    "ver": "S1",
    "dataset": [
      {
        "columns": ["ref", "at", "value"],
        "values": [
          ["variableId1", "1554884039", 21],
          ["variableId2", "1554910094", 42]
        ]
      }
    ]
  }
}

---

Calcul du checksum (v3)

Le checksum garantit la non-falsification des données.

1. Concaténez les champs at et data du stream, sans espaces.
2. Appliquez un hash SHA1 avec le mot de passe de l'équipement comme clé.

astuce

Il est recommandé de tester d'abord le format v2 (sans checksum) avant de passer en v3.

Exemple de transmission de données

Dans cet exemple, nous allons simuler un envoi de point de données à l'aide de Postman.

info

Nous utilisons ici le protocole v2, le checksum n'est donc pas nécessaire.

Étape 1 : Récupérer les informations du device

Pour envoyer des données, vous devez récupérer :

• La Clé API du site propriétaire de la variable
• Le Device Developer ID de l'équipement

Clé API et Device ID

Cliquer pour ouvrir

Étape 2 : Récupérer la référence de la variable

Cliquez sur la variable cible et notez son Stream Ref (MappingConfig DataHub).

Stream Ref de la variable

Cliquer pour ouvrir

Étape 3 : Configurer la requête Postman

Configurez votre requête comme suit :

Paramètre	Valeur
Méthode	POST
URL	https://streams-api.magicbuilder.io/streams
Header	apikey: {VOTRE_CLÉ_API}

Configuration du header Postman

Cliquer pour ouvrir

Étape 4 : Configurer le body

Configuration du body Postman

Cliquer pour ouvrir

Étape 5 : Vérifier le résultat

Si tout s'est bien passé, vous obtiendrez la réponse suivante :

{
  "response": "OK"
}

La donnée sera transmise et visible sur la variable dans l'onglet Données.

Résultat de la transmission

Cliquer pour ouvrir