REST steht für Representational State Transfer und stellt eine Schnittstelle für Konfiguration, Statusabfrage und Ausführung manueller Aktionen der icom Data Suite über das HTTP- und HTTPS-Protokoll zur Verfügung.

Nutzen der REST-Schnittstelle: Die HTTP(S)-REST-Schnittstelle erlaubt es, die icom Data Suite mithilfe von Skripten automatisiert zu konfigurieren oder Werte abzufragen.

Im Folgenden finden Sie ein Beispiel für das Auslesen, Hinzufügen, Ändern und Löschen von Konfigurationen über die REST-Schnittstelle mit der App Postman und dem Web-basierten Tool Swagger. Dies soll Ihnen vermitteln, wie Sie die erforderliche Syntax für Befehl und übermittelten Konfigurationsinformationen (Payload) mithilfe verschiedener Tools ermitteln und an die icom Data Suite übertragen.

Der Configuration Guide basiert auf einer icom Data Suite in Werkseinstellungen. Bei individuellen Konfigurationen kann die Beschreibung hinsichtlich Profilen, Adressen usw. abweichen.

Die REST-Schnittstelle wird von der icom Data Suite ab der Version 1.5 unterstützt. Die genannten Tools sind nur Beispiele und dienen als Leitfaden für den Umgang mit der REST-Schnittstelle mithilfe externer Tools.

Note Die Dokumentation der REST API enthält sämtliche Befehle, die in der icom Data Suite auf den verschiedenen Konfigurationen und Ausstattungsvarianten des Routers verfügbar sind. Nicht alle enthaltenen Befehle werden von der icom Data Suite auf Ihrem Router unterstützt. icom Data Suite und REST API-Dokumentation müssen denselben Firmware-Stand haben.

1. Situation

Folgende Konfigurationsschritte sollen über die REST-Schnittstelle erfolgen:

  • Abfragen der aktuell konfigurierten Benutzer der icom Data Suite

  • Hinzufügen eines neuen Benutzers

  • Ändern der Konfiguration dieses Benutzers

  • Löschen des neu hinzugefügten Benutzers

2. Lösung

Die gesamte Dokumentation der REST API wird in Form einer JSON-Datei gemäß der OpenAPI-Spezifikation 3.0 aus der icom Data Suite heruntergeladen. Diese JSON-Datei wird in einem Tool wie dem Swagger Editor oder Postman geöffnet, um die Syntax für die Befehlsübermittlung zu ermitteln. Die angepassten Konfigurationsbefehle werden dann mit diesen Tools oder über einen cURL-Befehl an die icom Data Suite übermittelt.
Stellen Sie sicher, dass Sie Zugriff auf das Web-Interface der icom Data Suite haben.

2.1. Aktivieren der REST-Schnittstelle und Herunterladen der REST API-Dokumentation

  1. Web-Interface der icom Data Suite mit einem Browser aufrufen: 192.168.1.10 [1]

  2. Im Menü Administration → REST-Interface die Checkbox REST-Interface via HTTPS aktivieren markieren und auf Einstellungen speichern klicken.

  3. Auf download REST API Dokumentation (OpenAPI als JSON) klicken und die REST API-Dokumentation auf den Rechner herunterladen.
    cg de m3 rest interface 01

  4. Auf das blinkende Zahnrad in der Titelleiste (cog) klicken, um das Profil zu aktivieren.

2.2. Ermitteln der REST-Syntax und Übertragen der Konfigurationsbefehle an die icom Data Suite

Ein besonders bequemer Weg hierfür sind REST API-Tools wie Postman und der Swagger Editor. Konfigurationsbefehle können auch mithilfe von cURL auch aus einer Kommandozeile heraus erfolgen.

2.2.1. Postman

