REST-Trigger
Der REST-Trigger stellt innerhalb eines Flows einen REST-Endpunkt bereit. Wenn ein externer Client diesen Endpunkt aufruft, wird der zugehörige Transfer ausgelöst.
Die Zuordnung zwischen REST-Server-Plug-in und Trigger ist im Kapitel REST im OPC Router: Struktur und Zuständigkeiten beschrieben.
Dialogübersicht
Der Dialog gliedert sich in die Reiter REST-Server und MCP Server. Auf dem Reiter REST-Server wählen Sie das REST-Server-Plug-in und konfigurieren Endpunkt, HTTP-Methode, Antwortformat sowie Anfrage- und Antwortparameter.
Konfiguration
| Eigenschaft | Beschreibung |
|---|---|
| Anbindung | Hier stehen alle im Bereich Plug-ins erstellten REST-Server-Plug-in-Instanzen zur Auswahl. Sollte das gewünschte REST-Server-Plug-in nicht dabei sein, können Sie es im Plug-ins-Bereich als REST-Server bereitstellen. |
| Endpunkt | Pfadanteil des Endpunkts hinter Host-Adresse, Port und gegebenenfalls Routen-Präfix des ausgewählten REST-Server-Plug-ins. |
| OpenAPI-Gruppierungsname | Name der Gruppe, unter der der Endpunkt in der OpenAPI-Beschreibung des REST-Server-Plug-ins zusammengefasst wird. |
| HTTP-Methode | HTTP-Methoden, die der Endpunkt unterstützen soll. |
| Antwortformat | Format, in dem die Antwort gesendet wird, zum Beispiel JSON. |
| Anfrageparameter | Parameter, die ein externer Client beim Aufruf des Endpunkts übergeben muss. Über die Spalte „Parametertyp“ legen Sie fest, wie der jeweilige Parameter übergeben wird. |
| Antwortparameter | Parameter, die als Antwort an den aufrufenden Client zurückgegeben werden. |
Typen der Anfrageparameter
Für jeden Anfrageparameter legen Sie über die Auswahlbox in der Spalte „Parametertyp“ fest, an welcher Stelle des Aufrufs der Parameter erwartet wird.
| Parametertyp | Beschreibung |
|---|---|
| HttpHeader | Der Parameter wird als HTTP-Header übergeben. |
| QueryString | Der Parameter wird als Query-String an die URL angehängt (?Name=Wert). |
| Url segment | Der Parameter ist Teil des URL-Pfads. |
Endpunktadresse
Wenn zum Beispiel im REST-Server-Plug-in die Adresse http://server:50117/api/ konfiguriert ist und im Trigger der Endpunkt GetData, ist der Aufruf unter http://server:50117/api/GetData erreichbar.
Wenn im REST-Server-Plug-in zusätzlich „API über Web-Management-Endpunkt bereitstellen“ aktiviert ist, wird zwischen Host-Adresse mit Port und dem Routen-Präfix der Pfadteil /services/{Plug-in-Name} eingefügt. Der Aufruf kann dann zum Beispiel http://server:8080/services/MyPlugin/api/GetData lauten.
Wird der OPC Router als Docker-Instanz betrieben, muss der im zugehörigen REST-Server-Plug-in konfigurierte Port zusätzlich im Container nach außen freigegeben werden, damit der Trigger-Endpunkt extern erreichbar ist. Das kann umgangen werden, wenn im REST-Server-Plug-in die Option „API über Web-Management-Endpunkt bereitstellen“ aktiviert ist und der Web-Management-Endpunkt erreichbar ist.
Konfiguration MCP-Tool
Auf dem Reiter MCP Server stellen Sie den REST-Trigger zusätzlich als MCP-Tool bereit. Ein vollständiges, durchgängiges Beispiel finden Sie unter Bereitstellung von Produktionsdaten über MCP.
Der Reiter MCP Server kann erst genutzt werden, wenn die MCP-Server-Funktion in der gewählten REST-Server-Plug-in-Instanz aktiviert wurde. Siehe Konfiguration MCP-Server.
| Eigenschaft | Beschreibung |
|---|---|
| MCP-Server aktivieren | Stellt den REST-Trigger als MCP-Tool bereit. |
| Name | Name des MCP-Tools. |
| Beschreibung | Beschreibung des MCP-Tools. |
| Eingabeschema | Schema für die Anfrage an das MCP-Tool. |
| Ausgabeformat | Legt fest, in welchem Format Daten zurückgegeben werden. Bei TextContentBlock wird ein unstrukturierter Text zurückgegeben. Bei StructuredContent kann ein Ausgabeschema definiert werden. |
| Ausgabeschema | Schema der Rückgabe für das MCP-Tool. Diese Eigenschaft ist nur relevant, wenn als Ausgabeformat StructuredContent verwendet wird. |
Die Dokumentation der verwendeten Schemata finden Sie auf modelcontextprotocol.com in der Schemareferenz.
Zusammenspiel mit dem aufrufenden Client
Wie diese Darstellung zu lesen ist, erklärt der Abschnitt Sequenzdiagramme.
Der REST-Trigger arbeitet request-response-synchron: Der aufrufende HTTP-Client wartet, bis der ausgelöste Transfer fertig ist. Einen Schalter „auf den Transfer warten“ gibt es hier nicht - gewartet wird immer. Beachten Sie dabei, dass der Antwortinhalt nicht im Trigger entsteht, sondern im Flow: Das mit dem Trigger unionierte, verdeckte Antwort-Transfer-Objekt schreibt während des Transfers den Antwort-Body (mehrere Verknüpfungen werden aneinandergehängt), den Statuscode und die Antwortparameter als HTTP-Header. Gesendet wird die Antwort danach genau einmal vom Trigger, nach dem Transferende. Ohne projektiertes Antwort-Transfer-Objekt bleibt der Antwort-Body leer, und es wird lediglich der Statuscode zurückgegeben.
REST-Trigger über HTTP: Antwort aus dem Flow
Das Hauptdiagramm zeigt, dass der HTTP-Client blockierend wartet und die Antwort erst nach dem Transferende hinausgeht. Der Inhalt der Antwort stammt aus dem Flow, gesendet wird er vom Trigger, und zwar genau einmal; danach läuft der wartende Anfrage-Thread aus. Die drei Sofortantworten 429, 503 und 408 sind davon getrennt: Bei 429 und 503 lief nie ein Transfer, bei 408 wurde er eingereiht und läuft möglicherweise weiter. Ist bei 408 die Option „Sende Fehler als Antwort“ ausgeschaltet, wird an dieser Stelle nichts gesendet, und die reguläre Antwort geht später verspätet hinaus.
Delta: derselbe Trigger als MCP-Tool
Das Delta-Diagramm zeigt nur die Unterschiede des MCP-Wegs. Der Anfrage-Body kommt aus den Argumenten des Werkzeugaufrufs statt aus dem HTTP-Body, und vom Antwort-Transfer-Objekt zählt allein der Antwort-Body. Geantwortet wird ebenfalls erst nach dem Transferende; früher festgelegt wird nur der Inhalt. Ohne gestarteten Transfer (volle Warteschlange, nicht bereite Verbindung) erhält der Aufrufer nichts.
Ablauf eines REST-Aufrufs: Der Antwortinhalt wird im Flow gebildet, gesendet wird er nach dem Transferende; die untere Bildhälfte zeigt denselben Trigger als MCP-Tool.