L’objectif de cet article est de décrire comment requêter et utiliser les API disponibles au travers du portail web de Suadeo SDS®.
Schéma de fonctionnement des API Suadeo :
Pour utiliser une API Suadeo, il est nécessaire de récupérer un bearer token (ou jeton d’accès) via une première requête vers Suadeo.
Une fois ce jeton récupéré, il sera nécessaire pour l’appel des différentes API disponibles au travers des API Suadeo.
Note : la durée de validité du jeton est configurée par défaut à 1 jour. Ce paramètre s’administre dans les options d’administration du portail web :
Récupération et utilisation d’un bearer token
Illustration avec un outil tiers (Postman)
Via l’utilisation d’une méthode GET, renseigner l’URL du portail Web Suadeo et y ajouter ‘/token’ à la fin, ajouter quatre clés dans le Body du message, sous le format x-www-forma-urlencoded :
- username
- password
- grant_type
- authenticationname
Valoriser ensuite ces quatre clés avec les informations utilisateurs comme suit :
Une fois la configuration terminée cliquer sur SEND pour contacter le serveur Suadeo.
Si le paramétrage est correct le serveur fourni les informations suivantes :
Dans la réponse, apparait notamment le bearer token via la balise access_token ainsi que la date d’expiration de celui-ci.
Ensuite il est possible d’utiliser les API désirées, par exemple la liste des caches disponibles, en utilisant l’authentification de type bearer token, en utilisant le jeton dans le champ prévu à cet effet et en cliquant sur SEND :
Si le paramétrage est correct le serveur retourne les informations concernant les caches disponibles :
Illustration avec des commandes CURL
Il faut utiliser la même cinématique que pour le premier cas d’exemple.
A savoir premièrement récupérer un jeton d’accès :
Dans la capture la commande Curl est configurée avec les paramètres suivants :
- --request GET
- --header "Content-Type: application/x-www-form-urlencoded"
- --data"username=nvaillier&password=*******&grant_type=password&authenticationname=SUADEO.NET"
- http://192.168.1.224/SuadeoDesigner/token
Voici la ligne de commande complète :
curl --request GET --header "Content-Type: application/x-www-form-urlencoded" --data "username=nvaillier&password=*******&grant_type=password&authenticationname=SUADEO.NET" http://192.168.1.224/SuadeoDesigner/token
Une fois le token récupéré, il est possible de l’utiliser dans la requête d’appel de l’API.
Par exemple avec la récupération des informations de cache :
Il suffit donc de définir dans l’entête de commande le texte "Authorization: Bearer ${TOKEN}" en remplaçant la variable ${TOKEN} par le token récupéré précédemment.
Illustration avec le connecteur Suadeo JSON
Le connecteur JSON de Suadeo permet d’utiliser un bearer token pour s’authentifier à une API, comme c’est le cas avec les données d’usage Suadeo.
Tout d’abord sélectionner le connecteur JSON :
Ensuite dans la section connexion, laisser à NONE le schéma d’authentification, puis renseigner l’utilisateur, le mot de passe et le lien de la donnée d’usage (URI) :
Ensuite dans la section « OAuth », configurer :
- L’initialisation de l’OAuth (Initiate OAuth) en mode GETANDREFRESH ;
- Le type d’accord (OAuth Grant Type) en mode PASSWORD ;
- Les autres paramètres (OAuth Params) avec le domaine de l’utilisateur (exemple : authenticationname=SUADEO.NET) ;
- L’URL de requête (OAuth Request Token URL) pour récupérer le bearer token, ici http://UrlServeur/SuadeoDesigner/token ;
- L’URL d’accès au token (OAuth Access Token URL) pour accéder au bearer token, ici http://UrlServeur/SuadeoDesigner/token ;
- La version OAuth (OAuth Version) en 2.0.
Voici une illustration de ces configurations :
Liste des API disponibles dans la plateforme Suadeo
Licence, version et Supervision
Informations complètes concernant la licence : UrlServeur/SuadeoDesigner/api/licence
Supervision des actions : UrlServeur/SuadeoDesigner/api/supervision
Utilisateurs et droits
Liste des utilisateurs : UrlServeur/SuadeoDesigner/api/users
Droits et filtres des objets : UrlServeur/SuadeoDesigner/api/userrights
Annuaires et groupes
Liste des annuaires configurés : UrlServeur/SuadeoDesigner/api/directories
Liste des groupes d’un annuaire Active Directory : UrlServeur/SuadeoDesigner/api/directories/2/groups
Liste des utilisateurs d’un annuaire Active Directory : UrlServeur/SuadeoDesigner/api/directories/2/users
Suivi des caches
Liste des caches : UrlServeur/SuadeoDesigner/api/cache
Contient le nom, le type (donnée d’usage ou tableau de bord), la clé technique, le dernier chargement et le fichier associé
Pour forcer la mise à jour d’un cache via CURL, en complément du jeton d’accès il suffit d’utiliser une requête de type PUT, de préciser que le paramètre sera envoyé en JSON et enfin de fournir la clé technique du cache à mettre à jour :
Dans la capture précédente, la commande Curl est configurée avec les paramètres suivants :
- "Authorization: Bearer ${TOKEN}"
- --request PUT
- --header "Content-Type: application/json "
- --data """{'DesignObjectKey': 'zOfad6wE'}"""
- http://192.168.1.224/SuadeoDesigner/api/cache
Voici la commande :
curl -H "Authorization: Bearer ${token}" --request PUT --header "Content-Type: application/json" --data """{'DesignObjectKey': 'zOfad6wE'}""" http://192.168.1.224/SuadeoDesigner/api/cache
Connexions et données d’usage
Liste des connexions : UrlServeur/SuadeoDesigner/api/connections
Liste des données d’usage : UrlServeur/SuadeoDesigner/api/userdata
Scheduling
Liste des taches planifiées : UrlServeur/SuadeoDesigner/api/scheduler/getall
Serveur de reporting
Génération de report via une API en fournissant la clé technique du rapport ainsi que le format de sortie désirée.
Par exemple : le lien http://localhost/SuadeoDesigner/api/report/b6ZkZO6v/pdf permet de créer et télécharger directement le rapport « b6ZkZO6v » en format PDF :
La liste des formats d’export possible est la même que celle disponible directement en ouvrant la page de prévisualisation dudit rapport.