Notice MicroSERVER - Documentation technique sur Sirea Docs

Dernière modification le 28/09/2022 10:36

1. Lecteurs ciblés
2. Présentation de l’application
3. API

1. Lecteurs ciblés

Cette documentation est à destination des utilisateurs de l’application MicroSERVER, permettant la visualisation de données collectées depuis des automates SIREA.

2. Présentation de l’application

A venir …

3. API

3.1 Obsolescence

Cette API est disponible sur MicroSERVER jusqu’à la version vX.

3.2 Généralités

Ce document détaille les requêtes HTTP permettant à l’utilisateur d’interagir avec MicroSERVER au travers de fonctions PHP, fournissant ainsi une interface de communication entre le serveur Web et d’autres services externes.

3.3 Fonctions

3.3.1 Authentification

Syntaxe Python :

import requests
server_uri = 'URI'
user = 'USER'
password = 'PASS'
query = 'QUERY'
resp = requests.post(server_uri + query, {'usr': user, 'pwd': password})

Syntax AJAX :

var user = 'USER';
var password = 'PASS';
var query = 'QUERY';
function on_response(data, status, xhr) {
    // do something
}
$.post(query, {usr: user, pwd: password}, on_response);

Paramètre	Commentaire
URI	Adresse IP ou nom d’hôte du serveur hébergeant la base de données
USER	Identifiant de connexion
PASSWORD	Mot de passe associé à l’identifiant de connexion
QUERY	Requête selon les fonctions PHP listées dans le document suivant

Avertissement
Pour des raisons de sécurité, veuillez utiliser la méthode POST pour les paramètres "usr" et "pwd".

Exemple de requête Python :

import requests
server_uri = 'https://192.168.43.108'
user = 'username'
password = 'password'
query = '/get_variables?dev=1'
resp = requests.post(server_uri + query, {'usr': user, 'pwd': password})

Exemple de requête AJAX :

var user = 'username';
var password = 'password';
var query = '/get_variables?dev=1';
function on_response(data, status, xhr) {
    // do something
}
$.post(query, {usr: user, pwd: password}, on_response);

3.3.2 get_variables.php

Cette requête récupère la valeur d’une ou plusieurs variables.

/get_variables.php?dev=DEV&var1=N1&var2=N2&...&varn=Nn

Paramètre	Commentaire
DEV	ID de l’équipement
N1, N2, Nn	ID (ou adresse ou mnémonique) de la variable à partir de laquelle la valeur doit être récupérée. Une même requête permet de récupérer la valeur d’une ou plusieurs variables, sans limite

Information
Vous pouvez utiliser le paramètre "dev" OU les paramètres "var", mais un seul d'entre eux est obligatoire.

Syntaxe de la réponse XML :

<update>
   <variable>
	<timestamp></timestamp>
	<rowid></rowid>
      <address></address>
      <name></name>
	<value></value>
	<fvalue></fvalue>
	<alarm></alarm>
      <ack></ack>
   </variable>
   <variable>
	<timestamp></timestamp>
	<rowid></rowid>
      <address></address>
      <name></name>
	<value></value>
	<fvalue></fvalue>
	<alarm></alarm>
      <ack></ack>
   </variable>
</update>

Tag	Commentaire
<timestamp>	Moment du dernier changement de la variable, mesuré en secondes depuis le 1er septembre 1970
<rowid>	Identifiant de la variable
<address>	Adresse de la variable
<name>	Mnémonique de la variable
<value>	Valeur de la variable, non formatée
<fvalue>	Valeur de la variable, formatée selon le format défini dans MicroSERVER
<alarm>	0 lorsqu’il n’y a pas d’alarme active associée à cette variable et 1 s’il y a des alarmes actives associées à cette variable
<ack>	0 lorsque l’alarme n’est pas acquittée et 1 si l’alarme est acquittée

Exemple de requête :

https://192.168.43.108/get_variables.php?dev=4&var1=17&var2=18

Exemple de la réponse XML :

