|
|
| (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]]
| |