Die gesamte WebGUI von Bloonix ist in JavaScript entwickelt. Die Daten werden über die JSON-API von Bloonix mittels HTTP-POST Abfragen im JSON-Format ausgetauscht. Aus diesem Grund ist es möglich, alle Komponenten und Objekte übers Web zu verwalten.
Sie finden in diesem Dokument nicht alle Komponenten, die abgefragt werden können. Sollten Sie Fragen haben, so wenden Sie sich bitte an den Bloonix-Support.
Eine Abfrage über die JSON-API sieht beispielhaft wie folgt aus:
POST /login HTTP/1.1
Host: demo.bloonix.org
Content-Type: application/json
Content-Length: 35
{"username":"your-user-name","password":"your-secret-password"}Dabei sind ein paar Dinge zu beachten.
Die Antwort der JSON-API erfolgt, wie auch die Anfrage, im JSON-Format. Dabei hat die Antwort beispielhaft folgenden strukturellen Aufbau:
{
"server_time" : "1400501371624",
"who_am_i" : "demo.bloonix.org",
"status" : "ok",
"data" : {
"sid" : "sdfah7823fs83k3..."
},
"total" : 1,
"size" : 1,
"offset" : 0
}Folgende Werte können in der Antwort der JSON-API vorkommen:
| server_time | Die Uhrzeit des Servers, der die Daten ausgeliefert hat. |
|---|---|
| who_am_i | Der Hostname des Servers, der die Daten ausgeliefert hat. |
| status | Der Status der Anfrage. Diese kann entweder ok oder einen Fehlercode im Format err-NUMMER sein. |
| message | Sollte der Status einer Anfrage nicht ok sein, dann finden Sie hier eine Fehlermeldung. |
| failed | Sollten Sie Formulardaten zum Anlegen oder zur Modifizierung von Objekten senden und der Status der Antwort nicht ok sein, dann finden Sie hier wohlmöglich die Parameter, welche nicht valide Angaben enthalten. |
| data | Hier finden Sie die Daten zur Abfrage, wenn die Abfrage erfolgreich war und der Status ok ist. |
| total, size, offset | Diese Angaben sind immer dann wichtig, wenn Sie eine Liste von Daten abfragen. Wenn Sie zum Beispiel eine Liste von Hosts abfragen, erhalten Sie in der Antwort immer die Information, wieviele Daten (total) tatsächlich vorhanden sind; wieviele Elemente das Datenarrray enthält (size) und wo die Liste beginnt (offset). Diese Angaben sind auch mit OFFSET und LIMIT von SQL-Abrfagen vergleichbar. |
Eine Route ist schlichtweg der Pfad einer URL. Die gesamte JSON-API von Bloonix wird über Routen angesteuert. Wenn Sie zum Beispiel eine Liste aller Hosts abfragen möchten, so geschieht das über die Route /hosts. Wenn Sie nun die Daten eines bestimmten Hosts abfragen möchten, so wird an die Route noch die ID des Hosts angehängt, etwa so /hosts/1000.
Sie können das auch gerne einmal testen. Rufen Sie dazu in der URL-Leiste Ihres Browsers folgende URL auf:
https://demo.bloonix.org/hostsSie erhalten dann eine Liste aller Hosts im JSON-Format. Mit dem Parameter pretty können Sie der JSON-API mitteilen, dass die Ausgabe etwas leserlicher ausgegeben werden soll.
https://demo.bloonix.org/hosts?prettyDer Aufbau der Routen ist einheitlich strukturiert. Schauen wir uns doch beispielhaft folgende Route etwas genauer an:
/hosts/1000/services/400/updateMit dieser Route wird die Konfiguration eines Service geupdated und zwar der Service, der die ID 400 hat und zum Host mit der ID 1000 gehört. Schauen wir uns als nächstes die Teilpfade an und welche Ausgabe mit jedem Teilpfad zu erwarten ist:
| /hosts | Liste aller Hosts abfragen. |
|---|---|
| /hosts/1000 | Abfrage des Hosts mit der ID 1000. |
| /hosts/1000/services | Alle Services des Hosts 1000 abfragen. |
| /hosts/1000/services/400 | Abfrage des Service mit der ID 400. |
| /hosts/1000/services/400/update | Den Service mit der ID 400 updaten. |
Es folgt eine Übersicht über den allgemeinen Aufbau von Routen.
| /hosts | Liste aller Hosts abfragen. |
|---|---|
| /hosts/options | Abfrage der Parameter zum Erstellen eines Hosts. |
| /hosts/create | Einen neuen Host anlegen. |
| /hosts/1000 | Abfrage des Hosts mit der ID 1000. |
| /hosts/1000/options | Abfrage des Parameter zum Updaten des Hosts mit der ID 1000. |
| /hosts/1000/update | Den Host mit der ID 1000 updaten. |
| /hosts/1000/delete | Den Host mit der ID 1000 löschen. |
Route: /hosts
Route: /services
Route: /contactsListen werden immer in Teilen ausgeliefert. Das heißt, wenn es 10000 Hosts gibt, werden doch nur 50 Hosts in einer Antwort geliefert. Dies gilt zur Vorbeugung von zu hoher Speicherauslastung. Die Anzahl der Objekte pro Abfrage kann mit bestimmten POST-Parametern kontrolliert werden.
Beispiel einer Anfrage mit folgenden POST-Daten:
{
"limit" : 3,
"offset" : 0
}Antwort:
{
"status" : "ok",
"data" : [
{ "id" : 1 },
{ "id" : 2 },
{ "id" : 3 }
],
"total" : 10000,
"size" : 3,
"offset" : 0
}Die Antwort enthält wie angefordert nur drei Objeke. Um die nächsten drei Objekte abzufragen, muss eine weitere Abfrage gesendet werden. Der offset muss dabei erhöht werden:
{
"limit" : 3,
"offset" : 3
}Antwort:
{
"status" : "ok",
"data" : [
{ "id" : 4 },
{ "id" : 5 },
{ "id" : 6 }
],
"total" : 10000,
"size" : 3,
"offset" : 3
}Route: /login| Parameter | Datatype | Default | Required | Description |
|---|---|---|---|---|
| username | STRING (100) | yes | Username | |
| password | STRING (100) | yes | Password |
Antwort:
{
"status" : "ok",
"data" : {
"sid" : "a-very-long-session-id"
}
}Die Session-ID muss für jede weitere Abfrage verwendet werden. Setzen Sie die Session-ID daher mit Namen sid als Cookie im HTTP-Header jedes Abfrage.
Route: /logoutVerwenden Sie diese Route um sich auszuloggen.
Für alle Aktionen, bei denen Sie Objekte erstellen, ändern oder löschen möchten, ist ein sogenanntes CSRF-Token notwendig. Nur mit diesem Token dürfen Objekte modifiziert werden. Bevor Sie also ein Objekt modifizieren möchten, fordern Sie zunächst ein Token an. Die Route lautet hierzu wie folgt:
Route: /token/csrfDie Antwort enthält das Token:
{
"status" : "ok",
"data" : "37746962038f0a430c55d3c8d49eb5585b1dac1456ec393cfda9295a9578a5bf",
}Dieses Token müssen Sie mit dem Parameter token zu den POST-Daten hinzufügen.
Bitte beachten Sie, dass das Token nur für 30 Sekunden gültig ist. Sollten Sie versuchen, ein Objekt ohne ein Token zu modifizieren oder sollte die Gültigkeitsdauer eines Tokens abgelaufen sein, so erhalten Sie eine Fehlermeldung.
In diesem Dokument sind die einzelnen Parameter zum Erstellen oder zum Ändern von Objekten bewußt nicht dokumentiert. Stattdessen können Sie die Parameter über die JSON-API abfragen.
Angenommen, Sie möchten einen neuen Host erstellen und sich hierzu die Parameter anschauen. Unter folgender Route können Sie die Parameter mit den möglichen Optionen abrufen:
/hosts/optionsFalls Sie die Parameter eines Hosts abrufen möchten, der bereits angelegt ist, dann können Sie das über folgende Route:
/hosts/:host_id/optionsWobei Sie den Platzhalter :host_id einfach mit der ID des Hosts ersetzen.
Auf diese Weise können Sie für alle Objekte die Parameter abfragen, die zum Erstellen oder zum Ändern erforderlich sind.
Route: /administration/users
Route: /administration/users/options
Route: /administration/users/create
Route: /administration/users/:user_id
Route: /administration/users/:user_id/update
Route: /administration/users/:user_id/deleteRoute: /administration/groups
Route: /administration/groups/options
Route: /administration/groups/create
Route: /administration/groups/:group_id
Route: /administration/groups/:group_id/update
Route: /administration/groups/:group_id/delete
Route: /administration/groups/:group_id/hosts/list
Route: /administration/groups/:group_id/hosts/list-non
Route: /administration/groups/:group_id/hosts/add
Route: /administration/groups/:group_id/hosts/remove
Route: /administration/groups/:group_id/users/list
Route: /administration/groups/:group_id/users/list-non
Route: /administration/groups/:group_id/users/add
Route: /administration/groups/:group_id/users/removeRoute: /contacts
Route: /contacts/options
Route: /contacts/create
Route: /contacts/:contact_id
Route: /contacts/:contact_id/update
Route: /contacts/:contact_id/deleteRoute: /contactgroups
Route: /contactgroups/options
Route: /contactgroups/create
Route: /contactgroups/:contactgroup_id
Route: /contactgroups/:contactgroup_id/update
Route: /contactgroups/:contactgroup_id/delete
Route: /contactgroups/:contactgroup_id/contacts/in-group
Route: /contactgroups/:contactgroup_id/contacts/not-in-group
Route: /contactgroups/:contactgroup_id/contacts/add
Route: /contactgroups/:contactgroup_id/contacts/remove
Route: /contactgroups/:contactgroup_id/hosts/in-group
Route: /contactgroups/:contactgroup_id/hosts/not-in-group
Route: /contactgroups/:contactgroup_id/hosts/add
Route: /contactgroups/:contactgroup_id/hosts/remove
Route: /contactgroups/:contactgroup_id/services/in-group
Route: /contactgroups/:contactgroup_id/services/not-in-group
Route: /contactgroups/:contactgroup_id/services/add
Route: /contactgroups/:contactgroup_id/services/removeRoute: /hosts
Route: /hosts/options
Route: /hosts/create
Route: /hosts/:host_id
Route: /hosts/:host_id/update
Route: /hosts/:host_id/deleteRoute: /templates/hosts
Route: /templates/hosts/options
Route: /templates/hosts/create
Route: /templates/hosts/:template_id
Route: /templates/hosts/:template_id/update
Route: /templates/hosts/:template_id/deleteRoute: /timeperiods
Route: /timeperiods/options
Route: /timeperiods/create
Route: /timeperiods/:timperiod_id
Route: /timeperiods/:timperiod_id/update
Route: /timeperiods/:timperiod_id/delete
Route: /timeperiods/:timperiod_id/timeslices
Route: /timeperiods/:timperiod_id/timeslices/create
Route: /timeperiods/:timperiod_id/timeslices/:timeslice_id
Route: /timeperiods/:timperiod_id/timeslices/:timeslice_id/update
Route: /timeperiods/:timperiod_id/timeslices/:timeslice_id/deleteMit dieser Abfrage werden alle verfügbaren Chart-Daten eines Hosts gezeigt. Beispiel:
Route: /hosts/:host_id/charts{
"server_time" : "1400514110002",
"status" : "ok",
"who_am_i" : "demo.bloonix.org",
"data" : [
{
"plugin" : "Apache2.Statistics",
"options" : {
"chart-type" : "area",
"ylabel" : "workers",
"series" : [
{
"color" : "#ff7a0d",
"name" : "busyworkers"
},
{
"color" : "#005467",
"name" : "idleworker"
}
]
},
"host_id" : "60",
"chart_id" : "215",
"hostname" : "test1.bloonix.de",
"service_id" : "149",
"subkeys" : "",
"service_name" : "Apache2 process status",
"title" : "Apache - workers",
"ipaddr" : "127.0.0.1"
}
],
"total" : "10",
"size" : 1,
"offset" : 0
}Route: /hosts/charts/dataUm nun die Daten eines Charts abzurufen, ist folgende Abfrage notwendig:
{
"service_id" : "149",
"chart_id" : "215",
"preset" : "3h",
"avg" : "600p"
}Die einzelnen Parameter haben folgende Bedeutung:
| service_id | Die ID des Service, für welchen die Chart-Daten abgerufen werden sollen. |
|---|---|
| chart_id | Die ID des Charts. Jeder Service kann mehrere Charts haben. |
| preset | Der Zeitrahmen der Daten. Der Wert 3h bedeuted: die letzten 3 Stunden. Folgende Voreinstellungen sind möglich: 3h, 6h, 12h, 18h, 1d, 3d, 5d, 7d |
| avg | Mit diesem Parameter wird bestimmt, auf wieviele Datenpunkte die Daten runter berechnet werden sollen. Weitere Informationen finden Sie hierzu weiter unten. |
Der Parameter avg ist ein sehr nützlicher, aber auch wichtiger Parameter.
Angenommen, Sie möchten einen Chart mit einer Weite von 800 Pixel erzeugen. In diesem Chart könnte man 800 Datenpunkte unterbringen - ein Datenpunkt pro Pixel -, ohne das sich Datenpunkte überschreiben würden. Wenn man nun Chart-Daten aus den letzten 3 Tagen anfordert, dann kommen da ca. 4320 Datenpunkte zusammen (pro Minute ein Datenpunkt bei einem Check-Intervall von 60 Sekunden).
Um diese Datenpunkte nun optimal im Chart anzuzeigen, kann man über den Parameter avg mitteilen, wieviele Datenpunte maximal benötigt werden. Sprich, bei einer Weite von 800 Pixel würde man der Wert von avg auf 800p setzen.
Was nun passiert ist, dass aus 4320 Datenpunkten 800 Datenpunkte berechnet werden. Dabei werden jede 6 Datenpunkte (4320 / 800 aufgerundet) zusammengefasst und ein Durchschnitt berechnet. Bei der Zusammenfassung der Datenpunte wird der Zeitstempel des ersten Datenpunkts verwendet. Auf diese Weise wird die Datenmenge auf ca. 720 Datenpunkte gesenkt.
Die Struktur der Chart-Daten sieht wie folgt aus:
{
"server_time" : "1400516771622",
"status" : "ok",
"who_am_i" : "demo.bloonix.org",
"data" : {
"stats" : {
"sendrep" : [
[
1400506030000,
1
],
[
1400516747000,
250
]
]
},
"service" : {
"options" : {
"chart-type" : "area",
"ylabel" : "workers",
"series" : [
{
"color" : "#ff7a0d",
"name" : "busyworkers"
},
{
"color" : "#005467",
"name" : "idleworker"
}
]
},
"host_id" : "60",
"service_id" : "149",
"chart_id" : "215",
"hostname" : "test1.bloonix.de",
"service_name" : "Apache2 process status",
"category" : "System,Webserver,Apache2",
"ipaddr" : "127.0.0.1",
"plugin" : "Apache2.Statistics",
"description" : "Apache2 webserver statistics and process status.",
"title" : "Apache - workers"
}
}
}Die Chart-Daten selbst finden Sie im Baum unter data/stats/key. Der erste Wert ist immer der UNIX-Timestamp in Millisekunden und der zweite Wert ist der Wert des Statistik-Keys, welcher in diesem Beispiel sendrep ist.
Route: /plugin-stats/:pluginIm obigen Beispiel sind die Chart-Daten des Plugins Apache2.Statistics abgerufen worden. Wenn Sie nun eine detaillierte Beschreibung der einzelnen Statistik-Keys benötigen, so können Sie diese über folgende die Abfrage /plugin-stats/Apache2.Statistics erhalten.
Dies ist eine Kurzbeschreibung um eine Downtime für mehrere Hosts einzurichten und wieder zu löschen. Die Hosts werden mit dem Schlüssel host_id angegeben. Wichtig ist, dass Sie den Parameter flag setzen. Anhand dieses Flags können Downtimes eindeutig identifiziert und später wieder gelöscht werden.
curl -H 'Content-Type: application/json' https://demo.bloonix.org/login/ -d '
{
"username" : "username",
"password" : "password"
}'Die Session-ID aus sid muss für alle weiteren Requests verwendet werden.
Das Token aus data muss für den Request zum Anlegen der Downtimes verwendet werden. Das Token ist nur für 30 Sekunden gültig.
Zur Angabe der Dauer der Downtime gibt es drei Typen: preset, absolute und timeslice
bc. {
"type" : "preset",
"preset" : "2h"
}
{
"type" : "absolute",
"begin" : "2014-10-10 10:00:00",
"end" : "2014-10-11 10:00:00"
}{
"type" : "timeslice",
"timeslice" : "Monday - Sunday 00:00 - 01:00"
}Eine Beschreibung der einzelnen Zeitangaben finden Sie hier: Geplante Wartungsarbeiten einrichten
curl -H 'Content-Type: application/json' https://demo.bloonix.org/token/csrf -d '
{
"sid" : "sid"
}'
curl -H 'Content-Type: application/json' https://demo.bloonix.org/hosts/create-downtime/ -d '
{
"sid" : "sid",
"token" : "token",
"host_id" : [60, 62, 96],
"description" : "Test",
"timezone" : "Europe/Berlin",
"preset" : "2h",
"type" : "preset",
"flag" : "backup"
}'Das Token aus data muss für den Request zum Löschen der Downtimes verwendet werden. Das Token ist nur für 30 Sekunden gültig.
curl -H 'Content-Type: application/json' https://demo.bloonix.org/token/csrf -d '
{
"sid" : "sid"
}'
curl -H 'Content-Type: application/json' https://demo.bloonix.org/hosts/delete-downtime/ -d '
{
"sid" : "sid",
"token" : "token",
"host_id" : [60, 62, 96],
"flag" : "backup"
}'