Documentation API
Avec smart operations, créez des applications personnalisées totalement adaptées à vos besoins. Travaillez avec tous les éléments basiques de smart operations (Points de gestion, Sessions, Alarmes,…) avec des moyens de consultation, d’édition, d’acquittement. Vous trouverez la liste complète des possibilités et des contraintes dans les différents chapitres du guide ci-dessous.
Autorisation
Pour consommer les API de smart operations, il est nécessaire de fournir un jeton d’accès obtenu suite à une étape d’authentification.
Obtenir un jeton d’accès
Pour obtenir un jeton d’accès, il est nécessaire d’utiliser l’API Authentification en fournissant les identifiants du compte utilisateur avec lequel vous souhaitez consommer les API.
Request body (application/json):
{
"strategy":"local",
"login":"monindentifiant",
"password":"monmotdepasse"
}
Tous les paramètres sont obligatoires. Voici les détails dans la table ci-dessous :
| Paramètre | Obligatoire | Description |
|---|---|---|
strategy |
Oui |
Permet d’indiquer la stratégie d’authentification. Pour s’authentifier à l’aide d’un login / password et obtenir un jeton d’accès la stratégie est "local". |
login |
Oui |
L’identifiant de l’utilisateur. |
password |
Oui |
Le mot de passe de l’utilisateur. |
{
"accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6ImFjY2VzcyI3.xxJ0c2VySWQiOiI1YzU3ZmE5NjRiYjNlMDAwMWZlMDk2NWYiLCJpYXQiOjE2Mjcy1TQ2NDksImV4cCI6MTYyNzM4MTA0OSIiYXVkIjoiaHR0cHM6Ly95b3VyZG9tYWluLmNvbSIsImlzcyI6ImZlYXRoZXJzIiwic3ViIjoiYW5vbnltb3VzIiwianRpIjoiZjU2YTgzYWMtYzcwZC00YTk3LThkNjgtNmQzNDAwMWE4Yzk5In0.ATctxHXX3dmijkYjg-qjh280gReAsetLFYZAb8FAmjU"
}
Utiliser le jeton d’accès
Toute requête vers l’API doit être faite suivant le protocole HTTPS avec le jeton d’accès qui doit être positionné dans l’entête avec la clé Authorization.
curl -X GET -H "Authorization:monaccesstoken" https://api.smart-operations.orange-business.com/v1/poms
Vous devriez obtenir une réponse avec un code HTTP 200.
| La durée de vie du jeton d’accès est temporaire et a une durée de validité de 24h. |
Après ce délai, les appels vers les API seront refusés. Il sera nécessaire de demander un nouveau jeton d’accès temporaire.
La réponse du serveur pour un jeton d’accès expiré sera la suivante :
{
"id": "22a45da8-59ce-4eb7-a694-77b28e336ba7",
"code": 401,
"message": "jwt expired",
"timestamp": 1659455897,
"hostname": "backend-588bbd7b84-8bvvf",
"version": "1.19.0_428c26b061e772764f6bb5366a3ed40cc9486602"
}
Il sera alors nécessaire de régénérer un nouveau jeton d’accès depuis l’étape Obtenir un jeton d’accès.
Méthodes API
Les API de smart operations vont vous permettre de travailler avec tous les éléments basiques tels que :
| Vous trouverez l’ensemble des méthodes avec la description des requêtes, réponses et erreurs possibles au format Swagger |
Authentification
Une méthode d’authentification est à votre disposition pour obtenir un jeton d’accès temporaire suivant les identifiants d’un utilisateur afin de consommer l’API (voir §Autorisation) ou obtenir les informations de l’utilisateur connecté à l’aide de son jeton d’accès temporaire :
-
Récupérer un jeton d’accès temporaire :
-
POST /v1/authentication :
-
choisir la stratégie "local" en fournissant les paramètres login/password, cette méthode vous permet d’obtenir un jeton d’accès temporaire de 24h
-
-
-
Récupérer les informations de l’utilisateur connecté à l’aide de son jeton d’accès temporaire :
-
POST /v1/authentication :
-
choisir la stratégie "jwt" en fournissant un jeton d’accès d’un utilisateur, cette méthode vous permet d’obtenir les informations de l’utilisateur connecté
-
-
Points de gestion
Un ensemble de méthodes sont à votre disposition afin de manipuler des points de gestion :
-
Récupérer la liste des points de gestion :
-
GET /v1/poms : Cette méthode vous permet de récupérer la liste des points de gestion répondant à certains critères de filtre avec la possibilité de trier et paginer le résultat.
-
-
Récupérer les informations d’un point de gestion :
-
GET /v1/poms/
{`pomId`}: Cette méthode vous permet de récupérer l’ensemble des informations d’un point de gestion à partir de son identifiant technique.
-
-
Editer les informations d’un point de gestion :
-
PATCH /v1/poms/
{`pomId`}: Cette méthode vous permet de mettre à jour les informations d’un point de gestion à partir de son identifiant technique telles que le nom, les tags, la localisation, le fuseau horaire, le commentaire, …
-
-
Valeurs historisées du point de gestion :
-
GET /v1/poms/
{`pomId`}/values : Cette méthode vous permet de récupérer l’historique des données d’un point de gestion à partir de son identifiant technique sur une période de temps donnée avec la possibilité de paginer le résultat.
-
-
Récupérer la liste des tags associés aux points de gestion :
-
GET /v1/poms/tags : Cette méthode vous permet de récupérer l’ensemble des tags associés aux points de gestion avec le nombre d’occurences pour chaque tag.
-
-
Récupérer les statistiques sur les points de gestion :
-
GET /v1/poms/stats : Cette méthode vous permet de récupérer le nombre de points de gestion par état de criticité.
-
Sessions (module optionnel)
| Cette fonctionnalité est optionnelle et n’est pas activée par défaut sur le compte client. Pour pouvoir utiliser cette fonctionnalité, il est nécessaire d’en faire la demande. Veuillez contacter le support (cf. rubrique ‘Contact’). |
Un ensemble de méthodes sont à votre disposition afin de manipuler des sessions :
-
Récupérer la liste des sessions :
-
GET /v1/sessions : Cette méthode vous permet de récupérer la liste des sessions répondant à certains critères de filtre avec la possibilité de trier et paginer le résultat.
-
-
Récupérer les informations d’une session :
-
GET /v1/sessions/
{`sessionId`}: Cette méthode vous permet de récupérer l’ensemble des informations d’une session à partir de son identifiant technique.
-
-
Créer une session :
-
POST /v1/sessions : Cette méthode vous permet de créer une session.
-
|
Pour créer une session, un ensemble de règles doivent être respectées :
|
-
Editer une session :
-
PUT /v1/sessions/
{`sessionId`}: Cette méthode vous permet de mettre à jour les informations d’une session.
-
|
L’édition d’une session doit respecter les règles suivantes :
|
| La date de fin d’une session est facultative. La session durera tant qu’une date de fin n’aura as été définie ou tant que la date de fin n’aura pas été atteinte (la session se terminera automatiquement à la date de fin) ou que l’action Terminer une session n’aura pas été réalisée. |
-
Terminer une session :
-
PUT /v1/sessions/
{`sessionId`}/terminate : Cette méthode vous permet de terminer la session manuellement.
-
| En utilisant cette méthode pour terminer une session, la date de fin de la session sera valorisée à la date de réception de la requête par le serveur. |
-
Supprimer une session :
-
DELETE /v1/sessions/
{`sessionId`}: Cette méthode permet de supprimer une session.
-
| La suppression d’une session est irréversible. Vous n’aurez plus accès à cette session dans la liste des sessions historisées. |
Alarmes
Un ensemble de méthodes sont à votre disposition afin de manipuler les alarmes :
-
Récupérer la liste des alarmes :
-
GET /v1/alarms : Cette méthode vous permet de récupérer la liste des alarmes répondant à certains critères de filtre avec la possibilité de trier et paginer le résultat.
-
-
Récupérer le nombre d’alarmes en cours :
-
GET /v1/alarms/count : Cette méthode vous permet de récupérer le nombre d’alarmes en cours (non acquittées).
-
-
Acquitter une alarme :
-
PATCH /v1/alarms/{`alarmId`} : Cette méthode vous permet d’acquitter une alarme en cours à partir de son identifiant technique.
-
-
Acquitter toutes les alarmes d’un tenant :
-
PATCH /v1/alarms/tenant/{`tenantId`}/ack : Cette méthode vous permet d’acquitter toutes les alarmes en cours d’un tenant à partir de son identifiant.
-