<update>
   <variable>
      <timestamp>1415788199.94717</timestamp>
      <rowid>17</rowid>
      <value>12</value>
      <address>%POW</address>
      <name>power</name>
      <fvalue>12 W</fvalue>
      <alarm>0</alarm>
      <ack>0</ack>
   </variable>
   <variable>
      <timestamp>1415788167.98588</timestamp>
      <rowid>18</rowid>
      <address>%POW</address>
      <name>power</name>
      <value>10</value>
      <fvalue>10 A</fvalue>
      <alarm>1</alarm>
      <ack>0</ack>
   </variable>
</update>

3.3.3 get_al.php

Cette requête récupère toutes les alarmes actives dans MicroSERVER, ou toutes les alarmes actives associées à une variable ou à un équipement.

/get_al.php?dev=DEV&var=VAR

Paramètre	Commentaire
DEV	ID de l’équipement
VAR	ID (ou adresse ou mnémonique) de la variable à partir de laquelle la valeur doit être récupérée.

Information
Vous pouvez utiliser le paramètre "dev" OU les paramètres "var".

Syntaxe de la réponse XML :

<update>
   <entry>
      <timestamp></timestamp>
      <log_index></log_index>
      <var_index></var_index>
      <dev_index></dev_index>
      <alarm></alarm>
      <ack_timestamp></ack_timestamp>
      <ack_user></ack_user>
      <ack_comment></ack_comment>
   </entry>
</update>

Tag	Commentaire
<timestamp>	Moment du dernier changement de la variable, mesuré en secondes depuis le 1er septembre 1970
<log_index>	ID de l’entrée du journal concernant l’alarme
<var_index>	ID de la variable associée à l’événement
<dev_index>	ID de l’équipement auquel appartient la variable
<alarm>	Libellé de l’alarme associé à l’alarme active
<ack_timestamp>	Moment de l’acquittement de l’alarme, si acquitté ; sinon ce champ reste vide
<ack_user>	Identification de l’utilisateur qui a acquitté l’alarme, si acquittée ; sinon ce champ reste vide
<ack_comment>	Commentaire relatif à l’acquittement d’alarme indiqué par ack_user si acquitté ; sinon ce champ reste vide

Exemple de requête :

https://192.168.43.108/get_al.php?dev=4&var=10

Exemple de la réponse XML :

<update>
   <entry>
      <timestamp>1415788199.94717</timestamp>
      <log_index>7693</log_index>
      <var_index>10</var_index>
      <dev_index>4</dev_index>
      <alarm>Communication default</alarm>
      <ack_timestamp></ack_timestamp>
      <ack_user></ack_user>
      <ack_comment></ack_comment>
   </entry>
</update>

3.3.4 get_bg.php

Cette requête récupère les données à partir d’une date de début et les regroupe selon la période demandée pour chaque variable.

/get_bg.php?time=TIME&period=PERIOD&tz=TZ&var1=N1&var2=N2&...&varn=Nn

Paramètre	Commentaire
TIME	Début de la période sous forme de timestamp
PERIOD	Type de période: – 1 = Une année de données cumulées par mois – 2 = Un mois de données cumulées par jour – 3 = Un jour de données cumulées par heure – 4 = Une heure de données cumulées par pas de 5 minutes
TZ	Chaîne du fuseau horaire, par exemple “Europe/Paris”
N1, N2, Nn	ID (ou adresse ou mnémonique) de la variable à partir de laquelle la valeur doit être récupérée. Une même requête permet de récupérer la valeur d’une ou plusieurs variables, sans limite

Information
Le paramètre « var1 » est obligatoire.

Syntaxe de la réponse XML :

<update>
   <entry>
      <var_index></var_index>
      <timestamp></timestamp>
      <value1></value1>
   </entry>
</update>

Tag	Commentaire
<var_index>	ID de la variable définie
<timestamp>	Moment du début de la période, mesuré en secondes depuis le 1er septembre 1970
<value1>	Valeur de la variable, non formatée

Exemple de requête :

https://192.168.43.108/get_bg.php?time=1415788199.94717&period=1&var=10

Exemple de la réponse XML :

