REST im OPC Router: Struktur und Zuständigkeiten
Dieses Kapitel beschreibt die gemeinsame Begriffsgrundlage für die REST-Dokumentation im OPC Router. Sie zeigt, welche Aufgabe das jeweilige Plug-in sowie das jeweilige Trigger- oder Transferobjekt übernimmt und wann welches Element verwendet wird.
Der Schwerpunkt liegt auf der Zuordnung der OPC-Router-Elemente, nicht auf allgemeinen Rollen innerhalb eines RESTful Webservice.
Auf einen Blick
Im REST-Bereich des OPC Routers gibt es zwei technische Rollen:
- Der REST-Client ruft externe REST-Schnittstellen auf.
- Der REST-Server stellt eigene REST-Endpunkte bereit, die von externen Systemen aufgerufen werden können.
Für diese Rollen werden unterschiedliche Elemente verwendet:
| Ziel | Plug-in | Trigger- oder Transferobjekt in der Verbindung |
|---|---|---|
| Externe REST-Schnittstelle aufrufen | REST-Client-Plug-in | REST-Client-Transferobjekt |
| Eigenen REST-Endpunkt im OPC Router bereitstellen | REST-Server-Plug-in | REST-Trigger |
Zuständigkeiten der Elemente
| Element | Zuständigkeit |
|---|---|
| REST-Client-Plug-in | Stellt die Verbindung zu einer externen REST-Schnittstelle bereit. Hier werden zum Beispiel Host-URL, Authentifizierung, Zertifikate und OpenAPI-Datei konfiguriert. |
| REST-Client-Transferobjekt | Verwendet eine REST-Client-Anbindung innerhalb einer Verbindung, um einen konkreten REST-Aufruf auszuführen. |
| REST-Server-Plug-in | Stellt die technische Basis für eigene REST-Endpunkte im OPC Router bereit, zum Beispiel Port, Routen-Präfix, Authentifizierung und SSL. |
| REST-Trigger | Verwendet eine REST-Server-Anbindung innerhalb einer Verbindung, um einen konkreten Endpunkt bereitzustellen und bei einem Aufruf einen Transfer auszuführen. |
Unterschied zwischen Plug-in und Trigger- oder Transferobjekt
Die Plug-ins definieren die allgemeine technische Erreichbarkeit und Sicherheit. Trigger- und Transferobjekte innerhalb einer Verbindung definieren den konkreten Datenfluss.
Das bedeutet:
- Im Plug-in wird festgelegt, wo und wie eine REST-Schnittstelle erreichbar ist.
- Im Transferobjekt oder Trigger wird festgelegt, welcher Endpunkt genutzt wird und welche Daten übertragen werden.
Gemeinsame Begriffe
Endpunkt
Ein Endpunkt ist die konkrete Adresse einer REST-Funktion.
- Beim REST-Client ist das der Zielpfad einer externen Schnittstelle.
- Beim REST-Trigger ist das der Pfad, unter dem der OPC Router selbst eine Funktion bereitstellt.
HTTP-Methode
Die HTTP-Methode gibt an, welche Art von Aktion ein Aufruf auf einem Endpunkt auslöst. Gebräuchlich sind:
GET– Daten abrufenPOST– Daten senden oder einen Vorgang anstoßenPUT– Daten anlegen oder vollständig ersetzenDELETE– Daten löschen
Anfrageparameter
Anfrageparameter sind Werte, die mit einem REST-Aufruf gesendet werden. Dazu gehören zum Beispiel:
- URL-Segmente
- Query-Parameter
- Header-Felder
- Inhalte im Anfrageinhalt
Antwortparameter
Antwortparameter beschreiben die Daten, die aus einer REST-Antwort gelesen oder in einer REST-Antwort zurückgegeben werden.
- Beim REST-Client werden Antwortparameter aus der Antwort eines externen RESTful Webservice gelesen.
- Beim REST-Trigger werden Antwortparameter als Rückgabe an den aufrufenden Client gesendet.
Authentifizierung
Die Authentifizierung wird grundsätzlich im jeweiligen Plug-in konfiguriert.
- Beim REST-Client betrifft sie den Zugriff auf einen externen RESTful Webservice.
- Beim REST-Server betrifft sie den Zugriff externer Clients auf die vom OPC Router bereitgestellten Endpunkte.
OpenAPI
OpenAPI ist ein standardisiertes Format, das die Endpunkte und Parameter einer REST-Schnittstelle maschinenlesbar beschreibt (als JSON- oder YAML-Datei). Liegt eine solche Beschreibung vor, lassen sich Endpunkte und Parameter im OPC Router komfortabler übernehmen, statt sie manuell einzutragen.
Entscheidungshilfe
Verwenden Sie die folgenden Kombinationen:
- Für den Aufruf einer externen REST-Schnittstelle: REST-Client-Plug-in und REST-Client-Transferobjekt
- Für die Bereitstellung eines eigenen REST-Endpunkts im OPC Router: REST-Server-Plug-in und REST-Trigger