Die Postman-App ist ein nützliches Tool, um mit der icom Data Suite über die REST-Schnittstelle zu kommunizieren. Im Folgenden wird beschrieben, wie Sie in der Postman-App die REST API-Dokumentation der icom Data Suite importieren, die Zugangsdaten für die REST-Schnittstelle hinterlegen sowie die Umgebungsvariablen für die Kommunikation mit der icom Data Suite überprüfen. Weiter wird am Beispiel der Benutzerkonfiguration beschrieben, wie Sie mit Hilfe der Befehle GET, POST, PUT und DELETE Konfigurationen auslesen, hinzufügen, ändern und löschen. Außerdem erfahren Sie, wie Sie manuelle Aktionen ausführen.

  1. Laden Sie die Postman-App herunter und installieren Sie diese.

  2. Öffnen Sie die Postman-App

  3. Klicken Sie auf die Schaltfläche Import im Bereich My Workspace oben links (oder im Menü File → Import…​) und öffnen Sie die oben heruntergeladene REST API-Dokumentation.

  4. Klicken Sie auf right Show import settings, aktivieren sie Copy collections to workspace und klicken Sie auf die Schaltfläche Import.
    cg en ids rest interface pm 01

  5. Klicken Sie auf die Schaltfläche Close um den Import abzuschließen.
    Die Dokumentation der REST API der icom Data Suite wird als Sammlung (Collection) angezeigt.

  6. Fahren Sie über die neue Sammlung, klicken Sie auf dots horizontal View more actions und wählen Sie pencil Edit.
    cg en ids rest interface pm 02

  7. Wechseln Sie im Feld der icom Data Suite - REST API auf die Registerkarte Authorization, wählen Sie den Type Basic Auth und geben Sie den Username und das zugehörige Password des Benutzers ein. Der Benutzer muss im Menü Administration → Benutzer der icom Data Suite mit Lese- und Schreibrechten angelegt sein.
    cg en ids rest interface pm 03

  8. Klicken Sie auf content save outline Save collection, um die Zugangsdaten in der Sammlung zu hinterlegen.

  9. Wechseln Sie auf die Registerkarte Variables und überprüfen Sie die hinterlegten Variablen für Protokoll (HTTP oder HTTPS), IP-Adresse der icom Data Suite und Port für den HTTP-/HTTPS-Zugang. Mit der oben importierten REST API-Dokumentation werden hier die Standardwerte der icom Data Suite übergeben. Wurden diese geändert, müssen Sie hier angepasst werden. [2]
    cg en ids rest interface pm 04

2.2.1.1. Abfragen der Benutzer-Konfiguration

Der erforderliche HTTP-Befehl zum Auslesen von Ressourcen (Parameter bzw. Einträge) ist GET. Die Syntax des Befehls ist in der Dokumentation der REST API beschrieben.

  1. Navigieren sie in der Sammlung icom Data Suite - REST API zu configuration → administration → users und klicken sie auf den Befehl GET.

  2. Deaktivieren Sie im Abschnitt Query Params die Checkboxen für profile, return_size und filter.

  3. Klicken Sie auf die Schaltfläche Send, um den GET-Befehl an die icom Data Suite zu senden.

Die Antwort erscheint im unteren Teil des Fensters der Postman-App im JSON-Format mit dem Status-Code 200 OK. Sie enthält die Benutzer-Konfiguration der icom Data Suite. Vergleichen Sie dazu die Konfiguration im Web-Interface der icom Data Suite im Menü Administration auf der Seite Benutzer.
cg en ids rest interface pm 05
cg ids m3 rest interface 02

2.2.1.2. Hinzufügen eines Benutzers

Der erforderliche HTTP-Befehl zum Hinzufügen von Ressourcen (Parameter bzw. Einträge) ist POST. Die Syntax des Befehls ist in der Dokumentation der REST API beschrieben.

  1. Navigieren sie in der Sammlung icom Data Suite - REST API zu configuration → administration → users und klicken sie auf den Befehl POST.

  2. Wechseln Sie auf die Registerkarte Body und passen Sie die Nutzlast im JSON-Format wie folgt an oder kopieren Sie diese hinein.

{
  "profile": {
    "name": "Profile",
    "activate": "0"
  },
  "config": {
    "user": [
      {
        "active": "1",
        "username": "CGTestUser",
        "password": "icom",
        "group": "read"
      }
    ]
  }
}

  1. Klicken Sie auf die Schaltfläche Send, um den POST-Befehl an die icom Data Suite zu senden.

Mit diesem Befehl wird ein neuer aktiver Benutzer mit dem Benutzernamen CGTestUser, dem Passwort icom und der Benutzergruppe Lesen dem Profil Profile hinzugefügt, das anschließend nicht aktiviert wird.

Die Antwort erscheint im unteren Teil des Fensters der Postman-App im JSON-Format mit dem Status-Code 201 Created. Die oben übertragene Konfiguration wird noch einmal angezeigt.
cg en ids rest interface pm 06

Vergleichen Sie dazu die Konfiguration im Web-Interface der icom Data Suite im Menü Administration auf der Seite Benutzer mit dem neu hinzugefügten Benutzer. [3]
cg de ids rest interface 03

2.2.1.3. Ändern der Konfiguration eines Benutzers

Der erforderliche HTTP-Befehl zum Hinzufügen von Ressourcen (Parameter bzw. Einträge) ist PUT. Die Syntax des Befehls ist in der Dokumentation der REST API beschrieben.

  1. Navigieren sie in der Sammlung icom Data Suite - REST API zu configuration → administration → users und klicken sie auf den Befehl PUT.

  2. Wechseln Sie auf die Registerkarte Body und passen Sie die Nutzlast im JSON-Format wie folgt an oder kopieren Sie diese hinein.