<update>
   <entry>
      <var_index>10</var_index>
      <timestamp>1415788199.94717</timestamp>
      <value1>4</value1>
   </entry>
   <entry>
      <var_index>10</var_index>
      <timestamp>1418380199.94717</timestamp>
      <value1>4</value1>
   </entry>
</update>

Information
Le nom de champ correct pour "valeur" est <valeur1> et non <valeur>.

3.3.5 get_tr.php

Cette requête récupère un ensemble de valeurs sur une période définie pour chaque variable.

/get_tr.php?mintime=MINTIME&maxtime=MAXTIME&np=NP&pval=PVAL&pmult=PMULT&var1=N1&...&varn=Nn

Paramètre	Commentaire
MINTIME	Début de la période sous forme de timestamp
MAXTIME	Fin de la période sous forme de timestamp
NP	Limite maximale de valeurs à récupérer
N1, Nn	ID (ou adresse ou mnémonique) de la variable à partir de laquelle la valeur doit être récupérée. Une même requête permet de récupérer la valeur d’une ou plusieurs variables, sans limite
PVAL, PMULT	Période sous la forme « pval * pmult » secondes. Par exemple, pour « 4 heures », pval = 4 et pmult = 3600

Information
Le paramètre « var1 » est obligatoire.

Syntaxe de la réponse XML :

<update>
   <entry>
      <timestamp></timestamp>
      <rowid></rowid>
      <var_index></var_index>
      <value></value>
   </entry>
</update>

Tag	Commentaire
<timestamp>	Moment du point, mesuré en secondes depuis le 1er septembre 1970
<rowid>	ID de l’entrée de journal du point
<var_index>	ID de la variable définie
<value>	Valeur du point, non formatée

Exemple de requête :

https://192.168.43.108/get_tr.php?mintime=1415788199.94717&maxtime=1418380199.94717&np=1&pval=4&pmult=3600&var1=10

Exemple de la réponse XML :

<update>
   <entry>
      <timestamp>1415788199.94717</timestamp>
      <rowid>546</rowid>
      <var_index>10</var_index>
      <value>24</value>
   </entry>
   <entry>
      <timestamp>1418380199.94717</timestamp>
      <rowid>547</rowid>
      <var_index>10</var_index>
      <value>26</value>
   </entry>
</update>

3.3.6 get_log.php

Cette requête récupère un ensemble d’événements sur une période définie pour chaque variable.

/get_log.php?cat=CAT&lastid=LASTID&period=PERIOD&mintime=MINTIME&maxtime=MAXTIME&var1=N1&...&varn=Nn

Paramètre	Commentaire
CAT	Catégorie du journal à récupérer : – 2 = Événements – 3 = Alarmes – 4 = Valeurs
LASTID	ID de l’entrée du journal à partir duquel récupérer les résultats suivants
PERIOD	Durée de la période en secondes depuis la date actuelle.
MINTIME	Début de la période sous forme de timestamp
MAXTIME	Fin de la période sous forme de timestamp
N1, Nn	ID (ou adresse ou mnémonique) de la variable à partir de laquelle la valeur doit être récupérée. Une même requête permet de récupérer la valeur d’une ou plusieurs variables, sans limite

Information
Le paramètre « var1 » est obligatoire et si « period » est fourni, « mintime » et « maxtime » sont ignorés.

Syntaxe de la réponse XML :

<log>
   <entry>
      <rowid></rowid>
      <dev_index></dev_index>
      <var_index></var_index>
      <var_address></var_address>
      <var_name></var_name>
      <value></value>
      <ack_timestamp></ack_timestamp>
      <ack_user></ack_user>
      <ack_comment></ack_comment>
      <timestamp></timestamp>
   </entry>
</log>

Tag	Commentaire
<rowid>	ID de l’entrée de journal du point
<dev_index>	ID de l’équipement défini (si pas de variable définie)
<var_index>	ID de la variable définie
<var_address>	Adresse de la variable définie (si pas de variable définie)
<var_name>	Nom de la variable définie (si pas de variable définie)
<value>	Valeur du point, non formatée
<ack_timestamp>	Timestamp de l’acquittement, mesuré en secondes depuis le 1er septembre 1970 (si « cat » = 3)
<ack_user>	Identifiant de l’utilisateur qui a acquitté (si “cat” = 3)
<ack_comment>	Commentaire de l’acquittement (si “cat” = 3)
<timestamp>	Moment du dernier changement de la variable, mesuré en secondes depuis le 1er septembre 1970

