1. Einleitung
Ab der Version VERSION[2.0] gibt es in Checkmk eine neue Anwendungsprogrammierschnittstelle: die Checkmk REST-API. Mit dieser API können Sie die Aufgaben, die Sie sonst in Checkmk über die GUI erledigen, per Kommando oder Skript mit HTTP-Anfragen an den Checkmk-Server übermitteln und ausführen lassen.
Eine API per HTTP nutzen? Das kommt Ihnen vielleicht bekannt vor. Denn Checkmk bietet schon seit längerem eine API, die sogenannte Web-API, mit der Sie viele Administrationsaufgaben erledigen können. Warum gibt es also jetzt eine neue API? Anders als der Name REST-API vielleicht vermuten lässt, geht es nicht darum, mit der neuen API den Rest der in der Web-API fehlenden Funktionen zu liefern. Ganz im Gegenteil soll die REST-API die komplette Funktionalität abdecken, die Checkmk über die GUI und über Kommandoschnittstelle bietet und damit die Web-API komplett ersetzen.
REST steht für *RE*presentational *S*tate *T*ransfer und beschreibt eine Architektur für den Austausch von Daten auf verteilten Systemen — insbesondere für Web-Dienste. Eine API, die gemäß der REST-Architektur implementiert ist, folgt bestimmten Prinzipien, z.B. dem Client-Server-Modell, der zustandslosen Kommunikation und einer einheitlichen Schnittstelle. In der Praxis erfolgt die Umsetzung bevorzugt über das HTTP-Protokoll, wobei die Ressourcen per Uniform Resource Identifier (URI) angesprochen werden und auf diese mit HTTP-Methoden (GET, POST, PUT, DELETE) zugegriffen wird.
Soviel zu den REST-Prinzipien. Ihre Vorteile zeigen sich in den konkreten Features, die Ihnen die Checkmk REST-API bietet:
| Feature | Beschreibung |
|---|---|
Protokoll | Das Hypertext Transfer Protocol (HTTP/1.1) wird als Transportsystem für die Kommunikation genutzt. |
Kodierung | Als Datenformat wird die JavaScript Object Notation (JSON) verwendet. Die Nutzdaten (payload) der Antworten werden mit JSON serialisiert und in UTF-8 kodiert. Datums- und Zeitangaben sind im ISO-8601-Format mit gültigen Zeitzoneninformationen kodiert. |
Sprache | Englisch ist die Sprache für Labels, Identifiers und die API-Dokumentation. |
Authentifizierung | Der Zugriff auf die API wird einem Client nur dann gestattet, wenn er die Berechtigung mittels HTTP-Authentifizierung (z.B. "Basic" oder "Bearer") nachgewiesen hat. |
Versionierung | Die API ist versioniert und nutzt dabei eine dreistufige Nummerierung nach dem Semantic Versioning 2.x Standard. Details finden Sie im Kapitel zur Versionierung weiter unten. |
Dokumentation | Die API wird in einem maschinenlesbaren Schema und einem menschenlesbaren Format in englischer Sprache dokumentiert, mit allen Ressourcen, ihren Eingabe- und Ausgabeparametern und den zugehörigen Wertebereichen. Die API ist mit der OpenAPI Spezifikation (OAS) 3.x erstellt, einem API-Beschreibungsformat speziell für REST-APIs. Das mit dieser Spezifikation erstellte API-Dokument wird für den Benutzer mit ReDoc angezeigt, einem responsiven Web-Design für OpenAPI-Dokumente. |
Beispiel-Code | Um die Verwendung zu demonstrieren, gibt es zu jeder Anfrage Beispiel-Code für verschiedene Anwendungen. |
Fehleranzeige | Die API sendet im Fehlerfall numerische HTTP-Status-Codes und eine Diagnosemeldung des Problems, die bei der Suche nach möglichen Ursachen für fehlerhafte Anfragen hilft. |
REST-API Klassifizierung | Die API erfüllt alle vier Ebenen (0 bis 3) des Richardson Maturity Model (RMM), mit dem beurteilt werden kann, wieviel REST in einer API steckt. In Ebene 1 wird die Einführung von Ressourcen gefordert, damit über die API statt zu einem globalen zu individuellen Endpunkten kommuniziert werden kann. Ebene 2 wird erfüllt, wenn für die Anfragen HTTP-Methoden verwendet werden. Auf der (höchsten) Ebene 3 dokumentiert sich die API quasi selbst, indem der Server mit der Antwort auf eine Anfrage die nächsten möglichen Aktionen und die dabei anzusprechenden Ressourcen mitteilt, und es dem Client so ermöglicht, die verfügbare Funktionalität selbst zu entdecken. Diese Bereitstellung von Zusatzinformationen wird auch „Hypermedia as the Engine of Application State“ (HATEOAS) genannt. |
Neben diesen generellen Komfortfunktionen bietet die Checkmk REST-API bereits jetzt Zugriff zu mehr Bereichen in Checkmk als die Web-API, z.B. zu Wartungszeiten, Zeitperioden, Quittierung von Problemen, Agenten und der Business-Intelligence (BI). Für viele Bereiche, die beide APIs unterstützen, haben Sie per REST-API zudem mehr und spezifischere Möglichkeiten.
Bei allem REST-Enthusiasmus verschweigen wir aber nicht, dass die REST-API zurzeit noch nicht all das drauf hat, was die Web-API kann (z.B. Regelsätze). Solange das so ist, finden Sie im letzten Kapitel eine Gegenüberstellung der Funktionalität von REST-API und Web-API.
2. Die API-Dokumentation
2.1. Versionierung
Einer der Vorteile der REST-API ist, dass Software und Dokumentation aus der gleichen Quelle stammen: dem OpenAPI-Dokument. Daher passt die API-Dokumentation stets zur Software und beschreibt genau das, was die API kann. Daher ist es auch nicht nötig, den Referenzteil der verfügbaren Ressourcen, Methoden, Parameter etc. im Checkmk-Handbuch zu beschreiben: stattdessen finden Sie die API-Dokumentation außerhalb dieses Handbuchs, direkt in ihrer Checkmk-Instanz.
Die API mit ihrer Dokumentation ist versioniert und nutzt dabei eine dreistufige Nummerierung im Format X.Y.Z, wobei X für ein Main Release steht, Y für ein Minor Release und Z für einen Patch. Ein neues Minor Release enthält neue, rückwärtskompatible Funktionen. Ein neues Main Release kann dagegen Änderungen enthalten, die die API inkompatibel mit dem vorherigen Main Release machen (sogenannte breaking changes). Die Versionsnummer des Main Release ist Bestandteil der URL, mit dem eine Anfrage an den Server gesendet wird.
Wichtig: Beachten Sie, dass die REST-API einer anderen Versionierung folgt als die Checkmk-Software. Da ein neues Main Release der API dann notwendig ist, wenn es inkompatible API-Änderungen gibt, passt das in der Regel nicht zum Release-Zyklus der Checkmk-Software.
Trotzdem ist die Zuordnung der Versionen von API-Dokumentation und Checkmk-Software sehr einfach, wie Sie im nächsten Kapitel erfahren.
2.2. Zugriff
Die REST-API-Dokumentation steht im HTML-Format zur Ansicht im Web-Browser bereit. Sie kann über die Checkmk GUI geöffnet und alternativ/zusätzlich über die Checkmk-Website heruntergeladen werden.
Wenn Sie die API-Dokumentation über die Checkmk GUI öffnen, wird Ihnen automatisch die passende API-Dokumentation angezeigt. Im Download-Bereich finden Sie beim Eintrag der Checkmk-Softwareversion die zugehörige API-Dokumentation .
In der Checkmk GUI öffnen Sie die API-Dokumentation über die Navigationsleiste im Menü Help > Internal links > REST API documentation. Die API-Dokumentation wird in einem neuen Browser-Fenster (bzw. Browser-Tab) angezeigt. Wir gehen darauf im nächsten Kapitel genauer ein.
Hinweis: Sicher ist Ihnen aufgefallen, das es im Help-Menü noch einen weiteren REST-API-Eintrag gibt, der REST API interactive GUI heißt. Mit diesem Eintrag öffnen Sie eine weitere Sicht auf die REST-API. GUI heißt der Eintrag, weil Ihnen nicht nur die REST-API-Funktionen angezeigt werden, sondern weil Sie aus dem Browser heraus direkt mit der API interagieren können, indem Sie z.B. Anfragen an den Server senden. Wir stellen die REST-API GUI als Alternative zur Ausführung per Skript im Kapitel zur REST-API GUI später vor.
2.3. Struktur und Inhalt
Die API-Dokumentation nutzt ein responsives Web-Design mit 3 Bereichen:
Der linke Navigationsbereich dient der Orientierung, der Suche und dem schnellen Sprung zur genauen Beschreibung der Einträge im mittleren Bereich. Das Inhaltsverzeichnis enthält für jeden API-Endpunkt einen Eintrag. Ein Endpunkt bezeichnet per URL die Ressource, die die API zur Verfügung stellt (z.B. für die Sammlung der Hosts), zusammen mit der Methode, um auf die Ressource zuzugreifen (z.B. GET zur Anzeige eines Hosts). Die Endpunkte sind in mehrere Ordner organisiert.
Der mittlere Inhaltsbereich enthält die harten Fakten der Dokumentation: alle Informationen zur Definition einer Anfrage (mit Parametern, Wertebereichen, Default-Werten und Beschreibungen) und die zugehörigen Antworten (ebenfalls mit allen Details). Die möglichen Antworten werden in unterschiedlichen Farben dargestellt, je nachdem ob der zurückgelieferte HTTP-Status-Code Erfolg oder einen Fehler signalisiert.
Der rechte Beispielbereich (Request samples) zeigt für den im Inhaltsbereich ausgewählten Endpunkt die Methode und die URL, gefolgt von mehreren Beispielen zu Anfragen: die Payload im JSON-Format (falls relevant für den Endpunkt) und Code-Beispiele z.B. für cURL, HTTPie, Python Requests und Python Urllib. Dann folgen die Antworten passend zum HTTP-Status. Alle Code-Beispiele können über den Knopf Copy in die Zwischenablage kopiert werden.
Der Navigationsbereich ist scroll-synchronisiert zu den anderen beiden Bereichen, das heißt, wenn Sie im Inhaltsbereich nach oben oder unten scrollen, scrollt der Navigationsbereich automatisch zum passenden Eintrag des Inhaltsverzeichnisses mit.
Das responsive Web-Design sorgt dafür, dass in einem Browser-Fenster mit geringer Breite der Beispielbereich verschwindet (dafür werden dann die Beispiele unterhalb der zugehörigen Methode angezeigt) und der Navigationsbereich in ein Menü umgewandelt wird.
In allen Bereichen finden Sie Inhalte, die Sie ein- und ausblenden können, zum Beispiel im Navigationsbereich die Einträge für die Endpunkte und im Inhaltsbereich verschachtelte Parameter. Durch Anklicken von > oder Expand all blenden Sie die verborgenen Inhalte ein und mit ∨ oder Collapse all wieder aus.
Wie Sie die API-Dokumentation nutzen können, um aus den Informationen konkrete Anfragen zu erstellen, an den Checkmk-Server zu senden, ausführen zu lassen und den Erfolg zu kontrollieren: all das erfahren Sie im nächsten Kapitel.
3. Die API nutzen
3.1. Authentifizierung
Um von einem Client aus die REST-API nutzen zu können, muss auf dem Checkmk-Server ein Automationsbenutzer eingerichtet sein. Nur dieser ist berechtigt, Aktionen über die API auszuführen.
Für die Authentifizierung benötigen Sie den Benutzernamen und das zugehörige, sogenannte "automation secret for machine accounts", das heißt das Passwort des Automationsbenutzers. Beide Informationen müssen im Header jeder Anfrage an den Checkmk-Server übermittelt werden. Bei einer neu erstellten Instanz (site) ist der Benutzer automation bereits angelegt. Sie finden ihn, wie andere Benutzer auch, unter Setup ⇒ Users. Achten Sie darauf, dass die Rollen und die damit verbundenen Berechtigungen für den Automationsbenutzer so gesetzt sind, dass Sie die Ausführung Ihrer Anfragen erlauben.
In diesem Artikel wird immer der standardmäßig eingerichtete Automationsbenutzer als Beispiel genommen.
3.2. Die API lokal testen
Um die REST-API zu testen, bietet es sich an, die Anfragen direkt vom Checkmk-Server aus zu stellen, das heißt, in diesem Fall befinden sich Client und Server auf dem gleichen Rechner. Wenn Sie als Instanzbenutzer arbeiten, können Sie zudem lokale Variablen wie z.B. $OMD_SITE benutzen, die auf den Namen der Instanz verweist.
In den folgenden Beispielen nutzen wir den in der API-Dokumentation enthaltenen Beispiel-Code für das Kommandozeilenprogramms cURL, das es ermöglicht, ohne Benutzerinteraktion Daten von oder zu einem Server zum Beispiel per HTTP zu übertragen. Das curl-Kommando wird innerhalb eines Bash-Skripts ausgeführt.
Zur Vorbereitung erstellen Sie eine Skript-Datei, in die später der Beispiel-Code kopiert wird:
OMD[mysite]:~$ touch rest-api_test.sh
OMD[mysite]:~$ chmod +x rest-api_test.shBevor es los geht, sammeln Sie einige grundlegenden Informationen, die spezifisch für Ihre Checkmk-Konfiguration sind:
| Variable | Beispielwert | Bedeutung |
|---|---|---|
HOST_NAME | myserver | Hostname des Checkmk-Servers |
SITE_NAME | mysite | Name der Checkmk-Instanz |
USERNAME | automation | Name des Automationsbenutzers |
PASSWORD | theautomationsecret | Passwort des Automationsbenutzers |
Diese Variablen werden im Beispiel-Code verwendet und müssen von Ihnen geändert werden, bevor Sie eine Anfrage absenden. In der obigen Tabelle finden Sie auch die Beispielwerte, die im folgenden verwendet werden.
3.3. Anfragen stellen per Skript
Wir werden nun den Umgang mit der REST-API an einem übersichtlichen Beispiel demonstrieren: Sie erstellen einen Host mit seinen Services mit insgesamt drei Anfragen. Prinzipiell gehen Sie dabei genauso vor, wie Sie es auch mit der Checkmk GUI tun würden:
Einen Host erstellen
Eine Serviceerkennung auf dem Host durchführen
Die Änderungen aktivieren
Einen Host erstellen
Öffnen Sie die API-Dokumentation und suchen Sie im linken Navigationsbereich den Eintrag zum Erstellen eines Hosts (Create a host):
Im mittleren Bereich sehen Sie die Details zur gewählten Anfrage: welche HTTP-Authentifizierung gefordert ist (diese ist identisch für alle Anfragen über die REST-API) und die notwendigen und optionalen Parameter. Notwendig (required) ist der Name des Hosts und der Ordner, in dem er angelegt werden soll. Sollten Sie den Host nicht im Hauptordner (main directory) anlegen wollen, müssten Sie sich erst über eine andere API-Anfrage (List all folders) die existierenden Ordner anzeigen lassen, um die ID des gewünschten herauszufinden.
In unserem Beispiel wollen wir den Host myserver123 mit der IP-Adresse 192.168.0.42 im Hauptordner erstellen.
In der API-Dokumentation klicken Sie im rechten Beispielbereich auf den Knopf curl und dann auf Copy um den cURL-Beispielcode in die Zwischenablage zu kopieren. Öffnen Sie das vorbereitete Skript rest-api_test.sh und fügen Sie den Inhalt der Zwischenablage ein:
.
#!/bin/bash
HOST_NAME="localhost"
SITE_NAME="heute"
API_URL="http://$HOST_NAME/$SITE_NAME/check_mk/api/v0"
USERNAME="automation"
PASSWORD="test123"
curl \
-X POST \
--header "Authorization: Bearer $USERNAME $PASSWORD" \
--header "Accept: application/json" \ \
--data '{
"attributes": {
"ipaddress": "192.168.0.123"
},
"folder": "\/",
"host_name": "example.com"
}' \
"$API_URL/domain-types/host_config/collections/all"Im ersten Teil des Beispiel-Codes finden Sie die vier zu ändernden Umgebungsvariablen, dann folgt das curl-Kommando mit der POST-Methode auf die Ressource, deren URL in der letzten Zeile steht. In der POST-Methode finden Sie nach den Header-Zeilen (eine davon definiert die HTTP-Authentifizierung) den Datenteil, in dem die Parameter für den neuen Host festgelegt werden.
Beachten Sie, dass der curl-Beispiel-Code mehr Parameter enthalten kann, als Sie im konkreten Fall vielleicht benötigen. Für unser Beispiel ist dies aber nicht der Fall, und Sie müssen nur die beiden vorhandenen Parameter host_name und ipaddress ändern.
Passen Sie nun den Beispiel-Code an, so dass das Resultat ungefähr so aussieht:
.
#!/bin/bash
HOST_NAME="*myserver*"
SITE_NAME="*mysite*"
API_URL="http://$HOST_NAME/$SITE_NAME/check_mk/api/v0"
USERNAME="*automation*"
PASSWORD="*theautomationsecret*"
curl \
-X POST \
--header "Authorization: Bearer $USERNAME $PASSWORD" \
--header "Content-Type: application/json" \
--header "Accept: application/json" \
--data '{
"attributes": {
"ipaddress": "*192.168.0.42*"
},
"folder": "*\/*",
"host_name": "*myserver123*"
}' \
"$API_URL/domain-types/host_config/collections/all"Führen Sie das Skript aus:
OMD[mysite]:~$ ./rest-api_test.sh
{
"domainType":"host_config",
"id":"myserver",
"title":null,
"links":[
{ "rel":"self",
"href":"\/objects\/host_config\/myserver123",
"method":"GET",
"type":"application\/json",
"domainType":"link" },
{ "rel":"urn:org.restfulobjects:rels\/update",
"href":"\/objects\/host_config\/myserver123",
"method":"PUT",
"type":"application\/json",
"domainType":"link" },
{ "rel":"urn:org.restfulobjects:rels\/delete",
"href":"\/objects\/host_config\/myserver123",
"method":"DELETE",
"type":"application\/json",
"domainType":"link" }],
"members":{
"folder_config":{
"id":"folder_config",
"memberType":"property",
"value":"\/objects\/folder_config\/8bef58303863484da83f51d99d9caebc",
"format":"string",
"title":null,
"choices":[],
"links":[
{ "rel":"self",
"href":"\/objects\/host_config\/myserver123\/properties\/folder_config",
"method":"GET",
"type":"application\/json;profile=\"urn:org.restfulobjects:rels\/object_property\"",
"domainType":"link" }]}},
"extensions":{
"attributes":{
"ipaddress":"192.168.0.42"},
"is_cluster":false,
"is_offline":false,
"cluster_nodes":null}
}Hinweis: Die REST-API gibt alle Antworten einzeilig (unformatiert) aus. Zur besseren Lesbarkeit haben wir die Ausgabe im obigen, wie auch in allen folgenden Beispielen, mehrzeilig formatiert.
In der Antwort erkennen Sie an den fett formatierten Einträgen, dass der Host erstellt wurde. Nach der ID des Hosts liefert die API unter links eine Auswahl von Anfragen zurück, die auf den gerade erstellten Host angewendet werden können — wie es sich für eine REST-API gehört. Unter members werden Informationen über den Ordner gezeigt (erneut mit einer möglichen Folge-Anfrage) und unter extensions die Parameter und Attribute inklusive der eingerichteten IP-Adresse.
Eine Serviceerkennung auf dem Host durchführen
Nachdem der Host myserver123 erstellt wurde, können die Services ermittelt werden. Wählen Sie dazu in der API-Dokumentation den Eintrag zur Ausführung einer Serviceerkennung aus (Execute a service discovery of a host), kopieren Sie den Beispiel-Code in das Skript und passen Sie es an Ihre Konfiguration an.
Den ersten Teil mit den Umgebungsvariablen können Sie 1:1 aus dem vorherigen Beispiel übernehmen. Im curl-Kommando ändern Sie den Namen des Hosts zu myserver123. Bei dieser Anfrage wird, im Unterschied zur vorherigen, der Name nicht in einem Datenteil festgelegt, sondern ist Bestandteil der URL in der letzten Zeile:
.
HOST_NAME="*myserver*"
SITE_NAME="*mysite*"
API_URL="http://$HOST_NAME/$SITE_NAME/check_mk/api/v0"
USERNAME="*automation*"
PASSWORD="*theautomationsecret*"
curl \
-X POST \
--header "Authorization: Bearer $USERNAME $PASSWORD" \
--header "Accept: application/json" \
"$API_URL/objects/host/*myserver123*/actions/discover-services/mode/tabula-rasa"Führen Sie auch dieses Skript aus.
Die Änderungen aktivieren
Zum Abschluss müssen die Änderungen aktiviert werden. Die passende Anfrage heißt Activate pending changes.
Wie zuvor übernehmen Sie den ersten Teil mit den Umgebungsvariablen aus den vorherigen Beispielen. Ändern Sie im Datenteil des curl-Kommandos den Parameter sites und setzen ihn auf den Namen der Instanz - dort, wo die Änderungen aktiviert werden sollen:
.
#!/bin/bash
HOST_NAME="*myserver*"
SITE_NAME="*mysite*"
API_URL="http://$HOST_NAME/$SITE_NAME/check_mk/api/v0"
USERNAME="*automation*"
PASSWORD="*theautomationsecret*"
curl \
-X POST \
--header "Authorization: Bearer $USERNAME $PASSWORD" \
--header "Accept: application/json" \
--data '{
"redirect": false,
"sites": [
"*mysite*"
]
}' \
"$API_URL/domain-types/activation_run/actions/activate-changes/invoke"Führen Sie das Skript aus:
OMD[mysite]:~$ ./rest-api_test.sh
{
"domainType":"activation_run",
"id":"66d50347-4974-491f-ba5c-2dee126cf796",
"title":"Activation 66d50347-4974-491f-ba5c-2dee126cf796 was started.",
"links":[
{ "rel":"self",
"href":"\/objects\/activation_run\/66d50347-4974-491f-ba5c-2dee126cf796",
"method":"GET",
"type":"application\/json",
"domainType":"link"},
{ "rel":"urn:com.checkmk:rels\/wait-for-completion",
"href":"\/objects\/activation_run\/66d50347-4974-491f-ba5c-2dee126cf796\/actions\/wait-for-completion\/invoke",
"method":"GET",
"type":"application\/json",
"domainType":"link"}],
"members":{},
"extensions":{}
}Der fett-markierte Text zeigt, dass die Aktivierung gestartet wurde. Wieder schlägt die REST-API unter links zwei sinnvolle Folge-Anfragen vor: um den Status dieser Aktivierung abzufragen und auf deren Abschluss zu warten.
3.4. Anfragen stellen per REST-API GUI
Mit der REST-API GUI erhalten Sie eine neue Perspektive auf die API: Sie können mit dieser GUI aus dem Browser heraus direkt mit der API interagieren, indem Sie Anfragen per cURL-Kommando an den Server senden und postwendend die Antworten sehen. Dafür müssen Sie in der API GUI auf die Code-Beispiele der REST-API-Dokumentation verzichten: beide Sichten sind eben für ihren Anwendungszweck optimiert.
Die REST-API GUI wird aus der gleichen Quelle wie die REST-API-Dokumentation generiert — dem OpenAPI-Dokument — und bietet daher stets die zur API passenden Funktionen an.
Sie öffnen die API GUI in der Checkmk GUI über die Navigationsleiste im Menü Help > Internal links > REST API interactive GUI. Die API GUI wird in einem neuen Browser-Fenster (bzw. Browser-Tab) angezeigt:
Im folgenden skizzieren wir, wie Sie die erste Anfrage aus dem obigen Beispiel (einen Host erstellen) statt per Skript auch mit der REST-API GUI ausführen können:
Autorisieren: Klicken Sie den Knopf Authorize. Sie finden diesen über dem Eintrag des ersten Endpunkt-Ordners. Geben Sie in der sich öffnenden Dialogbox
automation theautomationsecretein, bestätigen Sie per Authorize und klicken Sie Close. Die Autorisierung bleibt so lange gültig, bis die Seite neu geladen wird. Ob die Autorisierung erfolgreich war, erfahren Sie allerdings erst nach dem Absenden der ersten Anfrage.Endpunkt auswählen: Wählen Sie im Ordner Hosts den Endpunkt Create a host aus und klicken Sie Try it out.
Parameterwerte eingeben: Überschreiben Sie im Request body die Beispielwerte für
host_nameundipaddress.Anfrage senden: Klicken Sie Execute.
Antwort überprüfen: Unter Responses sehen Sie zunächst das gesendete cURL-Kommando und die URL des Endpunkts. Anschließend wird unter Server response die Antwort angezeigt mit HTTP-Status-Code und im Response body der (mehrzeilig formatierten) REST-API Antwort.
Die REST-API GUI bietet Ihnen also die Möglichkeit, schnell und unkompliziert die Funktionen der API auszuprobieren und sich mit den Details der Eingabewerte und mit konkreten Antworten vertraut zu machen.
3.5. Fehler korrigieren
Im Gegensatz zu den bisher gezeigten Ausgaben bei erfolgreichen Kommandos per Skript, zeigt Ihnen die REST-API Fehler in der folgenden Art an:
{
"title":"There are changes from other users and foreign changes are not allowed in this API call.",
"status":401,
"detail":"An exception occurred.",
"ext":null
}Je nach Fehler können die in der Ausgabe angezeigten Parameter unterschiedlich sein. Immer erhalten sie aber in status den HTTP-Status-Code und in title eine Beschreibung der Fehlerursache. Im obigen Beispiel erfahren Sie, dass es zwar ausstehende Änderungen in Checkmk gibt, die aber von einem anderen Benutzer veranlasst wurden. Über die API können nur Änderungen aktiviert werden, die auch über die API durchgeführt wurden.
In den meisten Fällen zeigt Ihnen detail, wie der Name schon vermuten lässt, detaillierte Informationen an. Diese können weniger hilfreich sein (wie oben) oder sehr hilfreich wie im nächsten Beispiel:
{
"title": "Bad request.",
"status": 400,
"detail": "These fields have problems: host_name",
"host_name": [
"'myserver/123' does not match pattern '[-0-9a-zA-Z_.]+'."
]
}Hier liegt das Problem darin, dass ein Parameterwert sich nicht an den gültigen Wertebereich hält (wegen eines Schrägstrichs im Hostnamen).
Die Anzahl der möglichen Fehler ist natürlich sehr viel länger als die beiden, die wir vorgestellt haben. An den gezeigten Beispielen sehen Sie aber, dass die REST-API in der Ausgabe meist genügend Informationen über die Ursache liefert und Ihnen so Anhaltspunkte für den Einstieg in die Analyse und die Fehlerbehebung gibt.
4. Die API absichern
Da beim Zugriff über die REST-API sensible Daten übertragen und — je nach Berechtigung des Automationsbenutzers — umfassende Änderungen an Checkmk durchgeführt werden können, sollten Sie den Zugriff entsprechend absichern. Hier finden Sie einige der Möglichkeiten:
Checkmk über HTTPS: Nutzen Sie die API ausschließlich über das Hypertext Transfer Protocol Secure (HTTPS), da Benutzername, Passwort und auch Konfigurationsdaten sonst im Klartext im Netz übertragen werden.
Geben Sie dem Automationsbenutzer ein Passwort mit einer ausreichenden Länge. Da das Passwort in der Regel nur in einem Skript hinterlegt wird, können Sie problemlos ein sehr langes vergeben.
Achten Sie auf das Berechtigungskonzept zu den Skripten, mit denen Sie die Anfragen an die API stellen. In den Skripten können sensible Daten, wie Konfigurationsdaten, Passwörter usw. enthalten sein. Stellen Sie daher sicher, dass ausschließlich berechtigte Benutzer und Gruppen diese Skripten lesen können.
5. REST-API und Web-API im Vergleich
In diesem Kapitel erhalten Sie einen Überblick, welche Funktionen Ihnen über die REST-API und über die Web-API zur Verfügung stehen. Die folgende Tabelle ist gegliedert nach den Endpunkten, die sie im linken Navigationsbereich der REST-API-Dokumentation wiederfinden. In der Tabelle enthält die Spalte für die REST-API die HTTP-Methoden (bei Mehrdeutigkeit ergänzt um Kontextinformationen) und die Spalte für die Web-API die Befehle.
Aktion | REST-API | Web-API |
ausstehende Änderungen aktivieren | POST activate-changes | activate_changes |
auf Abschluss einer Aktivierung warten | GET wait-for-completion | - |
Zustand einer Aktivierung anzeigen | GET activation_run | - |
laufende Aktivierungen anzeigen | GET collections running | - |
anzeigen | GET | get_folder |
alle anzeigen | GET all | get_all_folder |
erstellen | POST | add_folder |
mehrere erstellen | POST bulk-create | - |
ändern | PUT | edit_folder |
mehrere ändern | PUT bulk-update | - |
verschieben | POST move | - |
entfernen | DEL | delete_folder |
mehrere entfernen | DEL bulk-delete | - |
anzeigen | GET | get_host |
alle anzeigen | GET all | get_all_hosts |
erstellen | POST | add_host |
Cluster-Host erstellen | POST clusters | - |
mehrere erstellen | POST bulk-create | - |
ändern | PUT | edit_host |
Cluster-Knoten ändern | PUT nodes | - |
mehrere ändern | PUT bulk-update | - |
umbenennen | PUT rename | - |
verschieben | POST move | - |
entfernen | DEL | delete_host |
mehrere entfernen | DEL bulk-delete | delete_hosts |
Hosts eines Zustands anzeigen | GET all | - |
anzeigen | GET | - |
alle anzeigen | GET all | get_all_hostgroups |
erstellen | POST | add_hostgroup |
mehrere erstellen | POST bulk-create | - |
ändern | PUT | edit_hostgroup |
mehrere ändern | PUT bulk-update | - |
entfernen | DEL | delete_hostgroup |
mehrere entfernen | DEL bulk-delete | delete_hosts |
anzeigen | GET | get_hosttags |
erstellen | POST | - |
ändern | PUT | set_hosttags |
entfernen | DEL | - |
alle anzeigen | GET all | - |
erstellen | POST | - |
entfernen | DEL | - |
mehrere entfernen | DEL bulk-delete | - |
Serviceerkennung ausführen | POST | discover_services |
Services eines Zustands anzeigen | GET | - |
Serviceerkennungszustand ändern | PUT | - |
Services eines Zustands auf einem Host anzeigen | GET | - |
Services eines Zustands global anzeigen | GET all | - |
anzeigen | GET | - |
alle anzeigen | GET all | get_all_servicegroups |
erstellen | POST | add_servicegroup |
mehrere erstellen | POST bulk-create | - |
ändern | PUT | edit_servicegroup |
mehrere ändern | PUT bulk-update | - |
entfernen | DEL | delete_servicegroup |
mehrere entfernen | DEL bulk-delete | - |
anzeigen | - | get_ruleset |
alle anzeigen | - | get_ruleset_info |
ändern | - | set_ruleset |
BI-Regel anzeigen | GET bi_rule | - |
BI-Regel ändern | PUT bi_rule | - |
BI-Regel entfernen | DEL bi_rule | - |
BI-Aggregat anzeigen | GET bi_aggregation | - |
BI-Aggregat ändern | PUT bi_aggregation | - |
BI-Aggregat entfernen | DEL bi_aggregation | - |
BI-Paket anzeigen | GET bi_pack | - |
alle BI-Pakete anzeigen | GET all bi_pack | - |
anzeigen | GET | - |
erstellen | POST | - |
ändern | PUT | - |
entfernen | DEL | - |
alle anzeigen | - | get_all_users |
mehrere erstellen | - | add_users |
mehrere ändern | - | edit_users |
mehrere entfernen | - | delete_users |
anzeigen | GET | - |
erstellen | POST | - |
ändern | PUT | - |
entfernen | DEL | - |
anzeigen | GET | - |
alle anzeigen | GET all | get_all_contactgroups |
erstellen | POST | add_contactgroup |
mehrere erstellen | POST bulk-create | - |
ändern | PUT | edit_contactgroup |
mehrere ändern | PUT bulk-update | - |
entfernen | DEL | delete_contactgroup |
mehrere entfernen | DEL bulk-delete | - |
für einen Host quittieren | POST host | - |
für mehrere Hosts quittieren | POST host bulk-acknowledge | - |
für Hosts einer Host-Gruppe quittieren | POST hostgroup | - |
für Services auf einem Host quittieren | POST host service | - |
für einen Service global quittieren | POST service | - |
für mehrere Services auf einem Host quittieren | POST service bulk-acknowledge | - |
für Services einer Service-Gruppe quittieren | POST servicegroup | - |
alle Agenten anzeigen | GET collections agent | - |
alle Agenten backen | POST bake | bake_agents |
alle Agenten signieren | POST sign | - |
alle Agenten backen und signieren | POST bake_and_sign | - |
Backzustand anzeigen | GET baking_status | - |
Zustand der automatischen Agentenverteilung anzeigen | GET automatic-deployment | - |
Agent herunterladen | GET agent | - |
anzeigen | - | get_site |
aktualisieren | - | set_site |
entfernen | - | delete_site |
anmelden | - | login_site |
abmelden | - | logout_site |
Versionsinformationen anzeigen | GET version | - |
Instanzen eines Benutzers anzeigen | - | get_user_sites |
Host-Namen aller Instanzen anzeigen | - | get_host_names |
Metriken aller Services eines Hosts anzeigen | - | get_metrics_of_host |
Graph-Informationen eines Services anzeigen | - | get_graph_recipes |
Metriken eines Graphen anzeigen | - | get_graph |
Service Level Agreement (SLA)-Informationen anzeigen | - | get_sla |