Informations générales

• Les 2 modèles de services fonctionnement de la même manière. Global-Api-Value traite un retour numérique et le compare à des seuils, Global-Api-Status traite un retour texte et le compare à des valeurs attendues
• Les 2 modèles de services supportent les API au format REST JSON (qui est un standard du marché) et pas d’autres formats (Pas de SOAP, pas de REST XML, …)
• Ils supportent les protocoles d’authentification suivants : sans authentification, OAuth, basic-auth

Est nommé « EndPoint », la fin l’URL que l’on peut appeler via les méthodes GET ou en POST, avec des paramètres, qui retourne les résultats de la requête.

Exemple : avec une authentification sur l’URL http://myservice.com/v3/token et l’appel sur l’information à obtenir sur http://myservice.com/v3/jobs alors :

• URL = http://myservice.com/v3
• EndPoint d’authentification = /token
• EndPoint = /jobs

Principes de fonctionnement 

Le plugin propose des champs liés à l’authentification. Ces champs doivent être utilisés si l’API demande une authentification via un EndPoint différent du EndPoint final.

Cela est indispensable dans le cadre d’une authentification OAuth, ou pour toute API qui demande par exemple un token ou un visa ou autre élément similaire pour faire l’appel à l’API.

Il n’est pas utile dans le cadre d’une API sans authentification ou d’une API avec une basic-authentification sur chaque appel.

Authentification

Dans le cas d’une authentification, le valeur collectée (token, visa, …) lors de l’appel au EndPoint d’authentification est mis en cache avec une durée de validité mise en paramètre.

Exemple de mise en place avec le cas de cette API : https://helpcenter.veeam.com/docs/vbo365/rest/authorization.html?ver=50#RequestinAuthorization

Pour faire les appels au EndPoint Jobs, il faut fournir un token et non un login et mot de passe. Il faut donc d’abord collecter le token, nous allons donc utiliser le EndPoint d’authentification

La documentation indique

Nous allons donc remplir les champs comme cela

URL = https://abc.tech.local:4443/v5

Identifiant= xxxx

Mot de passe = yyyy

EndPoint d’authentification = /token

Méthode pour l’authentification = POST

Header d’authentification = Content-Type: application/x-www-form-urlencoded

Body d’authentication = grant_type=password&username=%login%&password=%password%

Champ d’identification : access_token

Validité du cache = 60

Explications sur les champs : 

• Body d’authentification : Nous remplaçons ici l’identifiant par %login% ceci permet de récuperer la valeur du champ Identifiant de ServiceNav et de bénéficier de la gestion des comptes de supervision. Idem pour le mot de passe remplacé par %password%. Attention on ne remplace pas le password de « grant_type=password » car c’est pour indiquer le type d’authentification à l’API (c’est un choix du developpeur de l’API)
• Champ d’identification : C’est le nom du champ qui retourne la valeur dont on va avoir besoin pour l’appel suivant. Il est ici directement à la racine de la réponse, c’est à dire au niveau 1 du Json donc on met juste son nom.

Appel à l’API

Ici dans l’exemple nous voulons lors d’un appel récupérer le dernier statut des jobs de sauvegarde (https://helpcenter.veeam.com/docs/vbo365/rest/get_jobs.html?ver=50)

Nous allons donc remplir les champs comme cela :

Champ EndPoint = /Jobs

Champ Méthode = GET

Champ Header = Authorization: Bearer %auth%     | ici %auth% est automatiquement remplacé par la valeur récuperer dans le champ « access_token » indiqué dans Champ d’identification dans l’appel précédent.

Comme le montre l’exemple l’API retourne un tableau avec pour chaque Job de sauvegarde de nombreuses informations, le modèle de service va donc regarder chaque élément du tableau et faire l’analyse selon les informations retournées pour chaque élément du tableau

Il convient donc de remplir les champs suivant comme ceci :

Champ Arborescence = <vide> . Ce champ sert à se positionner au début du tableau. Ici dans l’exemple l’API retourne directement le tableau, donc vide.

Champ Filtre = name. Il s’agit du champ sur lequel vont ensuite s’appliquer les listes blanches et noires, donc ici le nom du job de sauvegarde. 

Champ Valeurs = lastStatus. Il s’agit du champ pour lequel la valeur retournée va être prise en compte pour l’analyse (seuils ou texte)

Si l’API était au format suivant 

Champ Arborescence devrait être « tableau » → donc on se positionne au niveau de tableau qui devient notre nouveau référentiel d’analyse

Champ Filtre devrait être « Informations>name« . → On est au niveau tableau, pour avoir le nom du job on va dans Informations et on collecte name

Champ Valeur devrait être « Result>lastStatus« . → On est au niveau tableau, pour avoir le statut du job on va dans Result puis lastStatus

Utilisation avancée

Cas 1

Au niveau de Arborescence, filtre et valeur il est possible de remplacer le texte par la position dans le tableau.

Par exemple si le retour de l’API est le suivant

La documentation vous indique qu’il y a toujours les 3 dernières exécutions, et vous souhaitez avoir le dernier statut dans le service.

le champ Arborescence doit être <vide> → donc on se positionne au niveau le plus haut

le champ Filtre doit être « name ». → on va filtrer (liste blanche et noire) sur les noms des jobs

le champ Valeur doit être « lastresults>2>executionstatut ». → On va descendre dans lastresults, on arrive sur un tableau, on prends la 3e valeur, donc on indique 2 (un tableau débutant tout le temps à 0) et on prend ensuite la valeur associée à executionstatut.

Il est possible d’utiliser dans le champ Valeur « lastresults>-1>executionstatut » pour récuperer la dernière valeur du tableau (-2 pour l’avant dernière …)

Cas 2

Par exemple si le retour de l’API est le suivant

La documentation vous indique qu’il y a toujours les 3 dernières exécutions, et vous souhaitez avoir le dernier statut dans le service.

le champ Arborescence doit être <vide> → donc on se positionne au niveau le plus haut

le champ Filtre doit être « name ». → on va filtrer (liste blanche et noire) sur les noms des jobs

le champ Valeur doit être « lastresults>2>1 ». → On va descendre dans lastresults, on arrive sur un tableau, on prends la 3e valeur, donc on indique 2 (un tableau débutant tout le temps à 0), on arrive sur un autre tableau et on veut la seconde valeur.

Utilisation du masque de valeur

On interroge ici un équipement qui retourne la température pour chaque ventilateur, la réponse est au format suivant :

Le champ Arborescence doit être <vide> → donc on se positionne au niveau le plus haut

Le champ Filtre doit être « name ». → on va filtrer (liste blanche et noire) sur les noms des ventilateurs

Le champ Valeur doit être « Temperature ». 

Problème : les valeurs retournées sont des textes (et non des chiffres) avec la présence du C dans le retour. Nous souhaitons conserver uniquement la valeur numérique, le champ masque de valeur contient alors : [0-9]+