{
  "profile": {
    "name": "Profile",
    "activate": "0"
  },
  "config": {
    "user": [
      {
        "group": "readwrite",
        "index": "user2"
      }
    ]
  }
}

  1. Klicken Sie auf die Schaltfläche Send, um den PUT-Befehl an die icom Data Suite zu senden.

Mit diesem Befehl wird für den Benutzer mit dem Index user2 im Profil Profile die Benutzergruppe auf Lesen/Schreiben gesetzt. Damit wird die Benutzergruppe des oben hinzugefügten Benutzers geändert. Der Index des Benutzers wird angezeigt, wenn man nach dem Hinzufügen noch einmal den GET-Befehl zur Abfrage der Benutzer-Konfiguration ausführt.

Die Antwort erscheint im unteren Teil des Fensters der Postman-App im JSON-Format mit dem Status-Code 200 OK.
cg en ids rest interface pm 07

Vergleichen Sie dazu die Konfiguration im Web-Interface der icom Data Suite im Menü Administration auf der Seite Benutzer mit der geänderten Benutzergruppe. [3]
cg de ids rest interface 04

2.2.1.4. Löschen eines Benutzers

Der erforderliche HTTP-Befehl zum Hinzufügen von Ressourcen (Parameter bzw. Einträge) ist DELETE. Die Syntax des Befehls ist in der Dokumentation der REST API beschrieben.

  1. Navigieren sie in der Sammlung icom Data Suite - REST API zu configuration → administration → users und klicken sie auf den Befehl DEL.

  2. Tragen Sie auf der Registerkarte Params unter Query Params für den Abfrageparameter profile den Wert Profile ein. Damit werden alle Benutzer, die den Filterkriterien entsprechen, aus dem Profil Profile gelöscht.

  3. Tragen Sie für den Abfrageparameter filter den Wert {"p":"username","o":"like","v":"test"} ein. Damit werden alle Benutzer aus dem angegebenen (oder dem zuletzt aktivierten, wenn kein Profil angegeben ist) Profil gelöscht, deren Benutzername ("p":"username") die Zeichenfolge test ("v":"test") enthält ("o":"like").

Note Jeder Filter besteht aus drei Parametern:
"p" : "zu filternder Paramater"
"o" : "für den Filter zu verwendender Operator, entweder "eq" (equal, gleich) für eine genaue Übereinstimmung oder "like" (ähnlich) wenn die angegebene Zeichenfolge nur enthalten sein soll"
"v" : "Wert nach dem der Parameter gemäß dem Operator gefiltert werden soll"

  1. Klicken Sie auf die Schaltfläche Send, um den DELETE-Befehl an die icom Data Suite zu senden.

Die Antwort erscheint im unteren Teil des Fensters der Postman-App im JSON-Format mit dem Status-Code 200 OK.
cg en ids rest interface pm 08

Vergleichen Sie dazu die Konfiguration im Web-Interface der icom Data Suite im Menü Administration auf der Seite Benutzer mit dem nun wieder gelöschten Benutzer. [3]
cg de ids rest interface 02

2.2.1.5. Manuelles Ausführen von Aktionen

Die icom Data Suite ermöglicht das Ausführen einer Vielzahl von Aktionen, wie Neustart, Starten eines Timers, Meldungsversand oder Setzen eines Datenpunkts. Aktionen werden bei Eintreten eines Ereignisses ausgelöst, können aber auch manuell ausgelöst werden.

Leider ist es nicht ohne weiteres möglich, die Syntax des JSON-Bodys für manuelle Aktionen in Postman zu ermitteln. Die erforderliche Syntax lässt sich jedoch über die CLI herausfinden. Siehe dazu die Seiten Rest-Schnittstelle → Debugging und Auslösen manueller Aktionen sowie Ermitteln der Befehls-Syntax für CLI und REST-Schnittstelle in der Online-Hilfe der icom Data Suite bzw. des Routers (für den an den Router übermittelten CLI-Befehl).

2.2.1.5.1. Beispiel 1: Schalten der Info-LED

In diesem Beispiel soll die Info-LED am Router manuell zum Blinken gebracht werden.

Der erforderliche HTTP-Befehl zum manuellen Auslösen von Aktionen ist POST.

  1. Navigieren sie in der Sammlung icom Data Suite - REST API zu operation und klicken sie auf den Befehl POST.

  2. Wechseln Sie auf die Registerkarte Body und passen Sie die Nutzlast im JSON-Format wie folgt an oder kopieren Sie diese hinein.

