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 élément, ou la liste des éléments.
• PUT : Créer ou modifier un élément.
• POST : Modifier un élément.
• PATCH : Modifier un élément.
• DELETE : Supprimer un élément.

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

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

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 ln'importe quel outil de votre choix.

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

• 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 de l'écouteur : l'adresse est celle du Synchronizer, le port du listener REST fourni avec Shinken Entreprise Enterprise 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 Enterprise est listener-rest.
• Version du protocole : dans cette version de Shinken EntrepriseEnterprise, il s'agit de la v1 ; si le protocole évolue dans de futures versions, le numéro de version évoluera également, ce qui permettra à l'écouteur de conserver la compatibilité avec la version actuelle.

• Type d'éléments Shinken : le type d'élément Shinken traité par la requête.

  Info
  Actuellement, seuls les hôtes sont gérés.

• Header HTTP : La liste des en-têtes HTTP ; dans le cas de l'écouteur ; nous spécifions que nous envoyons du contenu JSON ;écouteur, il faut spécifier que le contenu sera du JSON.
• Données de l'élément : Les données décrivant l'é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'élément.
  • Elles sont définies à l'aide des nom noms de propriétés décrites dans la page Syntaxe des fichiers d'imports.
  • Des exemples de requêtes sont disponibles plus bas dans la page.

Sécuriser l'écouteur

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

• Une Authentification 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 de saisir un identifiant et un mot de passe, qui ne seront valables que pour cet écouteur.
• Validez ensuite Pour valider cette configuration en cliquant , il faudra cliquer 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 'admin-listener:mot_de_passe' -X PUT ....

Chiffrement des appels

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

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

Validez ensuite Pour valider cette configuration en cliquant , il faut cliquer 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:7761/shinken/listener-rest/v1/hosts" 

Description des actions

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

• non Non authentifiées.
• sans Sans le chiffrement ( SSL ).
• lancées 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é utilisée sera donc :

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

curl ... | python -m json.tool

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

Définition

Pour obtenir la liste des hôtes présents dans l'écouteur via l'appel /shinken/listener-rest/v1/hosts

, et la méthode GET :

• Voir la page V1 - ( GET ) /shinken/listener-rest/v1/hosts ( liste des hôtes présents dans l'écouteur

Les éléments présents dans l'écouteur sont ceux qui ont été crée 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.

Exemple

• ).

Créer un hôte

Pour créer un hôte via l'appel /shinken/listener-rest/v1/hosts, et la méthode PUT :

• Voir la page V1 - ( PUT ) /shinken/listener-rest/v1/hosts ( création d'hôte ).

Obtenir les données d'un hôte

Pour obtenir les informations définissant un hôte via l'appel

/shinken/listener-rest/v1/hosts/

SE_UUID

Créer un hôte

Définition

, et la méthode GET :

• Voir la page V1 - ( GET ) /shinken/listener-rest/v1/hosts/SE_UUID ( Obtenir les données d'un hôte ).

Modifier un hôte

Pour modifier un hôte via l'appel

/shinken/listener-rest/v1/hosts

/SE_UUID

, et l'

Exemple

une des méthodes POST ou PUT ou PATCH :

• Voir la page V1 - ( POST, PUT, PATCH ) /shinken/listener-rest/v1/hosts/SE_UUID ( modification de l'hôte ).

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

Pour supprimer un hôte via l'appel /

shinken/listener-rest/v1/hosts/

Obtenir les données d'un hôte

Définition

SE_UUID, et la méthode DELETE :

• Voir la page V1 - ( DELETE )

• /shinken/listener-rest/v1/hosts/SE_UUID

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

Exemple

• ( Supprimer un hôte créé par l'écouteur ).

Forcer la valeur des propriétés

Il est possible d’ajouter le suffixe [FORCE] ( sans espace ) à la clé d’import d'un élément Shinken afin de forcer la valeur associée ( voir la page Forcer la valeur des noms des éléments et des propriétés de type liste (comme la propriété des modèles hérités) ).

Exemple :

# Modifie l'hôte avec le SE_UUID core-hosts-a476af2aae9d4cdab85e0c439ee93bee en forçant l'adresse et les modèles qui seront appliqués à l'hôte

$ curl -H "Content-Type: application/json" "http://localhost:7761/shinken/listener-rest/v1/hosts/core-hosts-a0af58fafdfb4db5b0fe07c704caf937a476af2aae9d4cdab85e0c439ee93bee" -X GET |POST python -m json.tool
  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                                 Dload  Upload   Total   Spent    Left  Speed
100   361  100   361    0     0  51046      0 --:--:-- --:--:-- --:--:-- 60166
{
    "_SE_UUID": "core-hosts-a0af58fafdfb4db5b0fe07c704caf937",
    "_SYNC_KEYS": "core-hosts-a0af58fafdfb4db5b0fe07c704caf937,host_example_01",
    "_id": "a0af58fafdfb4db5b0fe07c704caf937",
    "address": "192.168.1.48",
    "host_d '{ "host_name": "host_example_01",
    "imported_fromaddress[FORCE]": "listener-rest envoy\u00e9 depuis l'adresse 127.0.0.1",
    "update_date": 1625570835.448688,
    "useuse[FORCE]": "linux, mongodb"
}

Modifier un hôte

Définition

Exemple

'

Lorsqu’une propriété est marquée avec [FORCE], elle est traitée de la manière suivante par le mélange des sources :

• La valeur est considérée comme prioritaire par rapport aux autres sources.
• Si une autre source importe le même objet avec une valeur différente, cette dernière est ignorée.
• En cas de conflit entre plusieurs valeurs forcées, la priorité de la source détermine la valeur conservée.

Ajouter [FORCE] à une clé d'import contenant une liste ( comme la propriété "members" servant à définir les membres d'un groupe d'utilisateurs ) aura pour effet de remplacer complètement la liste des autres sources par celle fournie avec l'option [FORCE].

Liste des clés d'import pouvant être forcées

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

Définition

Exemple

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

Forcer l'utilisation d'un modèle ( ou pour les propriétés qui acceptent plusieurs valeurs )

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.