Custom Webservices

Vertec bietet die Möglichkeit, extern erreichbare Webservices bereitzustellen, deren Logik in Python 3.12 implementiert ist. 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.

Voraussetzung

In der Konfigurationsdatei Vertec.ini werden folgende Parameter ergänzt:
[Cloud Server]
Web Services Server=True
DebugCategories=Vertec.Webservices

Hinweis: DebugCategories=Vertec.Webservices wird bei der Methode self.log(log_object) gesetzt. Beachten Sie dazu die Informationen zur Methode und zum Log.

Hinweis zum [Notif]:

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, den PollIntervall darin zu reduzieren, um schneller Rückmeldung zu erhalten. Beachten Sie dazu den KB Artikel Notif Datenaktualisierung.

Session Handling

Für Webservice-Sessions wird ein Timeout über die Vertec.ini Datei unter [Cloud Server] mit folgendem 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.

Scripteintrag für Webservice erstellen

Unter Einstellungen > Berichte & Scripts > Scripteintrag erstellen Sie einen neuen Scripteintrag. Geben Sie die Bezeichnung ein und wählen unter Plattform Python 3 aus. Webservices sind nur mit Python 3 lauffähig.

Im Script Text tragen Sie den Python Code ein. Hier ein Beispielcode:

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)

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.

Damit eine Methode via Webrequest erreicht werden kann, muss sie mit sogenannten Decorator annotiert sein. Jeder Decorator entspricht einer bestimmten Art von Anfrage. Folgende Decorator können verwendet werden:

• GET: bestehende Daten abrufen
• POST: neue Daten erstellen
• PUT: bestehende Daten aktualisieren
• DELETE: die Daten löschen
• HTTP: erlaubt den Zugriff auf alle obigen Anfragearten (GET, POST, PUT & DELETE)

Die dafür notwendigen Definitionen und Methoden zum Beispielcode sind im Vertec Python Modul "vtcweb" implementiert.

Objekt Webservice erstellen

Als nächstes erstellen Sie unter Einstellungen > Schnittstellen > Webservices einen Webservice.

Bedingungen für einwandfreies Ansprechen

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:

Berechtigung Webservices ausführen

Um das Erstellen bzw. Ausführen der Webservices zu ermöglichen respektive zu sperren, kann dazu die Berechtigung den entsprechenden Benutzergruppen erlaubt respektive verweigert werden. Für die Benutzergruppen Administratoren und Standardbenutzer wird die Berechtigung standardmässig zugewiesen.

WebRequest abschicken

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 im Vertec generiert werden kann. Das API-Token kann entweder als Header oder via Query übergeben werden.

Authentisierung via Header

Der Webservice prüft die Identität über ein Bearer-Token.
Dieses wird im HTTP-Header unter Authorization: Bearer <apiToken> übermittelt.

Authentisierung via Query

Das 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.

Fehlermeldungen

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 403 Forbidden zurückgegeben.