{
    "method" : "manual_action",
    "params" : {
        "type" : "m3_cli",
        "options" : {
            "command" : "help.debug.info_led.info_led=flash\nhelp.debug.info_led.submit"
        }
    }
}

  1. Klicken Sie auf die Schaltfläche Send, um den POST-Befehl an die icom Data Suite zu senden.

Mit diesem Befehl wird die Info-LED am Router zum Blinken gebracht. Analog dazu wird sie mit dem Wert off für den Parameter info_led deaktiviert oder mit on aktiviert. Der CLI-Befehl besteht aus den beiden Befehlen help.debug.info_led.info_led=flash zum Setzen der LED auf Blinken und help.debug.info_led.submit zum Übertragen des gesetzten Parameters, verbunden durch \n für einen Zeilenumbruch zwischen den beiden Befehlen.

Die Antwort erscheint im unteren Teil des Fensters der Postman-App im JSON-Format mit dem Status-Code 201 Created.
cg en ids rest interface pm 09

Beobachten Sie dazu auch die LED am Router.

2.2.1.5.2. Beispiel 2: Setzen eines Analogwerts

In diesem Beispiel soll der Merker flag1 auf einen bestimmten Wert gesetzt werden. Dabei wird vorausgesetzt, dass in der icom Data Suite dieser Merker mit einem analogen Datentyp angelegt ist.

Der erforderliche HTTP-Befehl zum manuellen Auslösen von Aktionen ist POST.

  1. Navigieren sie in der Sammlung icom Data Suite - REST API zu operation und klicken sie auf den Befehl POST.

  2. Wechseln Sie auf die Registerkarte Body und passen Sie die Nutzlast im JSON-Format wie folgt an oder kopieren Sie diese hinein.

{
  "method": "manual_action",
  "params": {
    "type": "analog",
    "options": {
      "datapoint": "flag1",
      "change": "set_to",
      "set":"to_value",
      "value":"123555"
    }
  }
}

  1. Klicken Sie auf die Schaltfläche Send, um den POST-Befehl an die icom Data Suite zu senden.

Mit diesem Befehl wird der analoge Datenpunkt (Merker) flag1 auf den Wert 123555 gesetzt.

Die Antwort erscheint im unteren Teil des Fensters der Postman-App im JSON-Format mit dem Status-Code 201 Created.
cg en ids rest interface pm 10

Öffnen Sie im Web-Interface der icom Data Suite die Seite Status → Aktuelle Werte und prüfen Sie, ob sich der Wert des Merkers flag1 auf den entsprechenden Wert geändert hat.

2.2.2. Swagger Editor

Der Swagger Editor ist ein nützliches Online-Tool, um eine Übersicht über alle vorhandenen Befehle mit ihren zugehörigen Optionen zu erhalten und die Syntax von Befehlen für die Übertragung über die REST-Schnittstelle zu ermitteln. Es erfordert keine Installation.

Eine detaillierte Beschreibung der Kommunikation mit der REST-Schnittstelle der icom Data Suite mit dem Swagger-Editor folgt an dieser Stelle zu einem späteren Zeitpunkt. Informationen zur Kommunikation mit der REST-Schnittstelle des Routers mit dem Swagger-Editor finden Sie in diesem Configuration Guide.

3. Fehlersuche

  • Bei Problemen mit der cURL-Syntax ist es hilfreich, die Option -v (verbose) zu verwenden, um die Fehlersuche zu vereinfachen.

  • Wird beim Ausführen eines aus dem Swagger-Editor kopierten cURL-Befehls ein Fehler im Zusammenhang mit einer nicht vertrauenswürdigen Zertifizierungskette angezeigt, wurde möglicherweise vergessen, die cURL-Option -k an den Befehl anzuhängen, welche eine Verifizierung des Zertifikats verhindert.

  • Je nach Betriebssystem kann es sein, dass der im Swagger-Editor erzeugte cURL-Befehl im Terminal nicht direkt verarbeitet werden kann. Dann ist er wir folgt anzupassen:

    • Befehl in Text-Editor kopieren

    • Apostrophe um den cURL-Befehl (z.B. GET) entfernen

    • Apostrophe um die Parameter durch Anführungszeichen ersetzen

    • Zeilenumbrüche entfernen

    • Unnötige Leerzeichen entfernen

    • Unnötige Backslash (\) entfernen

Zurück zu den Configuration Guides für die icom OS Smart Devices

Zurück zur Übersicht

1. Voreinstellung: Benutzername: insys, Kennwort: icom
2. In einer frühen Version der REST API-Dokumentation (Firmware 4.3) ist der falsche Standard-Port für HTTPS eingetragen (9090 statt 9091) und muss hier geändert werden.
3. Um das Hinzufügen zu sehen, muss das laufende Profil in der icom Data Suite auch das Profil sein, zu dem der Benutzer hinzugefügt wurde, hier Profile