Version 9.3.0 (10 aug 2021)

Documentation ServicePilot

API

L'API ServicePilot vous permet de lister facilement les ressources supervisées et permet aux applications externes et aux agents ServicePilot d'interagir avec les données de ServicePilot. L'API est basée sur REST avec des réponses au format JSON.

Gestion des ressources à l'aide de l'API REST

Pour pouvoir utiliser l'API REST, une clé API est nécessaire. Obtenez une clé API et utilisez-la lorsque vous appelez l'interface REST.

Obtention d'une clé d'API ServicePilot

Ouvrez la page Clés API pour gérer les clés API pour les agents ServicePilot et l'API REST. Il est suggéré d'utiliser une clé API dédiée à l'interface REST avec les privilèges Lire, Lire & Ecrire ou Lire, Ecrire & Supprimer en fonction de l'accès requis. Si cette clé est compromise, elle peut être supprimée sans affecter la collecte des données de l'agent ServicePilot.

1. En utilisant un compte avec des privilèges administrateurs, accédez à ServicePilot.
2. Ouvrez PARAMETRES > Installation Settings menu installation
3. Accédez à l'élément Clés API Keys menu item
4. Créez et notez une Clé API avec l'autorisation requise Key list

Obtenir une liste de ressources

Pour obtenir une liste de toutes les ressources, appelez la méthode REST "GET" avec une clé API disposant du droit Lire. La commande cURL ci-dessous est un exemple de requête utilisant la clé API 10000000-0000-0000-0000-000000000000 du serveur ServicePilot https://data.servicepilot.com.

curl -H "X-Api-Key: 10000000-0000-0000-0000-000000000000" -X GET "https://data.servicepilot.com/api/resources"

Obtenir des informations sur une ressource

Pour obtenir des informations sur une ressource particulière, appelez la méthode REST "GET" avec une clé API disposant du droit Lire. La commande cURL ci-dessous est un exemple de requête utilisant la clé API 10000000-0000-0000-0000-000000000000 du serveur ServicePilot https://data.servicepilot.com. Il obtiendra des informations sur la ressource internalstatistics.

curl -H "X-Api-Key: 10000000-0000-0000-0000-000000000000" -X GET "https://data.servicepilot.com/api/resources/internalstatistics"

Ajouter une ressource

Pour ajouter une nouvelle ressource, appelez la méthode REST "PUT" avec une clé API disposant du droit Ecrire. La commande cURL ci-dessous est un exemple de requête utilisant la clé API 10000000-0000-0000-0000-000000000000 du serveur ServicePilot https://data.servicepilot.com. Il créera une nouvelle ressource nommée ping 10.1.1.1 avec les paramètres présentés.

Tous les paramètres ne sont pas nécessaires. Selon le type de ressource, la liste des réponses sera différente.

curl -H "X-Api-Key: 10000000-0000-0000-0000-000000000000" -X PUT "https://data.servicepilot.com/api/resources/ping 10.1.1.1" -d "{'package': 'network-ping', 'view': 'main', 'agents': ['SP-TEST-15'], 'x': '150', 'y': '150', 'width': '30', 'height': '30', 'shape': 'image', 'picture': 'server.svg', 'backcolor': '#000000', 'borderwidth': '1', 'bordercolor': '#777777', 'borderstyle': 'solid', 'opacity': '100', 'backgroundcolorexist': 'true', 'html': '', 'policy': '', 'answers': {'ip_address_fqdn':'10.1.1.1','diffserv':''}}"

On remarque trois parties dans cette requête :

  • La première concerne le -H (le header de la requête cURL), cette dernière va prendre la clé d'API en paramètre afin de s'authentifier.

  • La seconde concerne une partie du -d (de 'package' jusqu'à 'answers'). Ici, nous allons spécifier plusieurs variables pour ServicePilot :

    Nom Obligatoire Exemple Explication
    Package Oui 'network-ping' Nom du package que l'on va utiliser pour créer la ressource
    view Oui 'main' Nom de la vue où la ressource va être créée
    agents Oui 'SP-TEST-15' Nom de l'agent ou des agents qui provisionneront la ressource, ne rien mettre si l'on veut utiliser l'agent par défaut. Si l'on doit renseigner plusieurs agents, la syntaxe est 'agents' : ['Nom_Agent_Custom', 'Nom Agent SNPM' ] "
    X / Y Oui 'x': '150', 'y': '150' Coordonnées où se placera la ressource dans la vue
    width / height Oui 'width': '30', 'height': '30' Taille de l'image ou forme de la ressource dans la vue
    shape Oui 'image' Forme dont on veut que la ressource prenne dans la vue. Nous avons le choix entre : 'image/circle/rectangle/text/line'
    picture Oui 'server.svg' Mettre une image dans la vue : il suffit de la renseigner ici
    backcolor Oui '#000000' Couleur de fond pour la ressource
    borderwidth Oui '#77777' Epaisseur des bordures
    bordercolor Oui '1' Couleur des bordures
    borderstyle Oui 'solid' Style des bordures de la ressource, nous avons le choix entre : 'solid/dotted/dashed'
    opacity Oui '100' Opacité de la ressource
  • La dernière concerne le reste du -d (de 'answers' jusqu'à la fin). Ici, nous allons spécifier plusieurs variables pour ServicePilot concernant la ressource. Ces variables vont varier en fonction du package choisit. Ici, c'est un exemple pour le package network-ping. Vous retrouverez ce tableau sur la page API de l'interface Web ServicePilot :

    Nom Obligatoire Exemple Explication
    ip_address_fqdn Oui '10.1.1.1' Adresse IP qui va être "pinguée"
    diffserv Non DSCP_B_Standard_DF Valeur utilisable seulement avec un agent .NET Core

Pour voir une liste des paramètres obligatoires et optionnels, allez à la page détails de l'API ServicePilot.

1. En utilisant un compte avec des privilèges administrateurs, accédez à ServicePilot.
2. Ouvrez PARAMETRES > Installation Settings menu installation
3. Accédez à l'onglet Advancées Advanced tab
4. Accédez à l'élément API API menu button
5. Réglez Méthode sur PUT et sélectionnez le Package souhaité.

Les paramètres seront présentés sous forme de liste ainsi que l'exemple de requête cURL situé à droite.

Supprimer une ressource

Pour supprimer une ressource particulière, appelez cette méthode REST avec une clé API disposant du droit Supprimer. La commande cURL ci-dessous est un exemple de requête utilisant la clé API 10000000-0000-0000-0000-000000000000 de https://data.servicepilot.com. Il supprimera la ressource internalstatistics.

curl -H "X-Api-Key: 10000000-0000-0000-0000-000000000000" -X DELETE "https://data.servicepilot.com/api/resources/internalstatistics"

Actualiser la configuration

Pour actualiser des changements faits sur des fichiers tels que le provisioning.conf ou la réalisation d'un package, l'API permet d'actualiser la configuration automatiquement sans avoir besoin de redémarrer ServicePilot. La commande cURL ci-dessous est un exemple de requête utilisant la clé API avec des droits d'écriture 10000000-0000-0000-0000-000000000000 du serveur ServicePilot https://data.servicepilot.com.

curl -H "X-Api-Key: 10000000-0000-0000-0000-000000000000" -d "{}" -X POST "https://data.servicepilot.com/api/service/reload"

Installation gratuite en quelques clics