API externe

API version 2.0 (actuelle)

Installation

A partir de la version NG 776, l'API PFMS 2.0 est installée par défaut. Si Ubuntu est le système d'exploitation du serveur PFMS, la mise à jour vers la version 777 doit être exécutée et installée avec l'utilisateur root ou équivalent: 

a2enmod rewrite
service apache2 restart

Il est nécessaire de vérifier que la configuration par défaut du serveur web Apache lors de l'installation de PFMS est correctement définie.

Sécurité

Par défaut, lors de l'installation de Pandora FMS, la liste des adresses IP autorisées est restreinte aux seuls appels locaux (à partir de localhost, 127.0.0.1). Vous devez ajouter la ou les adresses IP qui fonctionneront avec le PFMS API 2.0 dans la Configuration générale de la console Web.

Il convient de veiller à utiliser des connexions SSL afin d'éviter que des informations sensibles ne soient vues par des tiers sur le réseau. En cas d'utilisation de HTTP au lieu de HTTPS, certains navigateurs web peuvent refuser de se connecter au serveur PFMS API 2.0.

Authentification de l'utilisateur

Les tokens d'authentification de chaque utilisateur doivent être générés par la console Web, menu Management → Profile → Token management → Create token où l'utilisateur qui utilisera le token, une description et une date d'expiration (recommandé) seront sélectionnés. Lorsque l'on clique sur le bouton Create, la valeur du token s'affiche une fois, elle doit être copiée et sauvegardée dans un endroit sûr.

Accès via l'interface web

Une fois le token généré par la console web, utilisez le lien suivant dans la barre d'adresse de votre navigateur web: 

https://< IP address or FQDN >/pandora_console/api/

Cliquez sur le bouton Autoriser et entrez le jeton précédemment généré dans la fenêtre pop-up.

En cliquant à nouveau sur le bouton Autoriser aucune authentification ne sera effectuée, en fait le formulaire accepte n'importe quelle valeur, valide ou non. Chaque fois qu'une requête API est effectuée, la valeur placée ici sera envoyée et la réponse du serveur doit toujours être vérifiée.

En définissant un token, les icônes de cadenas changeront et vous pourrez commencer à faire des demandes d'API. Ces demandes sont classées par catégories:

  • POST: Pour créer de nouveaux éléments.
  • GET: Pour afficher les éléments enregistrés.
  • PUT: Pour modifier les éléments enregistrés.
  • DELETE: Pour supprimer les éléments enregistrés.

Des regroupements logiques d'actions sont ensuite proposés:

Accès à la ligne de commande

À cette fin, il est recommandé d'utiliser curl, qui est présent dans la plupart des systèmes d'exploitation actuels: 

curl -X '< action >' \
  'http://< IP address or FQDN >/pandora_console/api/v2/< command >/< parameter >' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer < your token >'
  -d '< JSON parameters >'

Donde:

  • < action > L'action à entreprendre:
  • POST: Pour créer de nouveaux éléments.
  • GET: Pour afficher les éléments enregistrés.
  • PUT: Pour modifier les éléments enregistrés.
  • DELETE: Pour supprimer les éléments enregistrés.
  • < command > La commande API elle-même, telle que ping, etc.
  • < parameter > Un identifiant unique ou des paramètres de pagination, le cas échéant.
  • < your token > Le token généré pour chaque utilisateur.
  • < JSON parameters > Tous les autres paramètres si nécessaire.

L'interface web web interface permet de générer et de copier les codes nécessaires, avec leurs paramètres et leurs champs obligatoires, pour toutes les commandes de ce PFMS API 2.0. Voir schemas pour plus de détails.

Schéma de documentation

https://< IP address or FQDN >/pandora_console/api/v2/swagger.json

En accédant au lien ci-dessus, vous obtiendrez toutes les fonctionnalités de la documentation de manière automatisée, ce qui vous permettra de générer de la documentation avec n'importe quel logiciel compatible JSON.

En outre, dans l'interface web de web, chaque commande a un lien vers son schema particulier:

Dans ce système, les paramètres obligatoires ont la propriété suivante nullable: false.

Comando ping API PFMS

La façon la plus simple de vérifier la connectivité et l'authentification avec l'API PFMS est d'utiliser la commande ping: 

curl -m 3 -X 'GET' \
  'http://192.168.7.117/pandora_console/api/v2/ping' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer < your token >' && echo

Dans l'interface web, allez dans la section Authentication (API Endpoints of authentication) et cliquez sur le bouton Try out (si l'icône du cadenas est ouverte, cliquez et entrez le jeton d'utilisateur généré), puis cliquez sur le bouton Execute. La connexion sera réussie si le code {“valid” : true } est affiché dans le Response body:

Retourner à l'index de la documentation du Pandora FMS