Page History

Introduction

L'API fournie par les écouteurs est de type REST ; elle fonctionne donc par l'intermédiaire des différentes méthodes du protocole HTTP:

• GET : Obtenir des informations sur un objetélément, ou la liste des objetséléments
• PUT : Créer ou modifier un objetélément
• POST : Modifier un élément
• PATCH : Modifier un objetélément
• DELETE : Supprimer un objetélément

L'identifiant des objets éléments est fournie fourni dans l'URL , et les données supplémentaires, quand cela est  est nécessaire, sont fournies dans le corps de la requête HTTP sous la forme d'un objet en format JSON.

Cette page décrit le format des URL ainsi que les différentes actions réalisables ainsi que le format des données.

Format des

URL

Les exemples utilisent la commande curl, disponible dans la plupart des distributions Linux ; cependant la requête HTTP peut être réalisée avec l'outil de votre choix.

Description générale d'une requête

Panel
Image Removed Image Added

Une requête est composée de plusieurs éléments :

• Utilisateur et mot de passe: utilisateur et de mot de passe si l’authentification à été activé
• Méthode HTTP : l'action que l'écouteur doit effectuer ; les actions disponibles sont décrites en détail dans les sections suivantes
• Adresse et port d'écoute de l'écouteur : l'adresse est celle du Synchronizer, le port du listener REST fourni avec Shinken Entreprise est le 7761
• Nom de l'écouteur : il s'agit du nom de l'écouteur tel que défini dans la propriété listener_name du fichier de définition de l'écouteur ; le listener fourni avec Shinken Entreprise est listener-rest
• Version du protocole : dans cette version de Shinken Entreprise, il s'agit de la v1 ; si le protocole évolue dans de futures versions, le numéro de version évoluera également, ce qui permettra a à l'écouteur de conserver la compatibilité avec la version actuelle
• Type d'objet éléments Shinken : le type d'objet élément Shinken traité par la requête. Actuellement, seuls les hôtes sont gérés.
• Header HTTP : La liste des en-têtes HTTP ; dans le cas de l'écouteurécouteur ; nous spécifions que nous envoyons du contenu JSON
• Données de l'objet élément : Les données décrivant l'objet élément à importer respectent le format JSON. Il s'agit d'un dictionnaire décrivant toutes les propriétés et données de l'objet ; élément. Elles sont définies de la même manière que dans les fichiers CFG et décrites sur cette page.

