V2 - ( READ ) /api/v2/cluster/{ID}

Sommaire

Objectifs

Méthode POST de type READ qui permet de récupérer des données de supervision d'un cluster et les informations de ses checks, comme sur l'Interface de Visualisation.

Paramètres

Le paramètre ID reçu dans l'URL identifie l'élément à rechercher.

Sa nature (nom ou UUID) est définie à l'aide du paramètre is_name (paramètre POST, détaillé ci-dessous).

Certains caractères sont interdits dans les URL, ils doivent être échappés (URL encodées) pour pouvoir être utilisés

caractère interdit : / ? # [ ] @ ! $ & ' ( ) * + , ; = % (espace)

remplacement %3A %2F %3F %23 %5B %5D %40 %21 %24 %26 %27 %28 %29 %2A %2B %2C %3B %3D %25 %20 ou +

Pour plus d'information https://developer.mozilla.org/fr/docs/Glossary/percent-encoding et rfc3986

Exemple: pour utiliser le nom ch@nged_name il faudra utiliser l'url http://broker-module-livedata:50100/api/v2/cluster/ch%40nged_name

Les 2 paramètres suivants sont également disponibles :

output_field ( Voir la page V2 - Les paramètres des API du broker-module-livedata, pour leur description complète )
is_name: précisant la nature de l'ID mentionné dans l'URL

Nom	Type	Défaut	Commentaire
is_name	Booléen	true	true, ID est considéré comme un nom d'hôte pour la récupération de l'hôte false, ID est considéré comme un UUID pour la récupération de l'hôte

Réponse

Codes de retour

Codes de retour	Explications
200	OK
400	Paramètre invalide
401	Accès nécessite une authentification ou un Token valide.
403	Authentification de l'utilisateur OK , mais droits non suffisants.
404	L'hôte demandé n'existe pas
405	L’élément correspondant à l'ID n'est pas un hôte
500	L'appel est valide, mais un problème d'exécution est survenu.

Retour du code 200

Les propriétés retournées doivent être choisies avec l'option output_field

Mais les propriétés suivantes seront au minimum automatiquement retournées :

nb_element
type
father_uuid
father_name
par checks :
- check_uuid
- check_name

Voir la page V2 - Les propriétés présentes dans le retour 200 des API du broker-module-livedata, pour la description complète de toutes les propriétés pouvant être renvoyée.

curl -s -S -H 'x-api-token: XYZ' \
http://broker-module-livedata:50100/api/v2/cluster/datacenter%20bdx

Exemple de sortie attendue :

http://localhost:50100//api/v2/host/095ac6b028d811ebb7a9080027774a8d

{
  "request_statistics": {
    "nb_elements_total": 9,
    "nb_clusters_total": 1,
    "nb_checks_total": 4,
    "nb_elements_filtered": 2,
    "nb_clusters_filtered": 1,
    "nb_checks_filtered": 1
  },
  "elements_found": [
    {
      "father_uuid": "d6921ee8ba1511eba36c0800277faebe",
      "father_name": "datacenter bdx",
      "type": "cluster"
    },
    {
      "check_name": "System Uptime",
      "check_uuid": "d6921ee8ba1511eba36c0800277faebe-e6daad4cba1511eb95980800277faebe",
      "father_uuid": "d6921ee8ba1511eba36c0800277faebe",
      "father_name": "datacenter bdx",
      "type": "check_cluster"
    }
  ]
}

Retour du code 400

Paramètre GET absent ( ID )

Le paramètre attendu est un nom

$ curl -s -S -H "x-api-token: XYZ" \
http://broker-module-livedata:50100/api/v2/cluster
ERROR 400: mandatory parameter [ name ] is missing

ERROR 400: mandatory parameter [ name ] is missing

Le paramètre attendu est un UUID

$ curl -s -S -H "x-api-token: XYZ" \
-d "is_name=false" \
http://broker-module-livedata:50100/api/v2/cluster
ERROR 400: mandatory parameter [ uuid ] is missing

ERROR 400: mandatory parameter [ uuid ] is missing

Paramètres POST incorrects

Paramètre inconnu

$ curl -s -S -H "x-api-token: XYZ" \
-d "parametre_inconnu=is_status_:true" \
http://broker-module-livedata:50100/api/v2/cluster/ID
ERROR 400: POST parameter [ parametre_inconnu ] is unknown

ERROR 400: POST parameter [ parametre_inconnu ] is unknown

Paramètre désactivé sur cette route

$ curl -s -S -H "x-api-token: XYZ" \
-d "output_format=checks_attached_to_father" \
http://broker-module-livedata:50100/api/v2/cluster/ID
ERROR 400: POST parameter [ output_format ] is not available for this route

ERROR 400: POST parameter [ output_format ] is not available for this route

Messages d'erreurs lors du paramétrage des propriétés présentes dans la sortie ( output_field )

( voir la page V2 - Les paramètres des API du broker-module-livedata )

Propriété de sortie inexistante

$ curl -s -S -H "x-api-token: XYZ" \
-d "output_field=is_status_" \
http://broker-module-livedata:50100/api/v2/cluster/ID
ERROR 400: output_field: invalid field name [ is_status_ ]

ERROR 400: output_field: invalid field name [ is_status_ ]

Messages d'erreurs liés au paramètre is_name

Valeur incorrecte

$ curl -s -S -H "x-api-token: XYZ" \
-d "is_name=cluster" \
http://broker-module-livedata:50100/api/v2/cluster/ID
ERROR 400: is_name: invalid value [cluster]

ERROR 400: is_name: invalid value [cluster]

Erreurs communes lors de l'envoi de la requête

Messages d'erreurs liés au protocole HTTPS

Le certificat SSL a été refusé

$ curl -s -S -H "x-api-token: XYZ" \
https://broker-module-livedata:50100/api/v2/inventory
curl: (60) SSL certificate problem: unable to get local issuer certificate
…

Cela peut se produire si le certificat du serveur est auto-signé.

Pour contourner la validité de l'émetteur du certificat, il faut utiliser l'option --insecure ( option courte : -k ).

curl --insecure -s -S -H "x-api-token: XYZ" \
https://broker-module-livedata:50100/api/v2/inventory

Avec curl v7.29.0 :

curl: (60) Peer's Certificate issuer is not recognized.

…

Avec curl v7.60 et supérieur :

curl: (60) SSL certificate problem: unable to get local issuer certificate

…

Requête HTTP sur un serveur en HTTPS

$ curl -s -S -H "x-api-token: XYZ" \
http://broker-module-livedata:50100/api/v2/inventory
The client IP_SERVEUR:PORT_CLIENT sent a plain HTTP request, 
but this server only speaks HTTPS on this port.

The client IP_SERVEUR:PORT_CLIENT sent a plain HTTP request, but this server only speaks HTTPS on this port.

Requête HTTPS sur un serveur en HTTP

$ curl -s -S -H "x-api-token: XYZ" \
https://broker-module-livedata:50100/api/v2/inventory
curl: (35) error:1408F10B:SSL routines:ssl3_get_record:wrong version number