View Source

Les routes suivantes sont mise à disposition par l'API. Chaque appel doit contenir dans ses paramètres le token d'identification décrit dans la section précédente.

Authentification

L'API du module broker-module-livedata est accessible à l'adresse suivante:

http://<ip-broker>:<port-module>/

Les appels effectués à l'API demandent l'utilisation d'un token d'identification. Ce token est spécifié dans le fichier de configuration du module (/etc/shinken/modules/broker-module-livedata.cfg).

Il est fortement recommandé de changer ce token.

Ce token doit être ajouté en paramètre à chaque requête sous peine de recevoir une erreur 401 de la part de l'API.

Par exemple:

http://192.168.1.59:50100/api/v1/host/408cd29ad37611e8810e0800277b7e16?token=ak5zv6t5s25r6g4

Chaque appel à l'API renvoie une réponse au format JSON.

Avec le module configuré en HTTP, une simple écoute du réseau permet de trouver le token. Il est fortement recommandé de passer en HTTPS afin d'éviter une interception du token.

GET /api/v1/all-monitored-elements

Cet appel permet de recevoir la liste des uuids de tous les hôtes et clusters ainsi que de leurs checks.

Réponse

Codes de retour

Codes de retour	Explications
200	OK
401	Permission refusée (Mauvais token)

Retour du code 200

hosts :
- host_uuid : text
- checks :
  - check_uuid : text
clusters :
- cluster_uuid : text
- checks :
  - check_uuid : text

Exemple

{
   "clusters":[
      {
         "cluster_uuid":"ac169cd1fb5744999eaadc5da595f88b",
         "checks":[
         ]
      },
      {
         "cluster_uuid":"0dcad2b1667642d28c933de70915331e",
         "checks":[
            "0dcad2b1667642d28c933de70915331e-905374c0f6ed11e78cd83cf862f4613a",
            "0dcad2b1667642d28c933de70915331e-714f6a1b90b318bbcfffb1a71d6258af",
            "0dcad2b1667642d28c933de70915331e-8537fb11f6ed11e7bf9f3cf862f4613a",
            "0dcad2b1667642d28c933de70915331e-8700ea097f3eb219b0e61d871936bfe4"
         ]
      }
   ],
   "hosts":[
      {
         "host_uuid":"ac169cd1fb5744999eaadc5da595f88b",
         "checks":[
         ]
      },
      {
         "host_uuid":"0dcad2b1667642d28c933de70915331e",
         "checks":[
            "0dcad2b1667642d28c933de70915331e-905374c0f6ed11e78cd83cf862f4613a",
            "0dcad2b1667642d28c933de70915331e-714f6a1b90b318bbcfffb1a71d6258af",
            "0dcad2b1667642d28c933de70915331e-8537fb11f6ed11e7bf9f3cf862f4613a",
            "0dcad2b1667642d28c933de70915331e-8700ea097f3eb219b0e61d871936bfe4"
         ]
      }
   ]
}

GET /api/v1/host

Cet appel permet de recevoir la liste des uuids et des noms de tous les hôtes ainsi que de leurs checks.

Paramètres

Nom du paramètre

Retour

Exemple

hostgroup_name ( optionnel )

Liste des hôtes ayant pour nom de groupe la valeur du paramètre hostgroup_name.

Plusieurs valeurs peuvent être spécifiées grâce au séparateur "^^".

Si plusieurs valeurs sont précisées, retourne les hôtes de chaque groupes.

hostgroup_name=gironde^^aveyron

Les valeurs de ce paramètre sont utilisées dans une URL.

Ainsi leur contenu doit être échappé (URL encodée) s'ils contiennent des caractères interdits dans une URL :

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 +

Exemple: hostgroup_name=mon (groupe) doit s'écrire hostgroup_name=mon+%28groupe%29

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

Réponse

Codes de retour

Codes de retour	Explications
200	OK
401	Permission refusée (Mauvais token)

Retour du code 200

hosts :
- host_uuid : text
- host_name : text
- checks :
  - check_uuid : text

Exemple

Appel simple à la route http://localhost:50100/api/v1/host

