Automatisierte Alarmauslösung mit der GroupAlarm API

Über die umfangreiche GroupAlarm API können Sie automatisiert Alarme auslösen, Szenarien verwalten und vieles mehr.
Wie das geht, erfahren Sie in diesem Artikel.

Was ist eine API?

Zunächst zu den Begrifflichkeiten. Was ist überhaupt eine API?
Über eine API (Application Programming Interface, zu Deutsch Programmierschnittstelle), können Sie Anwendungen und Systeme miteinander verknüpfen.
Im Fall von GroupAlarm bietet Sie Ihnen die Möglichkeit, alle Aspekte des Systems nicht nur über die bekannte Web-Oberfläche, sondern auch aus Ihren eigenen Anwendungen heraus oder über die Kommandozeile zu bedienen. Dabei kommt eine standardisierte REST-Schnittstelle zum Einsatz, welche die Kommunikation über das HTTP-Protokoll abwickelt und Daten im JSON-Format übermittelt.

Authentifizierung

Damit nicht jeder Benutzer in Ihrem Namen Änderungen vornehmen kann, müssen Sie Ihre Identität bei jeder Anfrage ans System über einen sogenannten “Personal Access Token” verifizieren. Diesen legen Sie bequem über die Weboberfläche in Ihrem Profil an.

Behandeln Sie den angezeigten Schlüssel wie Ihr eigenes Passwort. Gerät er in die falschen Hände, hat der Besitzer Zugriff auf Ihr gesamtes GroupAlarm-Konto. Im Zweifelsfall sollten Sie den Schlüssel sofort regenerieren oder löschen.

Automatisierte Alarmauslösung

Am Beispiel der automatisierten Alarmauslösung zeigen wir Ihnen nun, wie eine Anfrage an GroupAlarm üblicherweise abläuft.

Suchen Sie zunächst die passende Stelle in der Schnittstellendokumentation, die die gewünschte Aktion beschreibt. Im Fall der Alarmauslösung befindet sich diese hier. Dort finden Sie den Endpunkt für die Anfrage (https://app.groupalarm.com/api/v1/alarm), die zu verwendende HTTP-Methode (POST) und welche Daten im Body der Anfrage übergeben werden müssen oder optional übergeben werden können.

Damit lässt sich nun eine einfache Anfrage mittels des Kommandozeilentools curl oder jedes anderen HTTP-Clients einer beliebigen Programmiersprache aufbauen.
Alternativ können Sie auch das grafische Tool Postman verwenden und die Anfrage dort importieren oder selbst nachstellen.

1
2
3
4
5

curl -X POST \
     -H "Content-Type: application/json" \
     -H "Personal-Access-Token: bmV0dGVyIFZlcnN1Y2ggOik=" \
     -d '{"eventName": "Stromausfall", "message": "Ausfall Notstromaggregat", "mode": "best-effort", "organizationID": 133, "scenarioID": 204, "startTime": "2019-08-27T10:00:00Z"}' \
     https://app.groupalarm.com/api/v1/alarm

In diesem Beispiel wird in der Organisation 133 ein neues Ereignis “Stromausfall” angelegt, welches den neuen Alarm “Ausfall Notstromaggregat” im “best-effort” Modus startet und das Szenario 204 zur gegebenen Startzeit auslöst.
Die ID Ihrer Organisation finden Sie entweder in den Organisationseinstellungen oder in der URL Ihres Browsers nach dem Öffnen der Organisation selbst (z.B. https://app.groupalarm.com/d/organizations/{ID}).

Die ID eines Szenarios wird Ihnen z.B. in der Vorschau eines Szenarios oben rechts angezeigt und kann von dort mit einem Klick kopiert werden.

Denken Sie auch daran, den im Beispiel verwendeten Personal Access Token durch einen Ihrer eigenen Token zu ersetzen, andernfalls wird die Alarmauslösung fehlschlagen.

Als direkte Antwort auf diese Anfrage erhalten Sie die in der Dokumentation beschriebenen Daten zum neuen Alarm, die Sie für weitere Anfragen oder Ihre eigene Dokumentation verwenden können.

Und das war es auch schon! Mit einem einfachen HTTP-Aufruf können Sie Alarme aus Ihren Anwendungen und Systemen in GroupAlarm auslösen.

GroupAlarm jetzt 14 Tage kostenlos testen!