Verwendung der TOP-Energy-Serverversion
Die Python-REST-API wurde bislang nur mit Standardfällen getestet, bitte benutzen Sie sie mit Vorsicht und überprüfen Sie jeden Schritt.
Aufruf der REST-API
Die REST-API von TOP-Energy lässt sich sowohl lokal über http://localhost:8010 als auch remote über das Netzwerk via http://SERVER:8010 aufrufen. Für den externen Zugriff über das Netzwerk muss ggf. der Port 8010 in der Firewall freigegeben werden.
Vorbereitung und Installation von TOP-Energy
Zur Verwendung der REST-API ist eine spezielle Lizenz erforderlich. Erfragen Sie diese beim Support!
Befolgen Sie dann die folgenden Schritte:
- Installieren Sie topenergy_setup_X.X.X.X-x64.msi mit dem Setup-Typ Complete.
- Alternativ wählen Sie den Setup-Typ Custom und dann die Installation der REST-API.
- Stellen Sie sicher, dass TOP-Energy aktiviert ist.
Installation des Python-Paketes
Rufen Sie die englischsprachige REST-API-Dokumentation auf: mit der URL http://localhost:8010/api-doc oder im Windows-Startmenü unter TOP-EnergyX.X.X/TOP-Energy REST-API Documentation. Folgen Sie den Installationshinweisen dieser Dokumentation.
Update der TOP-Energy-Version
Beim Update von TOP-Energy auf die neueste Version müssen Sie das Python-Paket tepyapi mit dem Befehl
pip install tepyapi ‐‐upgrade ‐‐index-url http://localhost:8010
updaten (siehe auch die REST-API-Dokumentation).
Beispiel
Ein Minimalbeispiel eines Python-Skripts zur Nutzung von TOP-Energy über die Rest-API wird Ihnen mit der Installation ausgeliefert. Sie finden dieses TOP-Energy REST-API Example im Windows-Startmenü, wenn Sie TOP-Energy aufklappen. Speichern Sie dieses Skript und das Tutorial 07 in der deutschen Version in einen Ordner außerhalb Ihres Benutzerverzeichnisses.
Hinweise zur Nutzung der REST-API-Schnittstelle via Python
Stellen Sie vorab sicher, dass die Projekte in TOP-Energy lauffähig sind. Mögliche Fehler (fehlende Lizenz, nicht verbundene Pins usw.) werden nicht gesondert behandelt. Die mehrkriterielle Optimierung und die Parameterstudie lassen sich nicht über die Rest-API ausführen.
Pfad zum Ordner mit der TOP-Energy-Projektdatei
Aufgrund der Standardrechte darf der TOP-Energy-Service nicht auf ein Benutzerverzeichnis zugreifen (z. B. C:\Benutzer\$Benutzername$) und kann die TOP-Energy-Datei nicht von dort laden. Um das dennoch zu ermöglichen, geben Sie in den Einstellungen des Services vor, dass der Service als lokaler Maschinen-Administrator ausgeführt wird. Aus sicherheitstechnischer IT-Sicht sollten Sie dafür aber gute Gründe haben, denn das ist wie die ständige Arbeit mit einem Admin-Account. Per Default wird dieses Risiko ausgeschlossen.
Unterschiedliche TOP-Energy-Versionen
Sind mehrere TOP-Energy-Versionen mit Server installiert, wird immer die neueste Version verwendet. Es können nicht zwei Server parallel gestartet werden.
Über die Windowsdienste können die Dienste einzeln geschlossen oder gestartet werden: durch Öffnen der Kommandozeile als Administrator, Öffnen von services.msg und anschließend z. B. des Services TOP-Energy Automation Service X.X.X (x64).
Möchten Sie mehrere Versionen alternierend auf einem Rechner nutzen, sorgen Sie neben dem manuellen Starten/Schließen der Services auch dafür, dass das zugehörige tepyapi-Paket in Python verwendet wird. Dazu lassen sich z. B. unterschiedliche virtuelle Umgebungen verwenden:
Virtuelle Umgebung für Version 3.4 erstellen
Voraussetzung: REST-API-Service für TOP-Energy 3.4 ist aktiv.
python -m venv te_py_3_4
te_py_3_4\Scripts\activate # (Windows) | source te_py_3_4/bin/activate (Linux/macOS)
pip install tepyapi ‐‐index-url http://localhost:8010
Virtuelle Umgebung für Version 3.5 erstellen
Voraussetzung: REST-API-Service für TOP-Energy 3.5 ist aktiv.
python -m venv te_py_3_5
te_py_3_5\Scripts\activate # (Windows) | source te_py_3_5/bin/activate (Linux/macOS)
pip install tepyapi ‐‐index-url http://localhost:8010
Zeitreihen updaten
Zeitreihen, die über die API in TOP-Energy-Komponenten geschrieben werden, müssen chronologisch sortiert sein. Sie dürfen keine doppelten Werte enthalten. Es wird keine Zeitreihenprüfung durchgeführt. Bitte sorgen Sie selbst dafür, dass die Zeitreihen korrekt sind.
Standard-Antworten in TOP-Energy-Dialogen
Über die REST-API haben Sie keinen Zugriff auf die Dialoge in TOP-Energy. Daher werden alle Dialoge automatisch mit der jeweiligen Standardantwort beantwortet, zum Beispiel:
