Zum Inhalt springen

OBS/Kostenpflichtige Module/REST-Server/Endpunkte: Unterschied zwischen den Versionen

Aus OBS Wiki
MINERVA-Rademacker (Diskussion | Beiträge)
K MINERVA-Rademacker verschob die Seite OBS/Kostenpflichtige Module/RESTServer/Endpunkte nach OBS/Kostenpflichtige Module/REST-Server/Endpunkte: Titel an Überschrift angeglichen (REST-Server, Umlaute, sprechende Beispieltitel)
MINERVA-Rademacker (Diskussion | Beiträge)
Weiterleitung auf Pflege#Endpunkt, Inhalt in die Seite Pflege übernommen [Volltext ersetzt]
Markierung: Neue Weiterleitung
 
(Eine dazwischenliegende Version desselben Benutzers wird nicht angezeigt)
Zeile 1: Zeile 1:
{{Vorlage:Kostenpflichtige Module}}
#WEITERLEITUNG [[OBS/Kostenpflichtige Module/REST-Server/Pflege#Endpunkt]]
{{Seitentyp|Maske}}
= Endpunkte =
 
Ein Endpunkt stellt eine Adresse bereit, über die der REST-Server eine Funktion anbietet. Hinter jedem Endpunkt steht ein OBS-Skript oder ein WebHook. So veröffentlichen Sie genau die Daten und Vorgänge, die eine Anwendung braucht, und vergeben die Rechte je Adresse. Sie erreichen die Endpunkte über '''Stammdaten → Z Weitere Stammdaten → REST-Server → Endpunkte'''.
 
== Liste ==
Die Liste zeigt alle Endpunkte mit '''Pfad''' (dem Pfad-Template) und '''Serv''' (der Nummer des Server-Profils). Aktive Endpunkte erscheinen fett.
 
== Tasten und Schaltflächen ==
{| class="wikitable"
! Taste !! Funktion
|-
| {{Einfg}} || Legt einen neuen Endpunkt an.
|-
| {{Return}} || Öffnet den markierten Endpunkt in der Eingabemaske.
|-
| {{F4}} || Wählt die Sortierung.
|-
| {{F6}} || Schaltfläche '''F6 Zugang''': öffnet die Liste der Zugänge, die diesen Endpunkt nutzen dürfen, siehe [[#Zugriffskontrolle|Zugriffskontrolle]].
|-
| {{F7}} || Schaltfläche '''F7 Script''': öffnet das Skript des Endpunkts im Skript-Editor. Wie Sie es schreiben, beschreibt [[OBS/Kostenpflichtige Module/RESTServer/Scripting|Scripting]].
|-
| {{F8}} || Schaltfläche '''F8 Stat''': zeigt die Statistik der Anfragen an diesen Endpunkt.
|}
 
== Eingabemaske ==
{{Return}} öffnet die Eingabemaske '''REST-Endpunkt'''. Ein neuer Endpunkt ist als '''Aktiv''' vorbelegt.
 
{| class="wikitable"
! Feld !! Bedeutung
|-
| '''Pfad-Template''' || Vollständiger Pfad nach Host und Port, mit Platzhaltern, z.B. <code>/orders/{uid}/modules/{code}</code>. Maßgeblich für die Zuordnung der Anfragen, siehe [[#Routing über Pfad-Templates|Routing über Pfad-Templates]]. Pflichtfeld.
|-
| '''Server''' || Server-Profil, auf dem der Endpunkt erreichbar ist. Auf anderen Profilen antwortet der Server für diesen Pfad mit '''404'''. Pflichtfeld.
|-
| '''zusätzliche Infos''' || Freitext zur Dokumentation. Wird nicht ausgewertet.
|-
| '''Datei-Upload''' || Der Endpunkt nimmt Dateien an. Ohne Haken weist der Server Uploads mit '''415''' ab, das Skript läuft dann nicht.
|-
| '''maximale Dateigröße (MB)''' || Obergrenze für Uploads in MB. Leer oder ''0'' bedeutet 25 MB. Darüber antwortet der Server mit '''413'''.
|-
| '''Aktiv''' || Nur aktive Endpunkte sind erreichbar. Ein inaktiver Endpunkt antwortet mit '''404'''.
|}
 
Das Skript des Endpunkts bearbeiten Sie in der Liste mit {{F7}}.
 
== Routing über Pfad-Templates ==
Der Server ordnet jede Anfrage über das '''Pfad-Template''' einem Endpunkt zu:
* '''Statische Segmente''' müssen übereinstimmen. Groß- und Kleinschreibung spielt keine Rolle.
* '''Platzhalter''' in geschweiften Klammern, z.B. <code>{uid}</code>, passen auf jeden Wert. Der Wert steht dem Skript als Pfad-Parameter zur Verfügung.
* '''Die Zahl der Segmente''' muss gleich sein. <code>/orders</code> passt nicht auf <code>/orders/{uid}</code>.
 
{| class="wikitable"
! Template !! Passt auf !! Pfad-Parameter
|-
| <code>/orders</code> || <code>/orders</code> || –
|-
| <code>/orders/{uid}</code> || <code>/orders/4711</code> || <code>uid = 4711</code>
|-
| <code>/orders/{uid}/modules/{code}</code> || <code>/orders/4711/modules/A1</code> || <code>uid = 4711</code>, <code>code = A1</code>
|-
| <code>/kalender/v1</code> || <code>/kalender/v1</code> || –
|}
 
Passen mehrere Templates, gewinnt das spezifischste, also das mit den meisten statischen Segmenten. So schlägt <code>/orders/summary</code> das Template <code>/orders/{uid}</code>, während <code>/orders/4711</code> auf <code>/orders/{uid}</code> passt. Haben zwei Templates gleich viele statische Segmente, ist nicht festgelegt, welches gewinnt. Vermeiden Sie solche Überschneidungen.
 
Passt kein Template, antwortet der Server mit '''404''' <code>NOT_FOUND</code>. Weitere Regeln, z.B. zu Schrägstrichen und Query-Parametern, beschreibt [[OBS/Kostenpflichtige Module/RESTServer/HTTP-Schnittstelle#Adressierung|HTTP-Schnittstelle]].
 
=== Pfad-Parameter im Skript ===
Das Skript liest die Werte der Platzhalter über <code>oReader.Path</code>:
 
<syntaxhighlight lang="delphi">
procedure Get(oReader: TxRestReader; oWriter: TxRestWriter);
var cUid: string;
begin
    cUid := oReader.Path('uid');  // aus /orders/{uid}
end;
</syntaxhighlight>
 
Der Name des Parameters ist geschützt: Query-Parameter oder Header können ihn nicht überschreiben. Der Wert kommt aber aus der Adresse, die der Client sendet. Prüfen Sie ihn im Skript wie jede andere Eingabe. Details: [[OBS/Kostenpflichtige Module/RESTServer/Scripting|Scripting]].
 
=== URL-Struktur ===
<syntaxhighlight lang="text">
https://<Host>[:<Port>]<Pfad-Template>
</syntaxhighlight>
 
Beispiele:
* <code>https://obs.example.com/orders</code>
* <code>https://obs.example.com/orders/4711</code>
* <code>https://obs.example.com/orders/4711/modules/A1</code>
 
== HTTP-Methode ==
Der Server ruft im Skript die Methode auf, die zum HTTP-Verb passt: <code>Get</code>, <code>Post</code>, <code>Put</code>, <code>Patch</code> oder <code>Delete</code>. Fehlt die Methode im Skript, antwortet er mit '''405''' und nennt im Header <code>Allow</code> die vorhandenen.
 
Ein Template entspricht damit einem Skript. Unterschiedliche Pfad-Formen wie <code>/orders</code> und <code>/orders/{uid}</code> sind eigene Endpunkte mit eigenem Skript und eigener Berechtigung.
 
Schreibende Aufrufe (<code>POST</code>, <code>PUT</code>, <code>PATCH</code>, <code>DELETE</code>) schützt der Server selbst gegen doppelte Ausführung. Der Client sendet dafür den Header <code>Idempotency-Key</code>, am Endpunkt ist nichts einzustellen. Details: [[OBS/Kostenpflichtige Module/RESTServer/HTTP-Schnittstelle#Idempotenz|HTTP-Schnittstelle]].
 
== Versionierung ==
Die Version eines Endpunkts nehmen Sie als statisches Segment ins Template auf, z.B. <code>/orders/v1</code> oder <code>/v1/orders/{uid}</code>. Eine Änderung ohne Bruch für bestehende Clients:
# Lassen Sie den bestehenden Endpunkt unverändert.
# Legen Sie einen neuen Endpunkt mit neuem Versions-Segment an.
# Vergeben Sie die Berechtigungen für die Clients, die umstellen.
# Deaktivieren Sie den alten Endpunkt, wenn alle Clients umgestellt sind.
 
== Zugriffskontrolle ==
Ein Zugang darf einen Endpunkt nur nutzen, wenn er dafür berechtigt ist. Die Berechtigungen stehen in der Tabelle <code>RESTSRV_ACCESS</code>.
 
So vergeben Sie eine Berechtigung:
# Markieren Sie den Endpunkt in der Liste und drücken Sie {{F6}}. Die Liste '''Endpunkt Zugang''' zeigt die berechtigten Zugänge.
# Drücken Sie {{Einfg}}. Die Liste der Zugänge öffnet sich zur Auswahl.
# Markieren Sie die gewünschten Zugänge mit {{F5}} und übernehmen Sie sie mit {{F2}}.
 
{{Achtung|Ein Endpunkt ohne Berechtigung sieht fertig aus: Pfad, Skript und Server-Profil stimmen, der Aufruf scheitert trotzdem mit '''403''' <code>FORBIDDEN_ROLE</code> und der Meldung „Zugriff verweigert“. Im Protokoll steht „Keine Berechtigung fuer die Endpunkt-Nutzung“. Vergeben Sie deshalb beim Anlegen immer auch die Berechtigung, und prüfen Sie bei einem '''403''' zuerst, ob sie existiert.}}
 
Weil jede Pfad-Form ein eigener Endpunkt ist, vergeben Sie die Rechte je Pfad-Form. So erlauben Sie z.B. das Lesen von <code>/orders/{uid}</code>, aber nicht das Ändern über <code>/orders/{uid}/modules/{code}</code>.
 
== Dateien ==
* '''Upload:''' Mit '''Datei-Upload''' nimmt der Endpunkt Dateien an, bis zur '''maximalen Dateigröße (MB)'''. Übertragungsarten, Header und Statuscodes beschreibt [[OBS/Kostenpflichtige Module/RESTServer/Datei-Upload|Datei-Upload]].
* '''Download:''' Jeder Endpunkt kann statt JSON eine Datei liefern, ohne Einstellung am Endpunkt. Das Skript erzeugt die Datei-Antwort, siehe [[OBS/Kostenpflichtige Module/RESTServer/Datei-Download|Datei-Download]].
 
== Caching ==
Der Server hält die Endpunkte eines Server-Profils samt Skript 60 Sekunden im Speicher. Neue oder geänderte Endpunkte, Templates und Skripte wirken deshalb spätestens nach 60 Sekunden. Nach einem Neustart des REST-Dienstes wirken sie sofort.
 
== WebHooks ==
Ein WebHook ist ein Endpunkt für einen einmaligen Rückruf. Typischer Einsatz: OBS stößt einen Vorgang bei einem Fremdsystem an, z.B. einem Bezahldienst oder Versanddienstleister, und gibt ihm eine Rückruf-Adresse mit, die nur einmal gilt. Die Adresse lässt sich danach nicht erneut oder von anderen benutzen.
 
Ablauf:
# OBS legt einen Eintrag in der Tabelle <code>REMOTE_HOOK_URL</code> an und dazu einen Endpunkt, der auf diesen Eintrag verweist. Ein Skript hat dieser Endpunkt nicht.
# Die Adresse dieses Endpunkts erhält das Fremdsystem als Rückruf-Adresse.
# Das Fremdsystem ruft die Adresse auf. Der Server speichert den empfangenen Inhalt in <code>REMOTE_HOOK_URL.hu_response</code>, antwortet mit <code>{"status": "ok"}</code> und löscht den Endpunkt.
# Der weiterverarbeitende OBS-Vorgang liest die Rückmeldung aus <code>hu_response</code>.
 
Für den Aufruf gilt:
* Wie bei jedem Endpunkt prüft der Server API-Key und Berechtigung des Zugangs.
* Ein <code>Idempotency-Key</code> ist nicht nötig.
* Ein zweiter Aufruf derselben Adresse erhält sofort '''404'''. Das ist gewollt: Ein WebHook ist keine dauerhafte Schnittstelle. Für eine dauerhafte Rückmelde-Adresse legen Sie einen normalen Endpunkt mit Skript an.
* Fehlt der Eintrag in <code>REMOTE_HOOK_URL</code>, antwortet der Server mit '''500'''.
 
== Siehe auch ==
* [[OBS/Kostenpflichtige Module/RESTServer/Scripting|Scripting]]
* [[OBS/Kostenpflichtige Module/RESTServer/Zugaenge|Zugänge]]
* [[OBS/Kostenpflichtige Module/RESTServer/HTTP-Schnittstelle|HTTP-Schnittstelle]]
* [[OBS/Kostenpflichtige Module/RESTServer/Datei-Upload|Datei-Upload]]
* [[OBS/Kostenpflichtige Module/RESTServer/Datei-Download|Datei-Download]]
* [[OBS/Kostenpflichtige Module/RESTServer/Einrichtung|Einrichtung]]

Aktuelle Version vom 17. November 2026, 11:53 Uhr