{
	"hosts":[
      {
         "host_uuid":"ac169cd1fb5744999eaadc5da595f88b",
		 "host_name":"Bordeaux",
         "checks":[
         ]
      },
      {
         "host_uuid":"0dcad2b1667642d28c933de70915331e",
		 "host_name":"Paris",
         "checks":[
            "0dcad2b1667642d28c933de70915331e-905374c0f6ed11e78cd83cf862f4613a",
            "0dcad2b1667642d28c933de70915331e-714f6a1b90b318bbcfffb1a71d6258af",
            "0dcad2b1667642d28c933de70915331e-8537fb11f6ed11e7bf9f3cf862f4613a",
            "0dcad2b1667642d28c933de70915331e-8700ea097f3eb219b0e61d871936bfe4"
         ]
      },
	  {
         "host_uuid":"0dcad2b1667642d28c933de70915331f",
		 "host_name":"Bruges",
         "checks":[
            "0dcad2b1667642d28c933de70915331f-905374c0f6ed11e78cd83cf862f4613b",
            "0dcad2b1667642d28c933de70915331f-714f6a1b90b318bbcfffb1a71d6258ag",
            "0dcad2b1667642d28c933de70915331f-8537fb11f6ed11e7bf9f3cf862f4613b",
            "0dcad2b1667642d28c933de70915331f-8700ea097f3eb219b0e61d871936bfe5"
         ]
      },
      {
         "host_uuid":"tv985cd1fb5744999eaadc5da595f88c",
		 "host_name":"Royan",
         "checks":[
         ]
      }
   ]
}

Appel à la route http://localhost:50100/api/v1/host avec un filtre sur le hostgroup_name

{
	"hosts":[
      {
         "host_uuid":"ac169cd1fb5744999eaadc5da595f88b",
		 "host_name":"Bordeaux",
         "checks":[
         ]
      },
      {
         "host_uuid":"0dcad2b1667642d28c933de70915331f",
		 "host_name":"Bruges",
         "checks":[
            "0dcad2b1667642d28c933de70915331f-905374c0f6ed11e78cd83cf862f4613b",
            "0dcad2b1667642d28c933de70915331f-714f6a1b90b318bbcfffb1a71d6258ag",
            "0dcad2b1667642d28c933de70915331f-8537fb11f6ed11e7bf9f3cf862f4613b",
            "0dcad2b1667642d28c933de70915331f-8700ea097f3eb219b0e61d871936bfe5"
         ]
      },
      {
         "host_uuid":"tv985cd1fb5744999eaadc5da595f88c",
		 "host_name":"Royan",
         "checks":[
         ]
      }
   ]
}

GET /api/v1/host/{uuid}

Cet appel permet de recevoir des informations sur un hôte.

Paramètres

Paramètre	Description
uuid	UUID de l'hôte

Réponse

Codes de retour

Codes de retour	Explications
200	OK
401	Permission refusée (Mauvais token)
404	Hôte introuvable

Retour du code 200

host_uuid : text
host_name : text
host_display_name : text
status : text
- OK
- WARNING
- CRITICAL
- UNKNOWN
- MISSING-DATA
- SHINKEN-INACTIVE
confirmated_state : text
- SOFT
- HARD
status_since : epoch (en secondes)
context : text
- NOTHING
- ACKNOWLEDGED
- PARTIAL-ACKNOWLEDGED
- INHERITED-ACKNOWLEDGED
- DOWNTIME
- PARTIAL-DOWNTIME
- INHERITED-DOWNTIME
- FLAPPING
- PARTIAL-FLAPPING
- DISABLED
business_impact : 0, 1, 2, 3, 4, 5
output : text
long_output : text
raw_perf_data : text, version texte de perf_data
perf_data : liste de métriques au format :
- value : number
- uom : Unit Of Mesure / Unité de mesure
- warning : valeur d'alerte
- critical : valeur d'alerte critique
- min : valeur minimale possible
- max : valeur maximale possible
notes_url : text
notes_multi_url : text

Exemple

{
 "status": "OK",
 "host_display_name": "localhost",
 "notes_multi_url": "UI_Configuration~=http://localhost:7766~=write~=NO~#~UI_Visualisation~=http://localhost:7767~=stats~=OPEN_IN_NEW_TAB" 
 "raw_perf_data": "rta=0.021000ms;1000.000000;3000.000000;0.000000 pl=0%;100;100;0",
 "perf_data": [{"name": "rta", "min": 0, "max": null, "value": 0.021, "warning": 1000, "critical": 3000, "uom": "ms"}, {"name": "pl", "min": 0, "max": 100, "value": 0, "warning": 100, "critical": 100, "uom": "%"}],
 "long_output": "",
 "notes_url": "http://localhost/",
 "host_name": "localhost",
 "context": "NOTHING",
 "status_since": 1540457802,
 "business_impact": 2,
 "output": "PING OK - Packet loss = 0%, RTA = 0.02 ms",
 "confirmated_state" : "HARD",
 "host_uuid": "408cd29ad37611e8810e0800277b7e16"
}

GET /api/v1/check-on-host/{uuid}

Cet appel permet de recevoir des informations sur un check attaché à un hôte.

Paramètres

Paramètre	Description
uuid	UUID du check, sachant qu'il correspond à {uuid_de_l'hôte}-{uuid_du_check}

Réponse

Codes de retour

Codes de retour	Explications
200	OK
401	Permission refusée (Mauvais token)
404	Check introuvable

Retour du code 200