• ( voir page Syntaxe des fichiers d'imports ).

Sécuriser l'écouteur

Par défaut, l'écouteur transmet et reçoit les requêtes en clair ( non chiffrée ) et sans authentification. Vous pouvez sécuriser ces communications avec :

• Une Authentification par identifiant/mot de passe
• Un chiffrement grâce à SSL

Authentification

Il est possible d'authentifier les requêtes grâce à un couple identifiant /mot de passe, configurable uniquement sur la page de l'écouteur, dans l'onglet Configuration.

Il suffit de cocher la case Authentification et saisir un identifiant et un mot de passe, qui ne seront valables que pour cet écouteur.

Validez ensuite cette configuration en cliquant sur le bouton Envoyer. L'écouteur va se relancer avec cette nouvelle configuration ( ou lors de l'activation de la source si celle-ci est désactivée au moment de l'édition ).

Lors des appels à cet écouteur, il faudra spécifier cet identifiant et ce mot de passe pour que les requêtes s'exécutent.

Par exemple, avec curl, il faut utiliser l'option -u :

$ curl -u '

Chiffrement des appels

Afin de chiffrer les communications entre un écouteur et un client, il suffit d'activer l'option SSL ( Secure Socket Layer ).

Il suffit de cocher la case Utiliser SSL et saisir une clé SSL et un certificat SSL qui ne sera valable que pour cet écouteur.

Validez ensuite cette configuration en cliquant sur le bouton Envoyer. L'écouteur va se relancer avec cette nouvelle configuration ( ou lors de l'activation de la source si celle-ci est désactivée au moment de l'édition ).

Lors des appels à cet écouteur, il faudra penser à modifier le protocole HTTP en HTTPS.

$ curl -X PUT "https://synchronizer-server

Créer un hôte / cluster

Pour mener à bien cette action, vous pouvez utiliser les méthodes PUT ou POST  qui permettent d'envoyer à l'écouteur un nouvel objet

$  curl -u 'root:root' -X PUT http://localhost:7761/shinken/listener-rest/v1/hosts -d '{ "host_name": "hote-example", "use":"linux", "_SSH_USER":"root", "_SSH_KEY_PASSPHRASE":"root" }'
"core-hosts-22b48e7408a549f6895badada2fd3690"

Modifier un hôte / cluster

Description des actions

Dans ces différents exemples, nous allons utiliser des des requêtes :

• non authentifiées
• sans le chiffrement ( SSL )
• lancées depuis le serveur hébergeant le Synchronizer : localhost
• Utilisant le collecteur par défaut : listener-rest
• Utilisant le port par défaut : 7761

L'URL utilisé sera donc

http://localhost:7761/shinken/listener-rest/v1/hosts/

"

Pensez à adaptez cette URL en fonction de votre configuration

| python -m json.tool

Obtenir la liste des hôtes créés par l'écouteur

Définition

Pour réécrire totalement un objet existant, utilisez la méthode PUT en indiquant son identifiant dans l'URL. Les propriétés présentes dans l'objet actuel seront supprimées et l'hôte sera recréé avec le même identifiant que l'ancien. Cela correspond à une requête DELETE et une requête PUT avec un identifiant spécifique.

Obtenir les données d'un hôte / cluster

Cette URL, associée à la méthode GET, permet d'obtenir la liste de tous les éléments présents dans l'écouteur. Le format de retour est un JSON

Les éléments présents dans l'écouteur sont ceux qui ont été créés sur cet écouteur ( et qui n'ont pas été supprimés ).

Les propriétés et données Shinken affichées sont celles reçues par le collecteur.

Réponse

Exemple

$ curl -H "Content-Type: application/json" "

La méthode GET, lorsqu'elle est accompagnée d'un identifiant, l'objet est renvoyé au format JSON.

$ curl -u 'root:root' http://localhost:7761/shinken/listener-rest/v1/hosts/core-hosts-22b48e7408a549f6895badada2fd3690" -X GET | python -mjsonm json.tool
  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                                 Dload  Upload   Total   Spent    Left  Speed
100   381728  100   381728    0     0   72668100k      0 --:--:-- --:--:-- --:--:-- 76200
 101k