Exemple de requête :

https://192.168.43.108/get_log.php?cat=3&lastid=1234&period=60&var1=10

Exemple de la réponse XML :

<log>
   <entry>
      <rowid>1235</rowid>
      <var_index>10</var_index>
      <value>1</value>
      <ack_timestamp>1415788199.94717</ack_timestamp>
      <ack_user>admin</ack_user>
      <ack_comment>ok</ack_comment>
      <timestamp>1415785429</timestamp>
   </entry>
</log>

3.3.7 set_variables.php

Cette requête met à jour une ou plusieurs variables.

/set_variables.php?var1=N1&...&varn=Nn&value1=V1&...&valuen=Vn

Paramètre	Commentaire
N1, N2	ID (ou adresse ou mnémonique) de la variable à partir de laquelle la valeur doit être récupérée. Une même requête permet de récupérer la valeur d’une ou plusieurs variables, sans limite
V1, V2	Valeur de la variable à partir de l’ordre des paramètres “var” de la requête.

Information
Le paramètre « var1 » et le paramètre « value1 » sont obligatoires.

Syntaxe de la réponse XML :

<update>
   <variable>
      <status></status>
      <error></error>
   </variable>
</update>

Tag	Commentaire
<status>	« OK » ou « ERR »
<error>	Correspond à un code d’erreur

Exemple de requête :

https://192.168.43.108/set_variables.php?var1=10&var2=11&value1=25&value2=27

Exemple de la réponse XML :

<update>
   <variable>
      <status>OK</status>
   </variable>
   <variable>
      <status>ERR</status>
      <error>XXX</error>
   </variable>
</update>

3.3.8 set_user.php

Cette requête met à jour les informations relatives à l’utilisateur connecté.

/set_user.php?new_pwd=NPASS&locale=LOCALE&email=EMAIL&phone_number=PHONE&active_report_filter=ARF&inactive_report_filter=IRF

Paramètre	Commentaire
NPASS	Nouveau mot de passe de l’utilisateur
LOCALE	Format régional sous forme de code ISO 639-1 de l’utilisateur
EMAIL	E-mail de l’utilisateur
PHONE	Numéro de téléphone de l’utilisateur
ARF, IRF	Période de filtre de rapport actif ou inactif de l’utilisateur. Chaque point doit être séparé par un point virgule, et chaque point est composé de 4 champs : – Premier champ : Jour de la semaine (lundi = 1, dimanche = 7) – Deuxième champ : Jour du mois (1 à 31) – Troisième champ : Mois (1 à 12) – Quatrième champ : Heure (0 à 23) Chaque champ doit être séparé par un espace. Vous pouvez mettre une valeur, ou plusieurs séparées par une virgule, ou une étoile pour dire « tout ». Par exemple : « 2,5 * * *;7 1 2,10 3 » signifie tous les mardis ou vendredis de l’année ET le dimanche 1er de février ou d’octobre à 3h du matin.

Avertissement
Seuls les codes ISO 639-1 "fr", "gb" et "us" sont pris en charge par le paramètre "locale".

Syntaxe de la réponse XML :

<update>
   <variable>
      <status></status>
   </variable>
</update>

Tag	Comment
<status>	« OK » ou « ERR »

Exemple de requête :

https://192.168.43.108/set_user.php?new_pwd=newpass&locale=fr&email=contact@exemple.com&phone_number=0600000000&inactive_report_filter=2,5+*+*+*;7+1+2,10+3

Information
Les espaces doivent être remplacés par "+" ou "%20" dans la requête HTTP pour être considérés comme des espaces.

Exemple de la réponse XML :

<update>
   <variable>
	<status>OK</status>
   </variable>
</update>

doc.pdf

Besoin d'aide ?

Notre équipe vous accompagne et pourra répondre à toutes vos questions.

Prendre contact