SmartSense fournit un ensemble de points de terminaison permettant de collecter par programmation des données relatives aux actifs et aux capteurs. SmartSense regroupe les appareils, les capteurs et leurs mesures au sein d'unités logiques appelées « actifs ». Passons en revue quelques définitions ci-dessous.
Définitions
Actif – Un actif est une abstraction logique d’un élément faisant l’objet d’une surveillance. Un réfrigérateur ou un congélateur en est un exemple courant.
Valeur mesurée par un capteur – Une valeur mesurée par un capteur est un chiffre ou un ensemble de données issu des informations fournies par un capteur, telles que celles relatives à la température ou à l'humidité.
Point de capteur – Un point de capteur est une abstraction logique de ce qui est surveillé. Un réfrigérateur, par exemple, peut comporter un point de capteur de température et un point de capteur d’humidité.
Les points de capteur ne peuvent pas être déplacés d’un équipement à l’autre et ne peuvent être associés qu’à un seul capteur à la fois.
Capteur – Un capteur est un dispositif qui mesure des paramètres physiques tels que la température ou l'humidité du moment. Dans SmartSense, un capteur est associé à un point de mesure afin de relier ses données à un actif.
Un capteur est également associé à un seul appareil, jamais à plusieurs.
Exemple : un magasin dispose d’un réfrigérateur et d’un actif dans SmartSense. La température et l’humidité à l’intérieur du réfrigérateur doivent être surveillées ; l’actif dispose donc de deux points de mesure, un pour la température et un pour l’humidité.
À l’intérieur du réfrigérateur se trouve un appareil auquel sont associés un capteur de température et un capteur d’humidité. Dans SmartSense, ces capteurs sont associés aux points de mesure de l'actif. Si l’appareil situé dans le réfrigérateur est remplacé par un nouvel appareil équipé de nouveaux capteurs, ces derniers seront associés aux mêmes points de mesure de l’actif dans SmartSense.
La consultation des mesures des points de mesure du réfrigérateur affichera les mesures du premier jeu de capteurs pour la période où ils étaient connectés aux points de mesure, ainsi que celles des nouveaux capteurs après leur installation.
Appareil – Les appareils transmettent les données des capteurs au cloud SmartSense ; un capteur doit être connecté à un appareil pour pouvoir effectuer correctement une mesure.
Types de données spécifiques
L'API SmartSense Data définit les types suivants :
Dates
Les paramètres de type « date » doivent être envoyés au service (et proviennent de celui-ci) sous la forme d'une date et d'une heure combinées au format ISO 8601. Les informations relatives au fuseau horaire doivent être incluses, faute de quoi les résultats de l'appel API ne sont pas définis.
Remarque : toutes les dates fournies par le service sont exprimées en UTC.
date de lecture
readingDate indique l'instant auquel une mesure a été enregistrée par un capteur ou un appareil. Par exemple, un capteur de température a enregistré une température de 32,45 °F le vendredi 15 janvier à 15 h 17, heure UTC.
date de traitement
La propriété « processedDate » indique l'instant auquel une mesure a été traitée par SmartSense.
Exemple : un capteur de température externe, connecté à un appareil, enregistre une température de 32,45 °F le vendredi 15 janvier à 15 h 17 (UTC). En raison d'une interruption du réseau mobile, l'appareil ne parvient pas à envoyer la mesure à SmartSense pendant cinq minutes. Ainsi, la mesure aura une « readingDate » (date de mesure) de 15 h 17, mais une « processedDate » (date de traitement) de 15 h 22.
Les applications utilisant cette API pour récupérer toutes les mesures traitées par SmartSense doivent utiliser le filtre « processedAfterDate » pour demander les nouvelles mesures enregistrées depuis la dernière requête.
date de la dernière activité
lastActivityDate indique la date et l'heure auxquelles un appareil ou un capteur a contacté SmartSense pour la dernière fois. Si l'appareil n'a jamais contacté SmartSense, ce champ sera nul.
Chiffres
Identifiant de l'appareil
Le champ « deviceId » est un nombre à 20 chiffres qui est converti en chaîne de caractères avant d'être transmis. Cette conversion en chaîne de caractères vise à faciliter l'interopérabilité.
Valeurs de lecture de la puissance
Un type de lecture « Power » indique l'état de l'alimentation d'un appareil. Les valeurs vont de 0 à 10 pour les appareils fonctionnant uniquement sur batterie (par exemple, le capteur sans fil Z-Point). Pour les appareils alimentés sur secteur et dotés d'une batterie de secours, les valeurs vont de 16 à 26 lorsque l'appareil est branché et de 0 à 10 lorsqu'il ne l'est pas. Une valeur de 16 indique une alimentation exclusivement sur secteur, tandis qu'une valeur supérieure à 16 indique une alimentation sur secteur complétée par une alimentation de secours par batterie.
Valeurs de mesure de la puissance du signal
La mesure de la puissance du signal d'un appareil correspond à une valeur normalisée représentant l'état du signal sans fil de cet appareil. Les valeurs sont comprises entre 1 et 10.
Gravité de l'incident
La « gravité d'un incident » décrit le niveau de gravité d'un incident ou d'une alarme. La gravité d'un incident correspond toujours à la gravité la plus élevée de toutes les alarmes associées à cet incident. La gravité d'une alarme correspond toujours à la gravité configurée pour l'alarme qui l'a générée. Ce type comporte 5 valeurs :
1 : Le plus bas
2 : Faible
3 : Moyen
4 : Élevé
5 : Le plus élevé
Statut de l'incident
« IncidentStatus » décrit l'état d'un incident. Ces valeurs peuvent être mises à jour par le système à mesure que de nouvelles mesures sont enregistrées, qui peuvent soit désactiver, soit redéclencher des alarmes, ou par les utilisateurs qui interagissent avec les incidents via l'interface utilisateur. Ce type comporte 4 valeurs :
0 : Nouveau
1 : Actif
2 : En attente
99 : Fermé
Le statut « Nouveau » signifie que le système a créé l’incident, mais qu’aucune action n’a été effectuée par un utilisateur. Le statut « Actif » indique qu’un utilisateur a été affecté à l’incident. Le statut « En attente » est fonctionnellement identique au statut « Actif », à cette différence près qu’un utilisateur a choisi de mettre l’incident en attente dans l’interface utilisateur. Le statut « Fermé » signifie que l’incident est résolu et qu’il ne sera plus utilisé par le système ; cela implique que de nouveaux dépassements de valeurs de mesure entraîneront la création de nouveaux incidents.
État de l'alarme
AlarmStatus décrit l'état d'une alarme. Un incident pouvant comporter plusieurs alarmes, leur état est suivi séparément pour chacune d'entre elles. Ce type prend 4 valeurs :
0 : Fermé
1 : Ouvrir
2 : Reçu
3 : Résolu
Le statut « Fermé » signifie que le système ne prendra plus aucune mesure concernant cette alarme. Tout nouveau dépassement de la valeur de mesure entraînera le déclenchement d’une nouvelle alarme. Le statut « Ouvert » signifie que l’alarme est active. La valeur de mesure actuelle est hors plage et l’alarme nécessite une intervention de l’utilisateur. Le statut « Acquitté » correspond au statut « Ouvert », mais indique en outre qu’un utilisateur a acquitté l’alarme dans l’interface utilisateur. Une alarme « Résolue » signifie que les valeurs de mesure sont revenues dans la plage autorisée.
Opérateur de violation
ViolationOperator décrit l'opérateur relationnel utilisé pour comparer une valeur mesurée à un seuil d'alarme. Tous les incidents et toutes les alarmes sont générés par le système en comparant les valeurs mesurées par les capteurs aux seuils d'alarme configurés. Ces seuils se composent d'une valeur et d'un opérateur de comparaison, qui sont également enregistrés dans l'instance d'alarme. Ce type comporte 3 valeurs :
-1 : Inférieur à
0 : Égal à
1 : Supérieur à
Type de seuil
Le paramètre « ThresholdType » décrit le type de mesure pour lequel une alarme est configurée ou déclenchée. Chaque incident ne prendra en compte que les alarmes relatives à un seul type de mesure. Prenons l'exemple d'un équipement équipé à la fois de capteurs de température et d'humidité, pour lequel deux alarmes ont été configurées : une pour la température et une pour l'humidité. Si les deux capteurs sortent de la plage définie pour leur alarme respective, deux incidents (un par type de mesure) seront créés. Le type de mesure associé à chaque incident est identifié à l'aide de cette énumération ThresholdType. Les valeurs possibles pour ce type sont les suivantes :
1 : Température
2 : Rapport manquant
3 : Humidité
4 : Alimentation
5 : Vitesse du vent
6 : Humidité du sol
7 : Inondation
8 : Tension
9 : Pression
10 : Pression (pascal)
11 : Humidité des feuilles
12 : Précipitations
13 : Pourcentage de CO2
14 : Pourcentage d'O₂
15 : Pression OLPHC
16 : Contact sec
17 : Pression en centipascals
18 : Alimentation – Batterie faible
20 : Pression Starwatch
21 : Niveau Starwatch
23 : Pression en kilopascals
24 : Courant en milliampères
25 : Ampère
26 : Charge
27 : Niveau
28 : Capacité en picofarads
99 : Validation
Énumérations
Les énumérations sont des types de variables dont l'ensemble des valeurs est limité ; les champs de type énumération sont renvoyés sous forme de chaînes de caractères au format JSON. La valeur de la chaîne sera limitée aux valeurs possibles de l'énumération, telles que définies pour le type. Tous les types d'énumération peuvent prendre la valeur null.
Type de lecture
Indique le type de lecture.
Valeurs :
« Température »
« Humidité »
« Puissance »
« Puissance du signal »
Unité
Indique l'unité de mesure d'une valeur relevée.
Valeurs :
« F »
« C »
« % »
Type d'appareil
Indique le type de périphérique.
Valeurs :
« Nœud »
« Répéteur »
« Gateway »
Type de capteur
Indique le type de capteur.
Valeurs :
« Température »
« Humidité »
Liste des identifiants
Pagination des résultats
La pagination des résultats est une méthode qui consiste à répartir plusieurs résultats de recherche sur des pages distinctes afin de rendre les informations plus claires, d’éviter de surcharger le service et de limiter les problèmes de délai d’expiration. La pagination permet également de limiter les réponses, de sorte que l’ensemble des données ne soit pas récupéré à chaque requête. De nombreux points de terminaison qui renvoient une liste de données font l’objet d’une pagination.
Les réponses paginées incluent les informations de pagination suivantes :
Nom | Type | Description |
nombre total | Nombre total de résultats trouvés pour cette requête. | |
pageSize | Nombre maximal d'éléments pouvant être renvoyés dans cette réponse. | |
nombre | Le nombre réel d'éléments renvoyés dans cette réponse. | |
numéro de page | Le numéro de la page actuelle. Ce numéro commence à 1. |
S'il existe une page supplémentaire, un lien vers la page suivante est indiqué dans l'en-tête de réponse HTTP appelé « next ». Cet en-tête peut inclure des valeurs par défaut pour les paramètres GET non obligatoires qui n'ont pas été spécifiés dans la requête d'origine ; il est donc préférable d'utiliser cet en-tête plutôt que de créer manuellement l'URI de la page suivante afin de garantir des résultats corrects.
La valeur par défaut de « pageSize » peut être remplacée en définissant un paramètre de requête « pageSize » :
Nom | Lieu | Type | Obligatoire | Description |
pageSize | chaîne de requête | non | Définissez le nombre de pages souhaité pour les résultats. La valeur par défaut est 50. La valeur maximale est 1 000. | |
numéro de page | chaîne de requête | non | Définissez le numéro de page souhaité. La valeur par défaut est 1. Comme indiqué ci-dessus, il est recommandé d'utiliser l'en-tête de réponse « next » lors de la récupération de plusieurs pages. |
Synchronisation des relevés
Les clients souhaitant disposer de leur propre copie des relevés des capteurs ou des appareils peuvent utiliser le paramètre de requête `processedAfterDate` pour rester à jour avec SmartSense. Chaque fois que la dernière « page » de résultats est renvoyée à la suite d'une requête contenant une valeur `processedAfterDate`, un en-tête (`nextProcessedAfterDate`) est inclus dans la réponse, précisant la valeur `processedAfterDate` à utiliser pour la prochaine requête.
Exemple : la cliente Alice souhaite obtenir toutes les mesures des capteurs depuis le 1er mars 2021 (UTC), ainsi que toutes celles qui seront enregistrées après cette date. Alice interrogera SmartSense toutes les 15 minutes en utilisant le paramètre de requête `processedAfterDate`.
Pour commencer, Alice effectue la requête suivante :
GET /v1/data/asset/4146/sensorpoint/55689?processedAfterDate="2021-03-01T00:00:00.00Z"
La réponse du serveur peut contenir plusieurs « pages » de données. Chaque « page » (à l’exception de la dernière) comportera dans la réponse un en-tête contenant un lien vers la « page » suivante. La dernière « page » contiendra un en-tête nextProcessedAfterDate avec une valeur de date-heure. Alice enregistre cette valeur sous le nom X.
Après avoir récupéré toutes les « pages », Alice dispose désormais d’une copie de toutes les relevés des capteurs du compte jusqu’à la date-heure X incluse.
Au bout de 15 minutes, Alice interroge SmartSense pour obtenir les mesures et utilise une nouvelle valeur pour « processedAfterDate » : plus précisément, la valeur « nextProcessedAfterDate » X issue de la dernière « page » de la requête précédente. SmartSense répondra en fournissant toutes les nouvelles mesures reçues depuis la dernière requête d'Alice.
Alice répète ce processus toutes les 15 minutes pour rester à jour avec SmartSense.
Documentation interactive de l'API
Pour consulter la documentation détaillée sur les points de terminaison et pouvoir tester directement les appels API, rendez-vous sur notre documentation Swagger :
L'interface Swagger propose :
Spécifications complètes des terminaux
Schémas de requête et de réponse
Tests interactifs des API
Exemples en temps réel