check_uuid : text
check_name : text
check_display_name : text
status : text
- OK
- WARNING
- CRITICAL
- UNKNOWN
- MISSING-DATA
- SHINKEN-INACTIVE
status_since : epoch (en secondes)
context : text
- NOTHING
- ACKNOWLEDGED
- PARTIAL-ACKNOWLEDGED
- INHERITED-ACKNOWLEDGED
- DOWNTIME
- PARTIAL-DOWNTIME
- INHERITED-DOWNTIME
- FLAPPING
- PARTIAL-FLAPPING
- DISABLED
output : text
business_impact : 0, 1, 2, 3, 4, 5
long_output : text
host_uuid : text
host_name : text
host_display_name : text
raw_perf_data : text, version texte de perf_data
perf_data : liste de métriques au format :
- value : number
- uom : Unit Of Mesure / Unité de mesure
- warning : valeur d'alerte
- critical : valeur d'alerte critique
- min : valeur minimale possible
- max : valeur maximale possible

Exemple

{
 "status": "OK",
 "host_display_name": "localhost",
 "raw_perf_data": "livedata_nb_error_last_hour=0 livedata_average_response_time=0.000852610383715 livedata_nb_request_last_hour=84 livedata_error_percent=0.0",
 "perf_data": [{"name": "livedata_nb_error_last_hour", "min": null, "max": null, "value": 0, "warning": null, "critical": null, "uom": null}, {"name": "livedata_nb_request_last_hour", "min": null, "max": null, "value": 84, "warning": null, "critical": null, "uom": null},
 "check_name": "Broker Daemon Livedata - broker-master",
 "host_uuid": "408cd29ad37611e8810e0800277b7e16",
 "long_output": "",
 "host_name": "localhost",
 "context": "NOTHING",
 "output": "<span style=\"color:#2A9A3D;font-weight:bold;\">[OK]</span> The example works fine.<br/>",
 "business_impact": 2,
 "status_since": 1540457781.797493,
 "check_uuid": "022a505c849f840e110f2aba5e27597f",
 "check_display_name": "Broker Daemon Livedata - broker-master"
}

GET /api/v1/cluster

Cet appel permet de recevoir la liste des uuids de tous les clusters ainsi que de leurs checks.

Réponse

Codes de retour

Codes de retour	Explications
200	OK
401	Permission refusée (Mauvais token)

Retour du code 200

clusters :

cluster_uuid : text
checks :
- check_uuid : text

Exemple

{
	"clusters":[
      {
         "cluster_uuid":"ac169cd1fb5744999eaadc5da595f88b",
         "checks":[
         ]
      },
      {
         "cluster_uuid":"0dcad2b1667642d28c933de70915331e",
         "checks":[
            "0dcad2b1667642d28c933de70915331e-905374c0f6ed11e78cd83cf862f4613a",
            "0dcad2b1667642d28c933de70915331e-714f6a1b90b318bbcfffb1a71d6258af",
            "0dcad2b1667642d28c933de70915331e-8537fb11f6ed11e7bf9f3cf862f4613a",
            "0dcad2b1667642d28c933de70915331e-8700ea097f3eb219b0e61d871936bfe4"
         ]
      }
   ]
}

GET /api/v1/cluster/{uuid}

Cet appel permet de recevoir des informations sur un cluster.

Paramètres

Paramètre	Description
uuid	UUID du cluster

Réponse

Codes de retour

Codes de retour	Explications
200	OK
401	Permission refusée (Mauvais token)
404	Cluster introuvable

Retour du code 200

cluster_uuid : text
cluster_name : text
cluster_display_name : text
status : text
- OK
- WARNING
- CRITICAL
- UNKNOWN
- MISSING-DATA
- SHINKEN-INACTIVE
status_since : epoch (en secondes)
context : text
- NOTHING
- ACKNOWLEDGED
- PARTIAL-ACKNOWLEDGED
- INHERITED-ACKNOWLEDGED
- DOWNTIME
- PARTIAL-DOWNTIME
- INHERITED-DOWNTIME
- FLAPPING
- PARTIAL-FLAPPING
- DISABLED
business_impact : 0, 1, 2, 3, 4, 5
output : text
long_output : text
raw_perf_data : text, version texte de perf_data
perf_data : liste de métriques au format :
- value : number
- uom : Unit Of Mesure / Unité de mesure
- warning : valeur d'alerte
- critical : valeur d'alerte critique
- min : valeur minimale possible
- max : valeur maximale possible

Exemple

{
 "status": "OK",
 "cluster_display_name": "localhost",
 "raw_perf_data": "rta=0.021000ms;1000.000000;3000.000000;0.000000 pl=0%;100;100;0",
 "perf_data": [{"name": "rta", "min": 0, "max": null, "value": 0.021, "warning": 1000, "critical": 3000, "uom": "ms"}, {"name": "pl", "min": 0, "max": 100, "value": 0, "warning": 100, "critical": 100, "uom": "%"}],
 "long_output": "",
 "cluster_name": "localhost",
 "context": "NOTHING",
 "status_since": 1540457802,
 "business_impact": 2,
 "output": "PING OK - Packet loss = 0%, RTA = 0.02 ms",
 "cluster_uuid": "408gfhfr7611e8810e0800277b7e16"
}

GET /api/v1/check-on-cluster/UUID

Cet appel permet de recevoir des informations sur un check attaché à un cluster.

Paramètres

Paramètre	Description
uuid	UUID du check, sachant qu'il correspond à {uuid_du_cluster}-{uuid_du_check}

Réponse

Codes de retour

Codes de retour	Explications
200	OK
401	Permission refusée (Mauvais token)
404	Check introuvable

Retour du code 200

check_uuid : text
check_name : text
check_display_name : text
status : text
- OK
- WARNING
- CRITICAL
- UNKNOWN
- MISSING-DATA
- SHINKEN-INACTIVE
status_since : epoch (en secondes)
context : text
- NOTHING
- ACKNOWLEDGED
- PARTIAL-ACKNOWLEDGED
- INHERITED-ACKNOWLEDGED
- DOWNTIME
- PARTIAL-DOWNTIME
- INHERITED-DOWNTIME
- FLAPPING
- PARTIAL-FLAPPING
- DISABLED
output : text
business_impact : 0, 1, 2, 3, 4, 5
long_output : text
cluster_uuid : text
cluster_name : text
cluster_display_name : text
raw_perf_data : text, version texte de perf_data
perf_data : liste de métriques au format :
- value : number
- uom : Unit Of Mesure / Unité de mesure
- warning : valeur d'alerte
- critical : valeur d'alerte critique
- min : valeur minimale possible
- max : valeur maximale possible

Exemple

{
 "status": "OK",
 "cluster_display_name": "localhost",
 "cluster_uuid": "408gfhfr7611e8810e0800277b7e16",
 "check_name": "Broker Daemon Livedata - broker-master",
 "raw_perf_data": "livedata_nb_error_last_hour=0 livedata_average_response_time=0.000852610383715 livedata_nb_request_last_hour=84 livedata_error_percent=0.0",
 "perf_data": [{"name": "livedata_nb_error_last_hour", "min": null, "max": null, "value": 0, "warning": null, "critical": null, "uom": null}, {"name": "livedata_nb_request_last_hour", "min": null, "max": null, "value": 84, "warning": null, "critical": null, "uom": null},
 "long_output": "",
 "cluster_name": "localhost",
 "context": "NOTHING",
 "output": "<span style=\"color:#2A9A3D;font-weight:bold;\">[OK]</span> The example works fine.<br/>",
 "business_impact": 2,
 "status_since": 1540457781.797493,
 "check_uuid": "044a505c849f840e110f2aba5e27597f",
 "check_display_name": "Example cluster check"
}

Obtenir un UUID

Hôtes et Clusters

Pour récupérer l'UUID d'un hôte ou d'un cluster il suffit de se rendre dans sa page de configuration sur l'UI de Configuration, ou de le sélectionner dans l'UI de Visualisation. Il se trouve alors dans l'URL de la page comme sur les screens suivants:

Shinken Entreprise V02.08.00 > V1 - Les API du broker-module-livedata > image2018-10-25_14-9-13.png

Shinken Entreprise V02.08.00 > V1 - Les API du broker-module-livedata > image2018-10-25_14-12-7.png

Il est aussi possible de récupérer les uuid directement par le biais des requêtes apis : all-monitored-elements, host et cluster.

Checks attachés

Pour récupérer l'UUID d'un check attaché à un hôte ou à un cluster, il suffit de se rendre dans sa page de configuration sur l'UI de Configuration en y rajoutant l'UUID de l'hôte ou du cluster sur lequel il est attaché, suivi d'un tiret. Dans l'interface de Visualisation, il peut être trouvé directement dans l'URL en ouvrant le détail du check:

Shinken Entreprise V02.08.00 > V1 - Les API du broker-module-livedata > image2018-10-25_14-14-18.png

Macros Shinken

Des macros sont également disponibles sur Shinken pour utiliser l'UUID d'un hôte/cluster/check.

Macro	Description
$HOSTUUID$	Renvoie l'UUID de l'hôte ou du cluster
$SERVICEUUID$	Renvoie l'UUID du check

Exemple d'utilisation

Ces macros peuvent être utilisées par exemple dans les URL externes. Par exemple:

Shinken Entreprise V02.08.00 > V1 - Les API du broker-module-livedata > image2018-10-29_9-19-18.png

L'URL externe de cet hôte amène directement sur le volet Graphiques de l'hôte en question.