[
    {
        "_SE_UUID": "core-hosts-a0af58fafdfb4db5b0fe07c704caf937",
        "_SYNC_KEYS": "core-hosts-22b48e7408a549f6895badada2fd3690a0af58fafdfb4db5b0fe07c704caf937,host_example_01",
        "_id": "a0af58fafdfb4db5b0fe07c704caf937",
        "address": "192.168.1.48",
        "host_name": "_SSH_KEY_PASSPHRASEhost_example_01",
        "imported_from": "listener-rest envoy\u00e9 depuis l'adresse 127.0.0.1",
        "update_date": 1625570835.448688,
        "use": "root",
linux"
    },
    {
        "_SSHSE_USERUUID": "rootcore-hosts-3941f2a530194d149f18b82f84bcef51",
        "_SYNC_KEYS": "core-hosts-22b48e7408a549f6895badada2fd36903941f2a530194d149f18b82f84bcef51,hote-host_example_02",
        "_id": "3941f2a530194d149f18b82f84bcef51",
       "22b48e7408a549f6895badada2fd3690 "address": "192.168.1.54",
        "host_name": "hote-host_example_02",
        "imported_from": "listener-rest envoy\u00e9 depuis l'adresse 127.0.0.1",
        "update_date": 15278391801625570975.6257291763321,
        "use": "linuxwindows"
    }

Obtenir la liste des hôtes / clusters créés par l'écouteur

Créer un hôte

Définition

Cette route permet d'envoyer à l'écouteur un nouvel élément.

• Si le nom entré correspond à un hôte présent dans l'écouteur, dans la Zone de Travail, ou dans Staging, l'élément sera envoyé avec le même SE_UUID que l'hôte trouvé. 
• L'écouteur renvoie l'identifiant de l'élément créé sous la forme "core-hosts-<ID>" .

Réponse

Exemple

Obtenir les données d'un hôte

Définition

La méthode GET, lorsqu'elle est accompagnée d'un identifiant, l'élément est renvoyé au format JSON.

Réponse

Exemple

$ curl -H "Content-Type: application/json" "

La méthode GET, lorsque la requête ne contient pas d'identifiant, renvoie la liste de tous les objets créées par l'écouteur, au format JSON.

$ curl -u 'root:root' http://localhost:7761/shinken/listener-rest/v1/hosts/core-hosts-a0af58fafdfb4db5b0fe07c704caf937" -X GET | python -m json.tool
  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                                 Dload  Upload   Total   Spent    Left  Speed
100   785361  100   785361    0     0   104k51046      0 --:--:-- --:--:-- --:--:--  109k
[
    60166
{
        "_SE_UUID": "core-hosts-22b48e7408a549f6895badada2fd3690a0af58fafdfb4db5b0fe07c704caf937",
        "_SSHSYNC_KEY_PASSPHRASEKEYS": "root",
        "_SSH_USER": "root",
    core-hosts-a0af58fafdfb4db5b0fe07c704caf937,host_example_01",
    "_SYNC_KEYSid": "core-hosts-22b48e7408a549f6895badada2fd3690,hote-examplea0af58fafdfb4db5b0fe07c704caf937",
        "_id"address": "22b48e7408a549f6895badada2fd3690192.168.1.48",
        "host_name": "hote-host_example_01",
        "imported_from": "listener-rest envoy\u00e9 depuis l'adresse 127.0.0.1",
        "update_date": 15278391801625570835.6257291448688,
        "use": "linux"
    },
    {
        "_SE_UUID": "core-hosts-bafe4fae3fc447b992daa3f10ee260f2",
        "_SYNC_KEYS": "core-hosts-bafe4fae3fc447b992daa3f10ee260f2,hote-example-2",
        "_id": "bafe4fae3fc447b992daa3f10ee260f2",
        "address": "192.168.0.42",
        "host_name": "hote-example-2",
        "imported_from": "listener-rest envoy\u00e9 depuis l'adresse 127.0.0.1",
        "update_date": 1527839954.469449,
        "use": "shinken-full"
    }
]

Supprimer un hôte / cluster créé par l'écouteur

Modifier un hôte

Définition

Vous pouvez renseigner le SE_UUID d'un hôte de l'écouteur, de la Zone de Travail ou bien de Staging.

Réponse

Exemple

On a un hôte avec le SE_UUID "core-hosts-a0af58fafdfb4db5b0fe07c704caf937" et on exécute cette commande :

$ curl -H "Content-Type: application/json" "http://localhost:7761/shinken/listener-rest/v1/hosts/core-hosts-a0af58fafdfb4db5b0fe07c704caf937" -X POST -d '{"business_impact":"4"}'
done

Supprimer un hôte créé par l'écouteur

Définition

Utilisez l'action DELETE pour supprimer un objet élément créé par l'écouteur, en fournissant l'identifiant de l'objet élément à supprimer.

Réponse

Exemple

Questions fréquentes sur l'import d'éléments via l'API REST

Forcer l'utilisation d'un modèle

Lorsqu'on importe un hôte existant qui contient la propriété "use", la liste des modèle décrits dans la propriété "use" est ajoutée à la liste des modèles actuellement utilisée par l'hôte.

Comme lors de l'import d'hôtes via fichiers Cfg, il est possible de forcer l'utilisation d'une liste de modèles (remplacement et non ajout de modèles) en utilisant la propriété "use[FORCE]" au lieu de "use".

Plus de précisions sur l'utilisation du FORCE pour les modèles sont disponible disponibles dans la page de documentation suivante: ( voir la page Syntaxe des fichiers d'imports )