Erstellen Sie Ihre eigenen Webservices
Cloud Abo
On-Premises
Vertec bietet die Möglichkeit, selbst von extern erreichbare Webservices bereitzustellen. Eingehende WebRequests werden dabei vom Python Code verarbeitet, wodurch flexible Integrationen und individuelle Schnittstellen realisiert werden können. Dazu gehören beispielsweise die Verarbeitung von Webhooks, die Anbindung externer Automatisierungsplattformen oder die Bereitstellung kundenspezifischer APIs. Vertec liefert mit dem Vertec REST API einen Webservice standardmässig aus.
Ein Webservice besteht aus zwei Teilen:
Unter Einstellungen > Berichte & Scripts > Scripts erstellen Sie ein neues Script.
Als Plattform wählen Sie Python 3 aus. Webservices sind nur mit Python 3 lauffähig.
Der Name des Scripts ist im Webservice Objekt Teil der Pythonklassenreferenz. Wählen Sie deshalb einen Namen ohne Leerschläge und Sonderzeichen.
Im Script Text tragen Sie den Python Code ein.
Das Basis-Modul für alle Python Webservices ist "vtcweb". Es enthält eine Routing-Logik, die bestimmt, welcher Webservice und welche Funktion den eingehenden Webrequest verarbeitet. Die Basisklasse für Webservices ist vtcweb.WebServices, und alle Python Webservices müssen von dieser Klasse erben:
from vtcweb import WebService class myService(WebService): ...
Damit eine Methode im Python Code via Webrequest erreicht werden kann, muss sie mit einem Decorator annotiert sein. Jeder Decorator entspricht einer bestimmten Art von Anfrage. Folgende Decorators können verwendet werden:
Zurückgegeben wird ein Response Objekt, welches einen Statuscode enthält sowie wahlweise einen Body und einen Content-Type. Mit der Methode self.as_json(content) wird der Content automatisch als JSON-String serialisiert und ein Response Objekt mit den entsprechenden Parametern zurückgegeben.
Detaillierte Informationen zum Python Code für Webservices finden Sie im Artikel Vertec Python Modul "vtcweb".
In folgendem Beispiel wird eine Aktivität erzeugt über den Methodennamen create_todo. Zurückgegeben wird die ID der neu erzeugten Aktivität.
from vtcweb import WebService, http, get, put, post, delete, WebException
class HelloWorld(WebService):
@post("create-todo")
def create_activity(self):
expected_values = {
"title": "str",
"text": "str",
"date": "datetime"
}
try:
values = self.parse_request_body(expected_values)
except ValueError as e:
raise WebException(400, str(e))
act = vtcapp.createobject("Activity")
act.title = values.title
act.text = values.text
act.createdBy = vtcapp.currentlogin()
if values.date:
act.dueDate = values.date
response = {}
response["id"] = act.objid
return self.as_json(response)Als nächstes erstellen Sie unter Einstellungen > Schnittstellen > Webservices einen Webservice.
Name (Subpath) |
Name des Webservices, welcher auch einen Teil der URL des Webservers ausmacht. |
Pythonklassenreferenz |
Die Bezeichnung des Scripteintrags und die zu verwendende Klasse. |
Aktiv |
Muss aktiviert sein. Nur wenn ein Webservice vorhanden und aktiv ist, können die WebRequests verarbeitet werden. |
Protokollieren |
Wenn diese Checkbox aktiv ist, dann werden die print und self.log Meldungen sowie Zeitangaben des Webservices in das Feld Anfrageprotokoll angezeigt. Dies hilft beim Einrichten und Austesten des Webservices. Für den Normalbetrieb kann die Checkbox deaktiviert werden. |
Mehrere Sessions erlauben |
Sofern diese Checkbox aktiviert wurde, kann analog zum Artikel XML-Server ein VertecSessionTag beim WebRequest Header hinzugefügt werden, um gezielt eigene Sessions zu erstellen. |
Letzter Zugriff |
Sofern ein gültiges API-Token und ein entsprechender Script-Eintrag zum Webservice vorhanden sind, wird in diesem Feld der aktuelle Zeitpunkt gespeichert. Dies erfolgt unabhängig davon, ob der Webservice aktiv oder gültig ist und unabhängig davon, ob der WebRequest erfolgreich war oder nicht. |
Anfrageprotokoll |
Sofern die Checkbox Protokollieren aktiv ist, werden nach jedem eingehenden WebRequest die print und self.log Meldungen sowie Zeitangaben angezeigt. |
Letzter Fehler |
In diesem Feld wird ein aufgetretener Fehler immer protokolliert und in der ersten Zeile der aktuelle Zeitpunkt des Auftretens gespeichert. Es werden Fehler gespeichert, deren Ursache nicht bereits durch den HTTP-Status eindeutig erklärt ist. Zum Beispiel wird der Fehler 404 Not Found nicht protokolliert. |
Logs löschen |
Die Logs werden automatisch bis zum nächsten Request mit aktuellen Einträgen überschrieben. Alternativ können die Einträge per Button Logs löschen auf der Detailseite oder im Aktionen Menü, die Felder Anfrageprotokoll und Letzter Fehler manuell geleert werden. |
Eine leere oder fehlerhafte Pythonklassenreferenz führt dazu, dass der Eintrag als ungültig angezeigt wird und beim Versuch, den Webservice anzusprechen, wird der Status 404 NOT Found zurückgegeben. Wenn zuvor das Feld Protokollieren aktiviert wurde, erscheint ein Hinweis unter Anfrageprotokoll bei invalidem Webservice:
Um das Erstellen bzw. Ausführen der Webservices zu ermöglichen oder zu sperren, stehen zwei Möglichkeiten zur Verfügung:
Für die Benutzergruppen Administratoren und Standardbenutzer wird die Berechtigung standardmässig zugewiesen.
Webservices laufen immer über die Anmeldung eines Benutzers. Damit Vertec einen Benutzer bestimmen und prüfen kann, ob der Benutzer den Webservice ausführen darf, ist eine Authentisierung notwendig. Für die Webservices erfolgt das über ein API-Token, welches in Vertec generiert werden kann. Das API-Token kann entweder als Header oder via Query übergeben werden.
Der Webservice prüft die Identität über ein Bearer-Token.
Dieses wird im HTTP-Header unter Authorization: Bearer <apiToken> übermittelt.
Die Query muss einen Key mit dem API Token als Wert haben und in der URL ergänzt werden: ?apiToken=<apiToken>.
Beispiel: http://<host>/api/webservice/<Name (Subpath)>/<method-name>?apiToken=<apiToken>
Diese Art der Authentisierung ist nützlich, wenn keine Möglichkeit besteht, einen Header für den WebRequest zu definieren. Beispielsweise, wenn Sie einen Webservice verwenden, um auf Webhooks zu reagieren.
Nach der Authentisierung wird geprüft, ob der Benutzer den Webservice ausführen darf. Ist dies der Fall, wird eine Session bereitgestellt und der Python Code mit den Berechtigungen dieses Benutzers ausgeführt.
Wenn das API-Token ungültig ist oder es keinem aktiven Benutzer zugeordnet werden kann, gibt der Webservice die Fehlermeldung Status 403 Forbidden zurück.
Wenn der Benutzer keine Berechtigung hat, den Webservice auszuführen, wird die Fehlermeldung Status 401 Unauthorized zurückgegeben.
Mit dem Parameter Web Services Server in der [CloudServer] Section im Vertec.ini - File können Webservices deaktiviert werden. Ist der Parameter nicht angegeben, sind Webservices aktiviert.
[CloudServer] Web Services Server=False
In der Konfigurationsdatei Vertec.ini kann in der [Log] Section folgender Parameter gesetzt werden:
[Log] DebugCategories=Vertec.Webservices
Dann werden die vom Webservice mit der Methode self.log(log_object) geloggten Objekte ins Session Log geschrieben.
Für Webservice Sessions wird ein Timeout über die Vertec.ini Datei unter [CloudServer] mit dem Parameter Webservice Session Timeout (Standard: 10 Minuten) konfiguriert. Erhält eine Webservice Session während der definierten Zeit keinen Request, sendet der Cloud Server einen Befehl, die Session zu schliessen. Die Session prüft selbst, ob sie beendet werden kann, und bleibt offen, wenn aktiv WebRequests verarbeitet werden.
Beim Erstellen eines Webservice ist zu beachten, dass für die Verarbeitung der WebRequests eine eigene Session erzeugt wird. Änderungen des Webservice-Codes gelangen per Notif von der Session des Entwicklers in die des Webservices. Ebenso werden die Felder Letzter Zugriff, Anfrageprotokoll und Letzter Fehler in der Webservice-Session geschrieben und gelangen per Notif wieder zurück in die Session des Entwicklers. Hierbei kann es hilfreich sein, das PollIntervall zu reduzieren, um schneller eine Rückmeldung zu erhalten. Beachten Sie dazu den KB Artikel Notif Datenaktualisierung.