1. Centre de Support Spacewell Energy
  2. Insertion de données
  3. Développement et intégration

Utiliser l'API d'insertion pour insérer des données dans une passerelle

S’abonner
Avatar
Jordi Garcia

Traduction à venir, trouvez ici l'article en anglais.

 

Cet article est un exemple étape par étape pour utiliser l'API d'insertion afin d'introduire des données dans une passerelle, en utilisant Postman pour les requêtes HTTP.

Qu'est-ce qu'une API d'insertion ?

L'API signifie Interface de Programmation d'Applications. C'est une interface informatique qui permet l'interaction entre plusieurs logiciels intermédiaires, tels que des sites web ou des applications web qui interagissent entre elles.

Une API d'insertion de données est une API qui permet d'envoyer des données afin qu'elles soient ensuite traitées et accessibles dans une application web, comme la plateforme EM.

L'API d'insertion permet à d'autres systèmes d'envoyer des données via Internet vers la plateforme en utilisant le protocole HTTP/HTTPS.

Vous pouvez en apprendre davantage sur les différentes manières d'envoyer des données vers la plateforme ici.

Vous pouvez en savoir plus sur les API ici.

Prérequis

Pour insérer des données, vous avez besoin de quelques éléments au préalable :

Du côté de la Plateforme

  • Avoir le rôle d'administrateur ou de super administrateur.

De votre côté

  • Vous aurez besoin d'une application capable de gérer des requêtes HTTP. Dans ce tutoriel, Postman sera utilisé, qui est gratuit.
  • Vous devriez avoir une compréhension de base du fonctionnement des requêtes HTTP.
  • Vous devrez préparer une requête HTTP POST comme détaillé plus loin dans cet article.

Du côté de votre réseau

Si votre réseau est protégé, vous devez vous assurer d'activer/mettre sur liste blanche les URL/IP suivantes ainsi que les ports.

Autres exigences

Il faut prendre en compte que les messages devant être insérés dans l'API ne doivent pas dépasser 5000 relevés par message.

De plus, il est à noter qu'il n'y a pas de limite de taux pour insert.dexma.com, cependant, pour obtenir un meilleur débit, nous recommandons :

 

Comment ça fonctionne ?

Obtenez les informations de sécurité de votre passerelle

Avant de configurer la requête pour envoyer des données, vous aurez besoin de certaines informations de la passerelle vers laquelle vous souhaitez envoyer des données (consultez cet article pour plus d'informations sur les passerelles).

Accédez à la passerelle où vous souhaitez envoyer vos données dans Configuration --> Passerelles. Si vous n'avez pas encore de passerelle sur votre compte, suivez les étapes de cet article pour créer votre première passerelle virtuelle.

La configuration de la passerelle doit lister 2 champs que vous devez noter, la Clé et le Token de la passerelle. Pour cet exemple, nous utiliserons les suivants :

  • Clé : mac-123456789
  • Token de la passerelle : token123456789

Notez ces informations car elles seront nécessaires pour construire la requête. Ne partagez pas ces informations avec des tiers.

dexma-api-insert-example-01.png

Si la passerelle vers laquelle vous souhaitez envoyer des données ne liste pas son token de passerelle, contactez votre fournisseur de support.

Avec la clé et le token de la passerelle, vous pouvez procéder à la construction de la requête HTTP.

Construire la requête

Pour envoyer les données via une requête HTTP, vous devez définir l'URL, les en-têtes et le corps de la requête.

Paramètres d'URL

L'URL de l'API d'insertion est insert.dexma.com/readings. Les paramètres sont ajoutés après l'URL pour fournir les informations de sécurité pertinentes. Exemple d'URL :

https://insert.dexma.com/readings?source_key=mac-123456789&dexcell_source_token=token123456789

Hôte : insert.dexma.com
Path : /readings
Méthode : HTTPS POST
Paramètres d'URL :

  • source_key : paramètre obligatoire. Il s'agit de l'adresse MAC de la passerelle ou de la clé unique qui identifie la source de données à laquelle les données appartiennent, que nous avons notée précédemment.
  • dexcell_source_token : le token d'authentification pour chaque passerelle. Ce token est utilisé comme couche de sécurité supplémentaire et peut être révoqué par le fournisseur de la plateforme si nécessaire. Ce n'est pas un paramètre obligatoire dans l'URL, mais il peut être utilisé.

Header de la requête

Un Header avec les informations de sécurité de la passerelle doit être défini. Cela est obligatoire et empêche toute personne sans le token d'envoyer des données à votre passerelle. Exemple de Header :

x-dexcell-source-token: token123456789
Content-Type: application/json

x-dexcell-source-token : le token d'authentification de la passerelle que vous avez noté précédemment.

Structure du message

​Le corps du message HTTP est un fichier JSON qui doit contenir la collection (tableau) du message que vous souhaitez insérer.

[{
     "did":"3a",
     "sqn":1,
     "ts":"2014-10-02T10:30:00+02:00",
     "values":[
        {
           "p":401,
           "v":3505
        },
        {
           "p":402,
           "v":5600012
        },
        {
           "p":404,
           "v":123504
        }
     ]
  },
{ ... },
{ ... }
]

La structure du message est la suivante :

  •  
  • "did" : String // max 25 caractères ; ID local de l'appareil
  • "sqn" : Integer // Numéro du message ; → Utilisé en interne pour le contrôle des relevés. Il doit être incrémental à partir de 1. Si vous ne pouvez pas l'envoyer, définissez-le sur "1".
  • "ts" : String // Format de date basé sur la norme ISO 8601, les formats disponibles sont :
  • "values" : Collection/Tableau // Contient tous les relevés avec leur ID de paramètre et leur valeur respective. La structure est la suivante :
    • "p" : Integer // ID du paramètre du type de données contenu ; se référer aux Paramètres
    • "v" : Float // valeur du relevé

Envoyer votre requête avec Postman

Votre URL de requête devrait ressembler à ceci :

http://insert.dexma.com/readings?source_key=mac-123456789

ou ceci :

https://insert.dexma.com/readings?source_key=mac-123456789&dexcell_source_token=token123456789

Où "source_key" est la clé de la passerelle que vous avez notée précédemment.

1. Allez sur Postman (ou le logiciel équivalent que vous utilisez) pour préparer la requête HTTP POST. L'écran par défaut de Postman devrait ressembler à ceci :

dexma-api-insert-example-02.png

2. Changez le type de requête de GET à POST dans le menu déroulant à gauche. Dans la zone de texte "Enter request URL", copiez votre URL :

http://insert.dexma.com/readings?source_key=mac-123456789

Assurez-vous de remplacer mac-123456789 par votre clé de passerelle. Votre écran devrait ressembler à ceci :

dexma-api-insert-example-04.png

3. Cliquez sur l'onglet Headers sous la barre d'URL et introduisez les en-têtes suivants :

  • x-dexcell-source-token : token123456789
  • Content-Type : application/json

Assurez-vous de remplacer token123456789 par votre token de passerelle. Votre écran devrait ressembler à ceci :

dexma-api-insert-example-03.png

4. Cliquez sur l'onglet Body sous la barre d'URL et introduisez le corps de votre requête. Votre écran devrait ressembler à ceci :

dexma-api-insert-example-05.png

5. Une fois que vous avez terminé cette configuration, cliquez sur le bouton Send pour envoyer votre requête HTTP et introduire les données dans la plateforme. Si la configuration est correcte, vous devriez obtenir une réponse 200 OK :

dexma-api-insert-example-06.png

Si votre requête échoue, passez en revue les étapes de configuration et assurez-vous que votre clé et votre token sont corrects.

Exemples

Exemple 1 : Envoi de données cumulées

Cet exemple montre comment insérer des données d'énergie active cumulées dans l'appareil "3" de la passerelle "123456789".
Selon la liste des paramètres, les données doivent être insérées dans le paramètre 402.

  • URL seulement :
https://insert.dexma.com/readings?source_key=mac-123456789&dexcell_source_token=123456789
  • URL et Header :
https://insert.dexma.com/readings?source_key=mac-123456789
x-dexcell-source-token:123456789

Corps du message : 

[{
     "did":"3",
     "sqn":1,
     "ts":"2014-10-02T10:30:00+00:00",
     "values":[
        {
           "p":402,
           "v":1250.0
        }
        ]
  },
  {
     "did":"3",
     "sqn":2,
     "ts":"2014-10-02T10:45:00+00:00",
     "values":[
        {
           "p":402,
           "v":1280
        }
        ]
  },
  {
     "did":"3",
     "sqn":3,
     "ts":"2014-10-02T11:00:00+00:00",
     "values":[
        {
           "p":402,
           "v":1298.3
        }
        ]
  }
]

Note importante : Pour les données cumulées, la plateforme utilise la convention qui consiste à attribuer la consommation entre deux horodatages A et B à A. Par exemple, une lecture avec un horodatage A de 2020-05-28T15:00:00 et une valeur de 1000 kWh, suivie d'une lecture avec un horodatage B de 2020-05-28T15:15:00 et une valeur de 1100 kWh, entraînera une consommation de 100 kWh attribuée à l'horodatage A (2020-05-28T15:00:00) dans l'interface. Cela signifie également que la plateforme ne calculera pas la consommation d'un intervalle tant qu'elle n'aura pas reçu la lecture à la fin de l'intervalle.

 

Exemple 2 : Envoi de données par intervalle

Cet exemple montre comment insérer des données d'énergie active par demi-heure dans l'appareil "5" de la passerelle "123456789".
Selon la liste des paramètres, les données doivent être insérées dans le paramètre 40261.

  • URL seulement :
https://insert.dexma.com/readings?source_key=mac-123456789&dexcell_source_token=123456789
  • URL et Header:
https://insert.dexma.com/readings?source_key=mac-123456789
x-dexcell-source-token:123456789

Corps du message :

[{
     "did":"5",
     "sqn":1,
     "ts":"2014-10-02T10:30:00+00:00",
     "values":[
        {
           "p":40261,
           "v":30.0
        }
        ]
  },
  {
     "did":"5",
     "sqn":2,
     "ts":"2014-10-02T10:45:00+00:00",
     "values":[
        {
           "p":40261,
           "v":18.3
        }
        ]
  }
]

 

Notes importantes :

  • Pour les données par intervalle, DEXMA utilise la convention consistant à tracer l'énergie consommée pendant l'intervalle dans le premier horodatage. Par exemple, de 20h00 à 20h30, l'énergie consommée est de 52 kWh, les données doivent être insérées dans l'horodatage de 20h00.
  • Pour les données par intervalle, vous devez envoyer l'horodatage du début de l'intervalle en fonction de la fréquence des données. Par exemple, si vous envoyez une consommation quotidienne, vous devez toujours spécifier la première heure du jour, en fonction de la notation que vous utilisez. Par exemple, une lecture quotidienne correspondant à la consommation d'énergie active quotidienne (paramètre 40221) le 28 juillet 2021 dans un fuseau horaire avec un décalage de +02:00 devrait être spécifiée de l'une des manières suivantes : 
    • 2021-07-28T22:00:00Z
    • 2021-07-28T00:00:00+02:00
  •  

Si vous envoyez un message avec un horodatage qui ne correspond pas au début de l'intervalle (par exemple 2021-07-28T22:15:00Z ou 2021-07-28T00:15:00+02:00), vous recevrez une réponse avec un statut "OK" (200), mais la lecture sera rejetée par le système d'insertion.

 

Exemple 3 : Envoi de données instantanées

Cet exemple montre comment insérer des données instantanées telles que la température (301) ou la puissance (401) dans l'appareil "7" de la passerelle "123456789".

  • ​URL seulement :
https://insert.dexma.com/readings?source_key=mac-123456789&dexcell_source_token=123456789
  • URL et Header :
https://insert.dexma.com/readings?source_key=mac-123456789
x-dexcell-source-token:123456789

Corps du message :

[{
     "did":"7",
     "sqn":1,
     "ts":"2014-10-02T10:30:00+00:00",
     "values":[
        {
           "p":301,
           "v":25.2
        },
        {
           "p":401,
           "v":2540
        }
        ]
  },
  {
     "did":"7",
     "sqn":2,
     "ts":"2014-10-02T10:45:00+00:00",
     "values":[
        {
           "p":301,
           "v":25.8
        },
        {
           "p":401,
           "v":1890
        }
        ]
  }
]

Pour toute assistance supplémentaire, veuillez contacter votre fournisseur de support.

 

Utiliser le Temps Zulu

Lorsque vous utilisez le Temps Zulu, veuillez garder à l'esprit d'ajouter le décalage horaire du fuseau horaire de la passerelle où vous insérez les données. Par exemple, une passerelle située dans la zone "Europe/Madrid" aura un décalage de +02:00 en été, et l'heure Zulu correspondante pour une lecture à minuit est la suivante : 2021-07-28T22:00:00Z. Si vous ne tenez pas compte de cela et envoyez une lecture avec un horodatage de 00:00:00Z, comme 2021-07-28T00:00:00Z, elle sera traitée par l'API avec un message "OK" (200), mais elle sera rejetée par le système d'insertion.

Avez-vous trouvé cet article utile ?

Articles dans cette section