OBS/Kostenpflichtige Module/REST-Server/Scripting: Unterschied zwischen den Versionen
Keine Bearbeitungszusammenfassung |
Links auf die neuen Titel (REST-Server, Zugänge, Beispiele) umgestellt, zitierte Meldungen mit Umlauten wie im Programm [Volltext ersetzt] |
||
| (17 dazwischenliegende Versionen von 2 Benutzern werden nicht angezeigt) | |||
| Zeile 1: | Zeile 1: | ||
{{Kostenpflichtige Module}} | {{Vorlage:Kostenpflichtige Module}} | ||
{{Seitentyp|Referenz}} | |||
= Scripting = | |||
Hinter jedem Endpunkt steht ein Skript, das Sie selbst schreiben. Damit bestimmen Sie, welche OBS-Daten ein Endpunkt liest oder ändert und was der Client zurückbekommt. Authentifizierung, Fehlerformat, Idempotenz und Transaktion übernimmt der Server. Diese Seite beschreibt die Skript-Schnittstelle: Anfrage lesen, Antwort schreiben, Fehler melden, gemeinsamen Code nutzen. | |||
Das Skript ist in Object Pascal geschrieben und nutzt die OBS-Funktionen für Datenbank und Hilfsfunktionen. Wie ein Client den Server aufruft, steht unter [[OBS/Kostenpflichtige Module/REST-Server/HTTP-Schnittstelle|HTTP-Schnittstelle]]. | |||
== | == Aufruf == | ||
Je HTTP-Methode enthält das Skript eine gleichnamige '''Prozedur'''. Der Server ruft die Prozedur auf, die zur Methode der Anfrage passt: | |||
<syntaxhighlight lang="delphi"> | |||
procedure Get (oReader: TxRestReader; oWriter: TxRestWriter); | |||
procedure Post (oReader: TxRestReader; oWriter: TxRestWriter); | |||
procedure Put (oReader: TxRestReader; oWriter: TxRestWriter); | |||
procedure Patch (oReader: TxRestReader; oWriter: TxRestWriter); | |||
procedure Delete(oReader: TxRestReader; oWriter: TxRestWriter); | |||
</syntaxhighlight> | |||
Ein Skript enthält nur die Methoden, die der Endpunkt anbietet. Fehlt die Methode zur Anfrage, antwortet der Server mit '''405''' <code>METHOD_NOT_ALLOWED</code>. Der Header <code>Allow</code> nennt die Methoden, die das Skript tatsächlich enthält: | |||
<syntaxhighlight lang="text"> | |||
HTTP/1.1 405 Method Not Allowed | |||
Allow: GET, PUT | |||
</syntaxhighlight> | |||
Lässt sich das Skript nicht übersetzen, antwortet der Server mit '''500'''. Die Meldung des Übersetzers mit Grund und Zeile steht im Protokoll. | |||
== Parameter == | |||
{| class="wikitable" | |||
! Parameter !! Typ !! Pflicht !! Standard !! Bedeutung | |||
|- | |||
| <code>oReader</code> || <code>TxRestReader</code> || ✓ || – || Die Anfrage: Query, Header, Pfadwerte, Formularfelder, Token-Werte, Körper und hochgeladene Datei. Siehe [[#Die Anfrage lesen: oReader|oReader]]. | |||
|- | |||
| <code>oWriter</code> || <code>TxRestWriter</code> || ✓ || – || Die Antwort: Felder, Statuscode, Header, Fehler oder Datei. Siehe [[#Die Antwort schreiben: oWriter|oWriter]]. | |||
|} | |||
Beide Objekte erzeugt und besitzt der Server. Im Skript wird nichts angelegt und nichts freigegeben. Die Datenbankverbindung steht im Skript global als <code>oDB</code> bereit. | |||
== Sicherheitshinweise == | |||
{{Achtung|Endpunkt-Skripte verarbeiten Daten aus dem Internet. Bauen Sie Werte des Clients nie ungeprüft in SQL ein. Setzen Sie jeden Wert über <code>DB_SQLVal</code> ein und prüfen Sie Eingaben gegen erlaubte Werte.}} | |||
* Prüfen Sie Pflichtfelder, Typen und Wertebereiche. | |||
* Geben Sie nur zurück, was der Client braucht: keine internen Kennungen, keine Systemfelder, keine Passwörter. | |||
* Lesen Sie Mandant und Rollen aus dem Token, nie aus Körper oder Query. | |||
* Schreiben Sie keine internen Details in Fehlermeldungen. Die <code>message</code> geht an den Client. | |||
== Die Anfrage lesen: oReader == | |||
<code>oReader</code> ist der einzige Zugang zur Anfrage. Alle Werte sind Zeichenketten oder werden über einen typisierten Leser geholt. | |||
{| class="wikitable" | |||
! Aufruf !! Liefert | |||
|- | |||
| <code>oReader.Param('kundennr')</code> || Query-Parameter, Formularwert (<code>application/x-www-form-urlencoded</code>) oder HTTP-Header. Getrimmt, leer wenn nicht gesendet. | |||
|- | |||
| <code>oReader.Path('nr')</code> || Wert eines Platzhalters aus dem '''Pfad-Template''' | |||
|- | |||
| <code>oReader.Form('bemerkung')</code> || Formularfeld einer <code>multipart/form-data</code>-Übertragung | |||
|- | |||
| <code>oReader.Subject()</code> || Subject (<code>sub</code>) des vorgelegten Tokens | |||
|- | |||
| <code>oReader.Claim('tenant')</code> || Eigener Claim des vorgelegten Tokens, als Text | |||
|- | |||
| <code>oReader.TraceId()</code> || Kennung der Anfrage, gleich dem Header <code>X-Trace-Id</code> der Antwort | |||
|- | |||
| <code>oReader.Offset()</code> || UTC-Offset des Servers, z.B. ''+01:00'' | |||
|- | |||
| <code>oReader.HasBody()</code> || Wurde ein JSON-Körper gesendet? | |||
|- | |||
| <code>oReader.UploadPath()</code>, <code>UploadName()</code>, <code>UploadType()</code>, <code>UploadSha()</code> || Hochgeladene Datei, siehe [[#Datei-Uploads|Datei-Uploads]] | |||
|} | |||
Was der Server vorher filtert: | |||
* Die Header <code>authorization</code>, <code>cookie</code>, <code>proxy-authorization</code>, <code>x-forwarded-for</code>, <code>x-real-ip</code>, <code>apikey</code> und <code>api_key</code> erreichen das Skript nicht. | |||
* Namen, die mit <code>_OBS_</code> beginnen, sind dem Server vorbehalten. Header und Query-Parameter mit solchen Namen verwirft er. | |||
* Werte aus Header, Query, Pfad und Formular kürzt er nach 1024 Zeichen. | |||
* Null-Bytes und Steuerzeichen entfernt er. Tabulator, CR und LF bleiben. | |||
<syntaxhighlight lang="delphi"> | |||
cKundenNr := oReader.Param('kundennr'); | |||
if (not Empty(cKundenNr)) then begin | |||
// ... | |||
end; | |||
</syntaxhighlight> | |||
== | === Der Körper === | ||
Den JSON-Körper liest <code>oReader</code> über '''Pfade'''. Es gibt keine Unterobjekte, keine Typumwandlung und nichts freizugeben. | |||
= | {| class="wikitable" | ||
! Aufruf !! Bedeutung | |||
|- | |||
| <code>oReader.Str('betreff', cWert)</code> || Liest den Wert. '''Rückgabe Boolean''': War das Feld da? Fehlt es, bleibt die Variable unverändert. | |||
|- | |||
| <code>oReader.Int('menge', nWert)</code> || dito, Ganzzahl | |||
|- | |||
| <code>oReader.Num('preis', nWert)</code> || dito, Kommazahl. Den Dezimalpunkt aus JSON liest der Reader richtig. | |||
|- | |||
| <code>oReader.Bool('aktiv', lWert)</code> || dito, Boolean | |||
|- | |||
| <code>oReader.NumDef('rabatt', nWert, 0)</code> || wie <code>Num</code>, mit Vorgabewert | |||
|- | |||
| <code>oReader.Has('feld')</code> || Ist das Feld vorhanden, auch mit <code>null</code>? | |||
|- | |||
| <code>oReader.Count('zeiten')</code> || Anzahl Einträge einer Liste, 0 wenn keine Liste | |||
|- | |||
| <code>oReader.IsArr('zeiten')</code>, <code>oReader.IsObj('zeiten[0]')</code> || Ist der Wert eine Liste bzw. ein Objekt? | |||
|- | |||
| <code>oReader.Keys()</code> || Alle Feldnamen der obersten Ebene, in Kommas eingefasst | |||
|} | |||
Verschachtelung steht im Pfad: Punkt für Felder, eckige Klammern für Listen. | |||
<syntaxhighlight lang="delphi"> | |||
procedure Put(oReader: TxRestReader; oWriter: TxRestWriter); | |||
var cVon: string; | |||
nAnz: Integer; | |||
nI : Integer; | |||
begin | |||
nAnz := oReader.Count('zeiten'); | |||
for nI := 0 to nAnz - 1 do begin | |||
if (oReader.Str('zeiten[' + IntToStr(nI) + '].von', cVon)) then begin | |||
// ... cVon verarbeiten ... | |||
end; | |||
end; | |||
end; | |||
</syntaxhighlight> | |||
{{Hinweis|Der Rückgabewert unterscheidet „nicht gesendet“ von „leer gesendet“. Bei <code>"feld": null</code> liefert <code>oReader.Str('feld', cWert)</code> ''true'' und einen leeren Wert, bei fehlendem Feld ''false''. So unterscheidet ein PATCH „Feld leeren“ von „Feld nicht ändern“.}} | |||
Regeln für den Körper: | |||
* Der Server liest den Körper als UTF-8. | |||
* Nur ein JSON-'''Objekt''' als Wurzel gilt als Körper. Eine Liste als Wurzel oder ungültiges JSON ergibt keinen Körper: <code>HasBody()</code> ist ''false'', jeder Leser liefert ''false''. Der Server antwortet in diesem Fall nicht mit 400. Prüfen Sie Pflichtfelder deshalb im Skript. | |||
* Ein Körper ohne Datei darf höchstens 10 MB groß sein, auch nach dem Entpacken. Darüber antwortet der Server mit '''413''', das Skript läuft nicht. Gepackte Körper: [[OBS/Kostenpflichtige Module/REST-Server/HTTP-Schnittstelle#Kompression|HTTP-Schnittstelle]]. | |||
=== Werte des Servers === | |||
Diese Werte setzt der Server. Ein Client kann sie nicht überschreiben. | |||
= | {| class="wikitable" | ||
! Aufruf !! Inhalt | |||
|- | |||
| <code>oReader.Param('_OBS_SERVER_TIME')</code> || Serverzeit nach ISO 8601 mit UTC-Offset, z.B. ''2026-11-17T09:12:33+01:00'' | |||
|- | |||
| <code>oReader.Offset()</code> || Nur der Offset daraus, z.B. ''+01:00''. Er geht in die [[#Zeitangaben|Zeitfunktionen]]. | |||
|- | |||
| <code>oReader.TraceId()</code> || Kennung der Anfrage | |||
|- | |||
| <code>oReader.Param('_OBS_JWT_EXP_SEC')</code> || Laufzeit des Access-Tokens in Sekunden ('''Lebenszeit (Min)''' × 60) | |||
|} | |||
Bei Zugängen mit '''JWT-Authentifizierung''' stehen zusätzlich die Werte des Tokens bereit: <code>oReader.Subject()</code>, <code>oReader.Claim('<name>')</code>, <code>oReader.Param('_OBS_JWT_ID')</code>, <code>oReader.Param('_OBS_JWT_AUDIENCE')</code> sowie die Sitzungskennungen <code>sid</code> und <code>rid</code>. Die vollständige Liste steht unter [[OBS/Kostenpflichtige Module/REST-Server/Anmeldung mit JWT#Claims im Endpunkt lesen|Anmeldung mit JWT]]. | |||
=== Pfad-Parameter === | |||
Enthält das '''Pfad-Template''' Platzhalter, liefert <code>oReader.Path</code> deren Werte: | |||
{| class="wikitable" | |||
! Pfad-Template !! Zugriff im Skript | |||
|- | |||
| <code>/beispiel/auftraege/{nr}</code> || <code>oReader.Path('nr')</code> | |||
|- | |||
| <code>/beispiel/auftraege/{nr}/module/{code}</code> || <code>oReader.Path('nr')</code>, <code>oReader.Path('code')</code> | |||
|} | |||
Der '''Name''' ist geschützt: Ein Client kann einen Pfadwert nicht über Query oder Header unterschieben. Der '''Wert''' stammt aber aus der URL des Clients. Prüfen Sie ihn wie jede andere Eingabe, z.B. ob der Auftrag zum Mandanten im Token gehört. Ein vollständiges Beispiel zeigt [[OBS/Kostenpflichtige Module/REST-Server/Beispiele/Pfad-Parameter|Beispiel 4]]. | |||
=== Datei-Uploads === | |||
Hat der Endpunkt den Haken '''Datei-Upload''', nimmt der Server Dateien entgegen und legt sie in einem temporären Verzeichnis ab. Das Skript erhält die Datei über diese Aufrufe: | |||
{| class="wikitable" | {| class="wikitable" | ||
! | ! Aufruf !! Inhalt | ||
|- | |- | ||
| | | <code>oReader.UploadPath()</code> || Vollständiger Pfad der temporären Datei auf dem Server | ||
|- | |- | ||
| | | <code>oReader.UploadName()</code> || Originaler Dateiname | ||
|- | |- | ||
| | | <code>oReader.UploadType()</code> || Content-Type der Datei, kleingeschrieben. Ohne Angabe des Clients <code>application/octet-stream</code>. | ||
|- | |||
| <code>oReader.UploadSha()</code> || SHA-256 der gespeicherten Datei, hexadezimal in Kleinbuchstaben. Vergleichen Sie damit eine Prüfsumme, die der Client mitsendet. | |||
|} | |} | ||
* Beide Übertragungswege liefern dieselben Werte: <code>multipart/form-data</code> und der fortsetzbare Upload mit <code>Content-Range</code>. Beim fortsetzbaren Upload läuft das Skript erst, wenn die Datei vollständig ist. | |||
* Ohne Dateinamen weist der Server den Upload mit '''400''' ab, das Skript läuft nicht. <code>UploadPath()</code> und <code>UploadName()</code> sind im Skript also immer gefüllt. | |||
* Ein Upload-Körper wird nicht als JSON gelesen. <code>HasBody()</code> ist ''false''. | |||
* Zusatzangaben eines Formulars liest das Skript mit <code>oReader.Form('<name>')</code>. Das sind die Partien ohne <code>filename=</code>. Vom Namen bleiben nur Buchstaben, Ziffern und Unterstrich, höchstens 40 Zeichen. | |||
* Beim fortsetzbaren Upload gibt es keine Formularfelder. Zusatzangaben kommen dort über Query-Parameter oder Header. | |||
* Ein Upload an einen Endpunkt ohne '''Datei-Upload''' beantwortet der Server mit '''415'''. Überschreitet die Übertragung die '''maximale Dateigröße (MB)''' des Endpunkts, antwortet er mit '''413'''. | |||
{{Hinweis|Der Server verschiebt die temporäre Datei nicht. Das Skript übernimmt sie an ihren Zielort.}} | |||
Übertragung, Header und Statuscodes: [[OBS/Kostenpflichtige Module/REST-Server/Datei-Upload|Datei-Upload]]. Ein vollständiges Beispiel zeigt [[OBS/Kostenpflichtige Module/REST-Server/Beispiele/Datei-Upload und Ablage|Beispiel 6]]. | |||
== Die Antwort schreiben: oWriter == | |||
Der Writer schreibt '''der Reihe nach''': Jeder Aufruf hängt ein Feld an der Stelle an, an der er steht. Die äußere Klammer setzt der Server. Schreibt das Skript nichts, lautet die Antwort <code>{}</code>. Ohne weitere Angabe ist der Status 200 und der Content-Type <code>application/json; charset=utf-8</code>. | |||
<syntaxhighlight lang="delphi"> | |||
procedure Get(oReader: TxRestReader; oWriter: TxRestWriter); | |||
begin | |||
oWriter.Str('wert_string', '123'); | |||
oWriter.Int('wert_int' , 456); | |||
end; | |||
</syntaxhighlight> | |||
{| class="wikitable" | |||
! Aufruf !! Ergebnis | |||
|- | |||
| <code>oWriter.Str('name', cWert)</code> || Zeichenkette, immer maskiert | |||
|- | |||
| <code>oWriter.StrN('name', cWert)</code> || wie <code>Str</code>, aber <code>null</code> statt einer leeren Zeichenkette | |||
|- | |||
| <code>oWriter.Int('anz', nWert)</code> || Ganzzahl | |||
|- | |||
| <code>oWriter.Num('preis', nWert, 2)</code> || Kommazahl mit fester Stellenzahl. Immer mit Dezimalpunkt, unabhängig von den Ländereinstellungen des Servers. | |||
|- | |||
| <code>oWriter.Bool('aktiv', lWert)</code> || <code>true</code> oder <code>false</code> | |||
|- | |||
| <code>oWriter.Null('lat')</code> || ausdrücklich <code>null</code> | |||
|- | |||
| <code>oWriter.ObjBegin('kunde')</code> … <code>oWriter.ObjEnd</code> || Unterobjekt | |||
|- | |||
| <code>oWriter.ArrBegin('dateien')</code> … <code>oWriter.ArrEnd</code> || Liste | |||
|- | |||
| <code>oWriter.RootArr()</code> || Die Wurzel ist eine Liste statt eines Objekts. Steht vor dem ersten Feld. Ein <code>ArrEnd</code> gehört nicht dazu. | |||
|- | |||
| <code>oWriter.Raw('meta', cJson)</code> || Fertiges JSON-Fragment einbetten, siehe unten | |||
|} | |||
'''In einer Liste hat ein Eintrag keinen Namen.''' Der leere Feldname steht dafür: | |||
<syntaxhighlight lang="delphi"> | |||
oWriter.ArrBegin('dateien'); | |||
while (not qDat.EoF) do begin | |||
oWriter.ObjBegin(''); | |||
oWriter.Str ('uid' , qDat.A2C('f_uid')); | |||
oWriter.Int ('bytes' , qDat.A2I('f_bytes')); | |||
oWriter.StrN('kategorie', AllTrim(qDat.A2C('f_kat'))); // null, wenn leer | |||
oWriter.ObjEnd; | |||
qDat.Next(); | |||
end; | |||
oWriter.ArrEnd; | |||
</syntaxhighlight> | |||
Ein Name in einer Liste, ein fehlender Name in einem Objekt und eine Ebene, die am Ende der Methode noch offen ist, sind '''Strukturfehler'''. Der Server antwortet dann mit '''500''' und nennt die Stelle im Protokoll. Halbes JSON liefert er nie aus. | |||
{{Hinweis|Eine Hilfsprozedur bekommt den Writer als Parameter und schreibt an der Stelle, an der sie aufgerufen wird. Sie gibt kein Fragment zurück. So steht die Reihenfolge der Antwort im Code: | |||
<code>procedure DateienSchreiben(oWriter: TxRestWriter; const cNr: string);</code>}} | |||
<code>Raw</code> prüft das Fragment und bettet den Originaltext ein. Ungültiges JSON führt zu einem Serverfehler, der das Feld nennt. Gebraucht wird <code>Raw</code> für gespeicherte, '''signierte''' Dokumente: Neu aufgebaut, verlöre das Dokument die signierte Reihenfolge der Felder. | |||
=== Zeitangaben === | |||
Zeitpunkte gehen als ISO 8601 mit Offset über die Leitung. Für die Umwandlung gibt es eigene Funktionen: | |||
{| class="wikitable" | |||
! Aufruf !! Zweck | |||
|- | |||
| <code>RestIsoFromDate(dWert, cOffset)</code> || OBS-Zeitpunkt in ''2026-09-09T14:12:00+02:00''. Leere Zeichenkette bei leerem Datum. | |||
|- | |||
| <code>RestDateFromIso(cWert, cOffset)</code> || ISO-Zeichenkette in einen OBS-Zeitpunkt in Ortszeit des Servers | |||
|- | |||
| <code>oReader.Offset()</code> || Der Offset für beide Funktionen | |||
|- | |||
| <code>RestOffsetToMinutes(cOffset)</code> || Offset in Minuten, für eigene Rechnungen | |||
|} | |||
== Antwort steuern: Statuscode, Header, traceId == | |||
Statuscode, Header, Fehler und Dateien setzen eigene Aufrufe des Writers, nicht Felder im Körper. | |||
{| class="wikitable" | |||
! Aufruf !! Wirkung | |||
|- | |||
| <code>oWriter.Status(201)</code> || HTTP-Statuscode, z.B. 201, 204, 409 oder 422. Ohne Angabe: 200. Werte außerhalb von 100 bis 599 ignoriert der Server. | |||
|- | |||
| <code>oWriter.Header('ETag', '"7"')</code> || Beliebiger Header der Antwort, z.B. <code>ETag</code>, <code>Location</code>, <code>Retry-After</code>. Steuerzeichen in Name und Wert entfernt der Server. | |||
|- | |||
| <code>oWriter.NoBody()</code> || Kein Körper, für '''204''' | |||
|- | |||
| <code>oWriter.Error(422, 'VALIDATION_FAILED', 'Feld "menge" fehlt')</code> || Fertige Fehlerantwort im Format des Servers, siehe [[#Fehlerbehandlung im Skript|Fehlerbehandlung]] | |||
|- | |||
| <code>oWriter.HasError()</code> || Steht schon eine Fehlerantwort im Writer? | |||
|- | |||
| <code>oWriter.JwtRevoke('session')</code> || Sperrt die Sitzung des vorgelegten Tokens, mit <code>'all'</code> alle Sitzungen des Subjects. Siehe [[OBS/Kostenpflichtige Module/REST-Server/Anmeldung mit JWT#Abmelden aus einem Endpunkt|Anmeldung mit JWT]]. | |||
|- | |||
| <code>oWriter.SendFile(cPfad, cName, cTyp)</code> || Eine Datei statt eines JSON-Körpers ausliefern. Die Datei bleibt liegen, der Download ist fortsetzbar. | |||
|- | |||
| <code>oWriter.SendTempFile(cPfad, cName, cTyp)</code> || Wie <code>SendFile</code>, die Datei wird nach dem Senden gelöscht. Für Ergebnisse, die je Abruf entstehen. | |||
|} | |||
Dateiantworten beschreibt [[OBS/Kostenpflichtige Module/REST-Server/Datei-Download|Datei-Download]]. | |||
Jede Antwort trägt den Header <code>X-Trace-Id</code>. Dieselbe Kennung liefert <code>oReader.TraceId()</code>, und sie steht in jeder Fehlerzeile des Protokolls. So findet der Betreiber einen Fehler ohne Zugriff auf das Gerät. | |||
Setzt das Skript den Header <code>Content-Encoding</code> selbst, packt der Server die Antwort nicht noch einmal. | |||
== | === Beispiel: Anlegen mit 201, Location und ETag === | ||
<syntaxhighlight lang="delphi"> | |||
procedure Post(oReader: TxRestReader; oWriter: TxRestWriter); | |||
var cNeueNr: string; | |||
begin | |||
// ... Datensatz anlegen, neue Nummer ermitteln ... | |||
oWriter.Str('nr', cNeueNr); | |||
oWriter.Status(201); | |||
oWriter.Header('Location', '/beispiel/tickets/' + cNeueNr); | |||
oWriter.Header('ETag' , '"1"'); | |||
end; | |||
</syntaxhighlight> | |||
=== Beispiel: Versionsprüfung mit ETag und If-Match === | |||
Mit Statuscode, Header und dem Header <code>If-Match</code> der Anfrage führt das Skript je Datensatz einen Versionszähler. Veraltete Schreibzugriffe lehnt es mit '''409''' ab. Clients senden den ETag meist in Anführungszeichen (<code>"7"</code>), manche ohne. | |||
<syntaxhighlight lang=" | <syntaxhighlight lang="delphi"> | ||
procedure Put(oReader: TxRestReader; oWriter: TxRestWriter); | |||
var nAktuell: Integer; | |||
cETag : string; | |||
cIfMatch: string; | |||
begin | begin | ||
nAktuell := TicketVersion(oReader.Path('nr')); // eigene Funktion | |||
cETag := '"' + IntToStr(nAktuell) + '"'; | |||
cIfMatch := AllTrim(oReader.Param('if-match')); | |||
if (cIfMatch <> cETag) and (cIfMatch <> IntToStr(nAktuell)) then begin | |||
// Der gültige ETag gehört auch an die Ablehnung, | |||
// sonst scheitert der nächste Versuch des Clients wieder. | |||
oWriter.Header('ETag', cETag); | |||
oWriter.Error(409, 'VERSION_CONFLICT', 'Der Datensatz wurde zwischenzeitlich geändert'); | |||
exit; | |||
end; | end; | ||
// ... speichern, Version hochzählen ... | |||
oWriter.Header('ETag', '"' + IntToStr(nAktuell + 1) + '"'); | |||
end; | end; | ||
</syntaxhighlight> | </syntaxhighlight> | ||
== | <code>VERSION_CONFLICT</code> ist hier ein eigener Code des Skripts. Der Server selbst verwendet für '''409''' den Code <code>CONFLICT</code>. | ||
== Transaktion == | |||
<code>POST</code>, <code>PUT</code>, <code>PATCH</code> und <code>DELETE</code> laufen in '''einer''' Datenbanktransaktion. Darin liegen alle Schreibvorgänge des Skripts und das Ergebnis der Idempotenz-Prüfung. | |||
{| class="wikitable" | |||
! Ende des Skripts !! Wirkung | |||
|- | |||
| Status unter 400 || Alle Änderungen werden festgeschrieben. | |||
|- | |||
| Status 400 oder höher || Alle Änderungen werden zurückgerollt. | |||
|- | |||
| Exception oder Skriptfehler || Alle Änderungen werden zurückgerollt, der Client erhält '''500'''. | |||
|} | |||
* '''Ablehnen ist gefahrlos.''' Ein Skript darf schreiben und danach mit <code>oWriter.Error</code> abbrechen. In der Datenbank bleibt nichts davon. | |||
* '''Auch eigene Protokollzeilen''', die das Skript in eine Tabelle schreibt, werden bei Status 400 oder höher zurückgerollt. Die Fehlerzeile des Servers in <code>RESTSRV_PROTO</code> bleibt, siehe [[#Fehler im Protokoll|Fehler im Protokoll]]. | |||
* '''Eigene Transaktionen''' im Skript (<code>StartTransaction</code>, <code>Commit</code>) sind wirkungslos. Sie liegen innerhalb der Transaktion des Servers, und nur deren Ende zählt. | |||
* '''Teilweise Schreibvorgänge''' bleiben nur stehen, wenn das Skript einen Schreibfehler übergeht und mit Status unter 400 antwortet. Werten Sie deshalb jeden Schreibvorgang aus, siehe [[#Schreibfehler erkennen|Schreibfehler erkennen]]. | |||
<code>GET</code> läuft '''ohne''' Transaktion. Schreibt ein GET-Skript, wirkt jeder Schreibvorgang sofort und bleibt auch bei einer Fehlerantwort stehen. | |||
== Idempotenz == | |||
Bei <code>POST</code>, <code>PUT</code>, <code>PATCH</code> und <code>DELETE</code> fängt der Server doppelte Sendungen über den Header <code>Idempotency-Key</code> ab. Das Skript braucht dafür keine eigene Logik. Fehlt der Header, läuft das Skript nicht. | |||
Für das Skript gilt: | |||
* Eine Wiederholung mit gespeicherter Antwort beantwortet der Server selbst. Das Skript läuft dabei nicht. | |||
* Gespeichert wird nur eine Antwort mit Status 2xx ohne Datei. Was sie enthält, ist eingefroren. Schreiben Sie die Antwort deshalb vollständig. | |||
* Melden Sie fachliche Ablehnungen mit 4xx (z.B. 404, 409, 422), nicht mit 200 und Fehlertext. Eine 2xx-Antwort würde gespeichert, und der Client bekäme sie bei jedem weiteren Versuch erneut. | |||
* Nach Status 400 oder höher ist alles zurückgerollt und der Key wieder frei. Eine Wiederholung ist gefahrlos. | |||
Den Ablauf aus Sicht des Clients beschreibt [[OBS/Kostenpflichtige Module/REST-Server/HTTP-Schnittstelle#Idempotenz|HTTP-Schnittstelle]]. | |||
<syntaxhighlight lang=" | == Fehlerbehandlung im Skript == | ||
Löst das Skript eine Exception aus oder lässt es sich nicht übersetzen, antwortet der Server mit '''500''' <code>INTERNAL_ERROR</code> und einer allgemeinen Meldung. Den Fehlertext schreibt er ins Protokoll. Der Client sieht keine internen Details. | |||
Für einen gezielten Fehler gibt es '''einen''' Aufruf. Er erzeugt dieselbe Fehlerantwort wie die Fehler des Servers: Statuscode, <code>code</code>, <code>message</code>, <code>uid</code> und <code>traceId</code>. | |||
<syntaxhighlight lang="delphi"> | |||
procedure Post(oReader: TxRestReader; oWriter: TxRestWriter); | |||
begin | begin | ||
if (Empty(oReader.Param('kundennr'))) then begin | |||
oWriter.Error(422, 'VALIDATION_FAILED', 'Parameter "kundennr" fehlt'); | |||
exit; | |||
end; | |||
// ... | |||
end; | |||
</syntaxhighlight> | |||
{{Hinweis|<code>Error</code> verwirft einen schon begonnenen Körper und setzt die Fehlerantwort. Ein Skript darf also Felder schreiben und danach noch abbrechen. Nur eine noch offene Ebene (<code>ObjBegin</code> ohne <code>ObjEnd</code>) bleibt ein Strukturfehler.}} | |||
Codes, die auch der Server verwendet: <code>VALIDATION_FAILED</code> (422), <code>NOT_FOUND</code> (404), <code>FORBIDDEN_ROLE</code> (403), <code>CONFLICT</code> (409). Eigene, fachlich sprechende Codes sind erlaubt. Halten Sie sie stabil, denn Clients richten ihre Reaktion danach aus. Alle Codes des Servers: [[OBS/Kostenpflichtige Module/REST-Server/HTTP-Schnittstelle#Fehlercodes|HTTP-Schnittstelle]]. | |||
=== Fehler im Protokoll === | |||
Jede Antwort des Skripts mit Status 400 oder höher schreibt der Server als eine Zeile nach <code>RESTSRV_PROTO</code>, mit <code>code</code> und <code>message</code> aus dem Fehlerobjekt: | |||
<syntaxhighlight lang="text"> | |||
Fehler VALIDATION_FAILED [422 POST /beispiel/tickets] [trace=<traceId>]: Parameter "kundennr" fehlt | |||
</syntaxhighlight> | |||
Daraus folgt: | |||
* Verwenden Sie <code>oWriter.Error</code>. Ohne Fehlerobjekt steht im Protokoll nur der Code aus dem Status und der Text „Antwort ohne error-Objekt“. | |||
* Schreiben Sie keine sensiblen Daten in die <code>message</code>. Sie steht im Protokoll und geht an den Client. | |||
* Schreiben Sie für dieselbe Ablehnung keine eigene Protokollzeile. Der Server hat sie bereits. | |||
Protokoll und Suche über die <code>traceId</code>: [[OBS/Kostenpflichtige Module/REST-Server/Betrieb und Fehlersuche|Betrieb und Fehlersuche]]. | |||
== Datenbankzugriff == | |||
Im Skript beginnt jede Datenbankfunktion mit <code>oDB</code>, ohne weiteren Parameter davor. Der Abfragetyp für <code>DB_SOpen</code> ist <code>TxFQuery</code>. | |||
{| class="wikitable" | |||
! Zweck !! Aufruf | |||
|- | |||
| Lesen || <code>DB_SOpen(oDB, cSql, qDat)</code>, dann <code>qDat.EoF</code>, <code>qDat.Next()</code>, <code>qDat.A2C('feld')</code>, <code>A2I</code>, <code>A2F</code>, <code>A2D</code>, <code>A2UID()</code>, am Ende <code>DB_Close(qDat)</code> | |||
|- | |||
| Neu anlegen || <code>qUpd := qSqlInit(oDB, 'TAB')</code>, <code>qUpd.qSet('feld', wert)</code>, <code>qUpd.SaveData(NEW_RECORD)</code> auswerten, <code>qSqlFree(qUpd)</code> | |||
|- | |||
| Ändern || <code>qUpd := qSqlInit(oDB, 'TAB')</code>, <code>qUpd.qSet('sys_uid', cUid)</code>, weitere <code>qSet</code>, <code>qUpd.SaveData(UPDATE_RECORD)</code> auswerten, <code>qSqlFree(qUpd)</code> | |||
|- | |||
| Direkt ausführen || <code>DB_SqlExec(oDB, cSql)</code> | |||
|- | |||
| Existenz prüfen || <code>DB_LSeek(oDB, 'TAB', cWhere)</code> | |||
|- | |||
| Werte einsetzen (Pflicht) || <code>DB_SQLVal(wert)</code> | |||
|} | |||
=== Ändern: qSqlInit statt qSqlRead === | |||
Zum '''Ändern''' eines Satzes nehmen Sie ebenfalls <code>qSqlInit</code>. Die <code>sys_uid</code> adressiert den Satz: | |||
<syntaxhighlight lang="delphi"> | |||
qUpd := qSqlInit(oDB, 'TICKETS'); | |||
qUpd.qSet('sys_uid' , cUid); // adressiert den vorhandenen Satz | |||
qUpd.qSet('ti_status', '9'); | |||
Speichern(qUpd, UPDATE_RECORD, 'Ticket'); // siehe Schreibfehler erkennen | |||
</syntaxhighlight> | |||
<code>qSqlRead</code> ist dafür die falsche Wahl: | |||
* Es liest zuerst den kompletten Satz. Das kostet einen zusätzlichen Zugriff. | |||
* Es schreibt nur Änderungen. Ist der neue Wert gleich dem alten, liefert <code>SaveData</code> ''False'', genau wie bei einem echten Fehler. | |||
{{Hinweis|Ohne <code>sys_uid</code> legt <code>qSqlInit</code> einen '''neuen''' Satz an. Setzen Sie die <code>sys_uid</code> bei jeder Änderung.}} | |||
Eine einzige Abfrage auf die <code>sys_uid</code> liefert Existenzprüfung und Schreibziel zugleich: | |||
<syntaxhighlight lang="delphi"> | |||
cUid := ''; | |||
if (DB_SOpen(oDB, 'SELECT sys_uid FROM TICKETS WHERE ' + cWhere + ' LIMIT 1', qDat)) then begin | |||
if (not qDat.EoF) then begin | |||
cUid := qDat.A2UID(); | |||
end; | |||
end; | |||
DB_Close(qDat); | |||
if (not Empty(cUid)) then begin | |||
// ändern: qSqlInit mit sys_uid | |||
end else begin | |||
// anlegen: qSqlInit ohne sys_uid | |||
end; | |||
</syntaxhighlight> | |||
=== Mehrere Felder sind ein Schreibvorgang === | |||
Ein <code>qSqlInit</code>-Objekt nimmt beliebig viele <code>qSet</code> an und schreibt sie mit '''einem''' <code>SaveData</code>. Felder derselben Zeile gehören in dasselbe Objekt: | |||
<syntaxhighlight lang="delphi"> | |||
// FALSCH: je Feld ein Aufruf mit eigener Abfrage und eigenem Schreibvorgang | |||
FeldSetzen(cUid, 'ti_status', '9'); | |||
FeldSetzen(cUid, 'ti_grund' , cGrund); | |||
FeldSetzen(cUid, 'ti_von' , cBenutzer); | |||
// RICHTIG: ein Schreibobjekt, ein SaveData | |||
qUpd := qSqlInit(oDB, 'TICKETS'); | |||
qUpd.qSet('sys_uid' , cUid); | |||
qUpd.qSet('ti_status', '9'); | |||
qUpd.qSet('ti_grund' , cGrund); | |||
qUpd.qSet('ti_von' , cBenutzer); | |||
Speichern(qUpd, UPDATE_RECORD, 'Ticket'); | |||
</syntaxhighlight> | |||
Einzeln geschriebene Felder kosten je Feld eine Abfrage und einen Schreibvorgang. Wird nichts gesetzt, geben Sie das Schreibobjekt mit <code>qSqlFree</code> frei, statt ein leeres <code>SaveData</code> abzusetzen. | |||
=== Keine Abfrage je Zeile === | |||
Was in einer Liste je Zeile nachgeschlagen wird, kostet '''N''' Abfragen für '''eine''' Antwort. Bei fünfzig Aufträgen sind das fünfzig Abfragen für ein einziges Feld. Der Ausweg: | |||
* Werte aus einer 1:1-Beziehung über einen <code>LEFT JOIN</code> mitnehmen. Bei einem eindeutigen Index auf dem Join-Feld vervielfacht er die Zeilen nicht. | |||
* Einzelwerte aus einer 1:n-Beziehung über eine Unterabfrage in der SELECT-Liste holen, nicht über einen Join. | |||
* Eine echte Unterliste (Positionen, Dateien) nur nachladen, wenn ein Zählfeld in der Hauptabfrage sagt, dass es eine gibt. | |||
{{Hinweis|Ein GET soll lesen. Schreibvorgänge im Lesepfad vervielfachen sich mit der Zeilenzahl und laufen ohne Transaktion.}} | |||
=== Schreibfehler erkennen === | |||
<code>SaveData</code> liefert einen Boolean, und der ist die einzige Fehlermeldung. Auch der Parameter ist ein Boolean: <code>NEW_RECORD</code> und <code>UPDATE_RECORD</code> sind Wahrheitswerte. Scheitert das Schreiben in der Datenbank (doppelter Wert in einem eindeutigen Index, zu langer Wert, fehlende Spalte), dann | |||
* löst das '''keine''' Exception aus, | |||
* steht '''nichts''' in <code>RESTSRV_PROTO</code>, | |||
* läuft das Skript weiter und meldet den Erfolg, den es selbst schreibt. | |||
Prüfen Sie den Rückgabewert deshalb immer. Am einfachsten über eine kleine Prozedur in der gemeinsamen Bibliothek: | |||
<syntaxhighlight lang="delphi"> | |||
procedure Speichern(qUpd: TqSQL; lNeu: Boolean; const cWas: string); | |||
var lOk: Boolean; | |||
begin | |||
lOk := qUpd.SaveData(lNeu); | |||
qSqlFree(qUpd); // auch im Fehlerfall freigeben | |||
if (not lOk) then begin | |||
raise Exception.Create('Schreiben fehlgeschlagen: ' + cWas); | |||
end; | end; | ||
end; | end; | ||
// Aufruf statt SaveData und qSqlFree: | |||
qUpd := qSqlInit(oDB, 'TICKETS'); | |||
qUpd.qSet('ti_betreff', cBetreff); | |||
Speichern(qUpd, NEW_RECORD, 'Ticket'); | |||
</syntaxhighlight> | </syntaxhighlight> | ||
Die Exception fängt der Server. Er schreibt den Text ins Protokoll, rollt alle Änderungen der Anfrage zurück und antwortet mit '''500'''. Der <code>Idempotency-Key</code> wird frei, der Client kann wiederholen. | |||
== Anmeldeskript (JWT) == | |||
Zugänge mit '''JWT-Authentifizierung''' haben ein eigenes Anmeldeskript. Sie bearbeiten es in der Zugänge-Liste mit {{F7}}. Es enthält die Methoden <code>Authenticate</code> und <code>Refresh</code> mit derselben Signatur wie ein Endpunkt-Skript. Rückgabefelder, Beispiel und Fehlerfälle stehen unter [[OBS/Kostenpflichtige Module/REST-Server/Anmeldung mit JWT#Das Anmeldeskript|Anmeldung mit JWT]]. | |||
== Gemeinsamen Code auslagern == | |||
Logik, die mehrere Endpunkte brauchen, muss nicht in jedes Skript kopiert werden. Eine Direktive lädt beim Übersetzen einen Textbaustein aus einer Tabelle nach: | |||
<syntaxhighlight lang="delphi"> | |||
{$L T="restsrv_endpoints" I="re_pathtemplate" V="/meinapp/lib" F="re_script"} | |||
</syntaxhighlight> | |||
{| class="wikitable" | {| class="wikitable" | ||
! | ! Attribut !! Bedeutung | ||
|- | |||
| <code>T</code> || Tabelle, aus der geladen wird | |||
|- | |||
| <code>I</code> || Spalte, über die gesucht wird | |||
|- | |- | ||
| | | <code>V</code> || Wert, der in dieser Spalte stehen muss | ||
|- | |- | ||
| | | <code>F</code> || Spalte, deren Inhalt an dieser Stelle eingesetzt wird | ||
|} | |} | ||
Die Direktive steht üblicherweise direkt unter dem Kopfkommentar des Skripts. Eine Funktion aus der Bibliothek rufen Sie danach auf wie eine im Skript selbst geschriebene. | |||
=== Bibliothek als eigener Endpunkt === | |||
Am wenigsten Verwaltung macht eine Bibliothek als eigener Endpunkt: | |||
# Legen Sie einen Endpunkt mit eigenem '''Pfad-Template''' an, z.B. <code>/meinapp/lib</code>. | |||
# Schreiben Sie den Quelltext der Bibliothek in das Skript dieses Endpunkts. | |||
# Vergeben Sie für diesen Endpunkt '''keine''' Berechtigung. Ein Aufruf von außen endet dann mit '''403'''. | |||
# Fügen Sie in jedem nutzenden Skript die Direktive ein. | |||
Eine Änderung an der Bibliothek gilt für alle Skripte, die sie einbinden. | |||
<syntaxhighlight lang=" | {{Hinweis|Spielen Sie Bibliothek und Skripte gemeinsam ein. Nutzt ein Skript eine neue Funktion, die in der Bibliothek noch fehlt, meldet der Übersetzer nur den neuen Namen als ''Unknown name''. Das sieht leicht wie ein Fehler im Skript aus.}} | ||
== Verfügbare Bibliotheken == | |||
Im Skript stehen die OBS-Funktionen bereit, die Sie aus Makros kennen: | |||
* Zeichenketten, Datum, Zahlen und Konstanten wie <code>CRLF</code>, <code>SINGELQUOTE</code> und <code>MINDATETIME</code> | |||
* Datenbank: lesen, schreiben, direkt ausführen | |||
* Dateifunktionen | |||
* Fachfunktionen, z.B. zu Aufträgen, Reparaturaufträgen, Angeboten, Einkauf und Artikelbewegungen | |||
* Reader, Writer und die [[#Zeitangaben|Zeitfunktionen]] dieser Seite | |||
Eine JSON-Bibliothek braucht ein Endpunkt-Skript nicht. Der Reader liest den Körper, der Writer erzeugt die Antwort. | |||
== Fallstricke im Skript == | |||
{| class="wikitable" | |||
! Stolperstein !! Richtig | |||
|- | |||
| Datenbankfunktion mit zusätzlicher Kennung als erstem Parameter, wie im Delphi-Code || Im Skript ohne Kennung: <code>DB_SOpen(oDB, cSql, qDat)</code>, <code>qSqlInit(oDB, 'TAB')</code>, <code>qSqlRead(oDB, 'TAB', cWhere)</code> | |||
|- | |||
| Generics, z.B. <code>oReader.Str<T>(…)</code> || Gibt es in der Skriptsprache nicht. Je Typ ein eigener Leser: <code>Str</code>, <code>Int</code>, <code>Num</code>, <code>Bool</code>. | |||
|- | |||
| Hilfsfunktion, die ein JSON-Fragment als Zeichenkette zurückgibt || Den Writer als Parameter übergeben und an der richtigen Stelle hineinschreiben | |||
|- | |||
| <code>oWriter.ArrEnd</code> nach <code>RootArr</code> || <code>RootArr</code> öffnet keine Ebene. Ein <code>ArrEnd</code> dazu ist ein Strukturfehler. | |||
|- | |||
| Zahlen selbst formatieren, z.B. mit <code>NStr</code> || <code>NStr</code> liefert deutsche Schreibweise mit Tausenderpunkt. Für JSON <code>oWriter.Num('preis', nWert, 2)</code> verwenden. | |||
|- | |||
| <code>fVal</code> auf eine JSON-Zahl || <code>oReader.Num</code> bzw. <code>oReader.NumDef</code> verwenden. Sie lesen den Dezimalpunkt richtig. | |||
|- | |||
| <code>EMPTY_DATE</code> für ein leeres Datum || <code>EMPTY_DATE</code> ist im Skript eine Zeichenkette. Für Datumsvariablen und Vergleiche <code>MINDATETIME</code> verwenden. | |||
|- | |||
| <code>TStringList</code> für Zwischenlisten || In Skripten unzuverlässig. Kleine Mengen als Zeichenkette mit Trennzeichen führen (<code>'|' + wert + '|'</code>) und mit <code>Pos</code> prüfen. | |||
|- | |||
| Vorgabewerte für Parameter eigener Funktionen || Werden nicht unterstützt. Alle Parameter ausschreiben. | |||
|- | |||
| <code>qUpd.SaveData(…)</code> als Anweisung ohne Auswertung || Rückgabewert immer auswerten, siehe [[#Schreibfehler erkennen|Schreibfehler erkennen]] | |||
|- | |||
| Je Feld ein eigener Aufruf zum Setzen || Ein <code>qSqlInit</code>-Objekt, alle <code>qSet</code>, ein <code>SaveData</code>, siehe [[#Mehrere Felder sind ein Schreibvorgang|Mehrere Felder]] | |||
|- | |||
| Ein Wert je Zeile nachgeschlagen || <code>LEFT JOIN</code> (1:1) oder Unterabfrage (1:n), siehe [[#Keine Abfrage je Zeile|Keine Abfrage je Zeile]] | |||
|- | |||
| Ausgabeparameter vom Typ <code>var … : TDateTime</code> || Bringt die Skriptausführung zum Absturz, und zwar erst beim Lesen des Werts. <code>var string</code>, <code>var Integer</code> und <code>var Double</code> laufen. Zeitpunkte als ISO-Zeichenkette zurückgeben und beim Aufrufer wandeln. | |||
|} | |||
== Skript-Cache == | |||
Der Server hält die Endpunkte samt Skript bis zu 60 Sekunden im Zwischenspeicher. Eine Änderung am Skript wirkt deshalb spätestens nach 60 Sekunden. Nach einem Neustart des Dienstes wirkt sie sofort. | |||
== Beispiel == | |||
Ein Endpunkt mit dem '''Pfad-Template''' <code>/beispiel/tickets/{nr}</code> liest ein Ticket und ändert seinen Status. Tabelle und Felder stehen für Ihre eigenen; <code>Speichern</code> ist die Prozedur aus [[#Schreibfehler erkennen|Schreibfehler erkennen]]. | |||
<syntaxhighlight lang="delphi"> | |||
procedure Get(oReader: TxRestReader; oWriter: TxRestWriter); | |||
var cSql : string; | |||
qTick: TxFQuery; | |||
lGef : Boolean; | |||
begin | begin | ||
cSql := 'SELECT ti_nr, ti_betreff, ti_status FROM TICKETS' + | |||
' WHERE ti_nr = ' + DB_SQLVal(oReader.Path('nr')); | |||
if ( | |||
lGef := false; | |||
if (DB_SOpen(oDB, cSql, qTick)) then begin | |||
if (not qTick.EoF) then begin | |||
lGef := true; | |||
oWriter.Str('nr' , AllTrim(qTick.A2C('ti_nr'))); | |||
oWriter.Str('betreff', AllTrim(qTick.A2C('ti_betreff'))); | |||
oWriter.Str('status' , AllTrim(qTick.A2C('ti_status'))); | |||
end; | end; | ||
end; | |||
DB_Close(qTick); | |||
if (not lGef) then begin | |||
oWriter.Error(404, 'NOT_FOUND', 'Ticket nicht gefunden'); | |||
end; | end; | ||
end; | end; | ||
== | procedure Put(oReader: TxRestReader; oWriter: TxRestWriter); | ||
var cNr : string; | |||
cStatus: string; | |||
cUid : string; | |||
cSql : string; | |||
qTick : TxFQuery; | |||
qUpd : TqSQL; | |||
begin | |||
cNr := oReader.Path('nr'); | |||
cStatus := ''; | |||
if (not oReader.Str('status', cStatus)) then begin | |||
oWriter.Error(422, 'VALIDATION_FAILED', 'Feld "status" fehlt'); | |||
exit; | |||
end; | |||
cUid := ''; | |||
cSql := 'SELECT sys_uid FROM TICKETS WHERE ti_nr = ' + DB_SQLVal(cNr); | |||
if (DB_SOpen(oDB, cSql, qTick)) then begin | |||
if (not qTick.EoF) then begin | |||
cUid := qTick.A2UID(); | |||
end; | |||
end; | |||
DB_Close(qTick); | |||
if (Empty(cUid)) then begin | |||
oWriter.Error(404, 'NOT_FOUND', 'Ticket nicht gefunden'); | |||
exit; | |||
end; | |||
qUpd := qSqlInit(oDB, 'TICKETS'); | |||
qUpd.qSet('sys_uid' , cUid); | |||
qUpd.qSet('ti_status', cStatus); | |||
Speichern(qUpd, UPDATE_RECORD, 'Ticket'); | |||
oWriter.Str('nr' , cNr); | |||
oWriter.Str('status', cStatus); | |||
end; | |||
</syntaxhighlight> | |||
Aufruf des PUT mit curl: | |||
<syntaxhighlight lang="bash"> | |||
curl -X PUT "https://obs.example.com:8443/beispiel/tickets/4711" \ | |||
-H "apikey: abcdef-ghij-klmn-opqr-stuvwx" \ | |||
-H "Idempotency-Key: 3f2b8c1e-7d4a-4e9b-9c0f-5a6d2e1b8f47" \ | |||
-H "Content-Type: application/json; charset=utf-8" \ | |||
-d '{"status": "9"}' | |||
</syntaxhighlight> | |||
Weitere vollständige Beispiele: | |||
* [[OBS/Kostenpflichtige Module/REST-Server/Beispiele/Daten-Abruf mit JWT-Anmeldung|Beispiel 1: Daten-Abruf mit JWT]] | |||
* [[OBS/Kostenpflichtige Module/REST-Server/Beispiele/Datensatz anlegen mit JSON-Körper|Beispiel 3: Datensatz anlegen mit JSON-Body]] | |||
* [[OBS/Kostenpflichtige Module/REST-Server/Beispiele/Pfad-Parameter|Beispiel 4: Pfad-Parameter im Routing]] | |||
* [[OBS/Kostenpflichtige Module/REST-Server/Beispiele/Schreibzugriff mit Statuscodes, ETag und Idempotenz|Beispiel 5: Schreibzugriff mit Statuscodes, ETag und Idempotenz]] | |||
* [[OBS/Kostenpflichtige Module/REST-Server/Beispiele/Datei-Upload und Ablage|Beispiel 6: Datei-Upload und Ablage]] | |||
* [[OBS/Kostenpflichtige Module/ | == Siehe auch == | ||
* [[OBS/Kostenpflichtige Module/ | * [[OBS/Kostenpflichtige Module/REST-Server|REST-Server]] | ||
* [[OBS/Kostenpflichtige Module/REST-Server/Endpunkte|Endpunkte]] | |||
* [[OBS/Kostenpflichtige Module/REST-Server/HTTP-Schnittstelle|HTTP-Schnittstelle]] | |||
* [[OBS/Kostenpflichtige Module/REST-Server/Anmeldung mit JWT|Anmeldung mit JWT]] | |||
* [[OBS/Kostenpflichtige Module/REST-Server/Datei-Upload|Datei-Upload]] | |||
* [[OBS/Kostenpflichtige Module/REST-Server/Datei-Download|Datei-Download]] | |||
* [[OBS/Kostenpflichtige Module/REST-Server/Betrieb und Fehlersuche|Betrieb und Fehlersuche]] | |||
Aktuelle Version vom 17. November 2026, 07:24 Uhr
Scripting
Hinter jedem Endpunkt steht ein Skript, das Sie selbst schreiben. Damit bestimmen Sie, welche OBS-Daten ein Endpunkt liest oder ändert und was der Client zurückbekommt. Authentifizierung, Fehlerformat, Idempotenz und Transaktion übernimmt der Server. Diese Seite beschreibt die Skript-Schnittstelle: Anfrage lesen, Antwort schreiben, Fehler melden, gemeinsamen Code nutzen.
Das Skript ist in Object Pascal geschrieben und nutzt die OBS-Funktionen für Datenbank und Hilfsfunktionen. Wie ein Client den Server aufruft, steht unter HTTP-Schnittstelle.
Aufruf
Je HTTP-Methode enthält das Skript eine gleichnamige Prozedur. Der Server ruft die Prozedur auf, die zur Methode der Anfrage passt:
procedure Get (oReader: TxRestReader; oWriter: TxRestWriter);
procedure Post (oReader: TxRestReader; oWriter: TxRestWriter);
procedure Put (oReader: TxRestReader; oWriter: TxRestWriter);
procedure Patch (oReader: TxRestReader; oWriter: TxRestWriter);
procedure Delete(oReader: TxRestReader; oWriter: TxRestWriter);
Ein Skript enthält nur die Methoden, die der Endpunkt anbietet. Fehlt die Methode zur Anfrage, antwortet der Server mit 405 METHOD_NOT_ALLOWED. Der Header Allow nennt die Methoden, die das Skript tatsächlich enthält:
HTTP/1.1 405 Method Not Allowed
Allow: GET, PUT
Lässt sich das Skript nicht übersetzen, antwortet der Server mit 500. Die Meldung des Übersetzers mit Grund und Zeile steht im Protokoll.
Parameter
| Parameter | Typ | Pflicht | Standard | Bedeutung |
|---|---|---|---|---|
oReader |
TxRestReader |
✓ | – | Die Anfrage: Query, Header, Pfadwerte, Formularfelder, Token-Werte, Körper und hochgeladene Datei. Siehe oReader. |
oWriter |
TxRestWriter |
✓ | – | Die Antwort: Felder, Statuscode, Header, Fehler oder Datei. Siehe oWriter. |
Beide Objekte erzeugt und besitzt der Server. Im Skript wird nichts angelegt und nichts freigegeben. Die Datenbankverbindung steht im Skript global als oDB bereit.
Sicherheitshinweise
DB_SQLVal ein und prüfen Sie Eingaben gegen erlaubte Werte.- Prüfen Sie Pflichtfelder, Typen und Wertebereiche.
- Geben Sie nur zurück, was der Client braucht: keine internen Kennungen, keine Systemfelder, keine Passwörter.
- Lesen Sie Mandant und Rollen aus dem Token, nie aus Körper oder Query.
- Schreiben Sie keine internen Details in Fehlermeldungen. Die
messagegeht an den Client.
Die Anfrage lesen: oReader
oReader ist der einzige Zugang zur Anfrage. Alle Werte sind Zeichenketten oder werden über einen typisierten Leser geholt.
| Aufruf | Liefert |
|---|---|
oReader.Param('kundennr') |
Query-Parameter, Formularwert (application/x-www-form-urlencoded) oder HTTP-Header. Getrimmt, leer wenn nicht gesendet.
|
oReader.Path('nr') |
Wert eines Platzhalters aus dem Pfad-Template |
oReader.Form('bemerkung') |
Formularfeld einer multipart/form-data-Übertragung
|
oReader.Subject() |
Subject (sub) des vorgelegten Tokens
|
oReader.Claim('tenant') |
Eigener Claim des vorgelegten Tokens, als Text |
oReader.TraceId() |
Kennung der Anfrage, gleich dem Header X-Trace-Id der Antwort
|
oReader.Offset() |
UTC-Offset des Servers, z.B. +01:00 |
oReader.HasBody() |
Wurde ein JSON-Körper gesendet? |
oReader.UploadPath(), UploadName(), UploadType(), UploadSha() |
Hochgeladene Datei, siehe Datei-Uploads |
Was der Server vorher filtert:
- Die Header
authorization,cookie,proxy-authorization,x-forwarded-for,x-real-ip,apikeyundapi_keyerreichen das Skript nicht. - Namen, die mit
_OBS_beginnen, sind dem Server vorbehalten. Header und Query-Parameter mit solchen Namen verwirft er. - Werte aus Header, Query, Pfad und Formular kürzt er nach 1024 Zeichen.
- Null-Bytes und Steuerzeichen entfernt er. Tabulator, CR und LF bleiben.
cKundenNr := oReader.Param('kundennr');
if (not Empty(cKundenNr)) then begin
// ...
end;
Der Körper
Den JSON-Körper liest oReader über Pfade. Es gibt keine Unterobjekte, keine Typumwandlung und nichts freizugeben.
| Aufruf | Bedeutung |
|---|---|
oReader.Str('betreff', cWert) |
Liest den Wert. Rückgabe Boolean: War das Feld da? Fehlt es, bleibt die Variable unverändert. |
oReader.Int('menge', nWert) |
dito, Ganzzahl |
oReader.Num('preis', nWert) |
dito, Kommazahl. Den Dezimalpunkt aus JSON liest der Reader richtig. |
oReader.Bool('aktiv', lWert) |
dito, Boolean |
oReader.NumDef('rabatt', nWert, 0) |
wie Num, mit Vorgabewert
|
oReader.Has('feld') |
Ist das Feld vorhanden, auch mit null?
|
oReader.Count('zeiten') |
Anzahl Einträge einer Liste, 0 wenn keine Liste |
oReader.IsArr('zeiten'), oReader.IsObj('zeiten[0]') |
Ist der Wert eine Liste bzw. ein Objekt? |
oReader.Keys() |
Alle Feldnamen der obersten Ebene, in Kommas eingefasst |
Verschachtelung steht im Pfad: Punkt für Felder, eckige Klammern für Listen.
procedure Put(oReader: TxRestReader; oWriter: TxRestWriter);
var cVon: string;
nAnz: Integer;
nI : Integer;
begin
nAnz := oReader.Count('zeiten');
for nI := 0 to nAnz - 1 do begin
if (oReader.Str('zeiten[' + IntToStr(nI) + '].von', cVon)) then begin
// ... cVon verarbeiten ...
end;
end;
end;
"feld": null liefert oReader.Str('feld', cWert) true und einen leeren Wert, bei fehlendem Feld false. So unterscheidet ein PATCH „Feld leeren“ von „Feld nicht ändern“.Regeln für den Körper:
- Der Server liest den Körper als UTF-8.
- Nur ein JSON-Objekt als Wurzel gilt als Körper. Eine Liste als Wurzel oder ungültiges JSON ergibt keinen Körper:
HasBody()ist false, jeder Leser liefert false. Der Server antwortet in diesem Fall nicht mit 400. Prüfen Sie Pflichtfelder deshalb im Skript. - Ein Körper ohne Datei darf höchstens 10 MB groß sein, auch nach dem Entpacken. Darüber antwortet der Server mit 413, das Skript läuft nicht. Gepackte Körper: HTTP-Schnittstelle.
Werte des Servers
Diese Werte setzt der Server. Ein Client kann sie nicht überschreiben.
| Aufruf | Inhalt |
|---|---|
oReader.Param('_OBS_SERVER_TIME') |
Serverzeit nach ISO 8601 mit UTC-Offset, z.B. 2026-11-17T09:12:33+01:00 |
oReader.Offset() |
Nur der Offset daraus, z.B. +01:00. Er geht in die Zeitfunktionen. |
oReader.TraceId() |
Kennung der Anfrage |
oReader.Param('_OBS_JWT_EXP_SEC') |
Laufzeit des Access-Tokens in Sekunden (Lebenszeit (Min) × 60) |
Bei Zugängen mit JWT-Authentifizierung stehen zusätzlich die Werte des Tokens bereit: oReader.Subject(), oReader.Claim('<name>'), oReader.Param('_OBS_JWT_ID'), oReader.Param('_OBS_JWT_AUDIENCE') sowie die Sitzungskennungen sid und rid. Die vollständige Liste steht unter Anmeldung mit JWT.
Pfad-Parameter
Enthält das Pfad-Template Platzhalter, liefert oReader.Path deren Werte:
| Pfad-Template | Zugriff im Skript |
|---|---|
/beispiel/auftraege/{nr} |
oReader.Path('nr')
|
/beispiel/auftraege/{nr}/module/{code} |
oReader.Path('nr'), oReader.Path('code')
|
Der Name ist geschützt: Ein Client kann einen Pfadwert nicht über Query oder Header unterschieben. Der Wert stammt aber aus der URL des Clients. Prüfen Sie ihn wie jede andere Eingabe, z.B. ob der Auftrag zum Mandanten im Token gehört. Ein vollständiges Beispiel zeigt Beispiel 4.
Datei-Uploads
Hat der Endpunkt den Haken Datei-Upload, nimmt der Server Dateien entgegen und legt sie in einem temporären Verzeichnis ab. Das Skript erhält die Datei über diese Aufrufe:
| Aufruf | Inhalt |
|---|---|
oReader.UploadPath() |
Vollständiger Pfad der temporären Datei auf dem Server |
oReader.UploadName() |
Originaler Dateiname |
oReader.UploadType() |
Content-Type der Datei, kleingeschrieben. Ohne Angabe des Clients application/octet-stream.
|
oReader.UploadSha() |
SHA-256 der gespeicherten Datei, hexadezimal in Kleinbuchstaben. Vergleichen Sie damit eine Prüfsumme, die der Client mitsendet. |
- Beide Übertragungswege liefern dieselben Werte:
multipart/form-dataund der fortsetzbare Upload mitContent-Range. Beim fortsetzbaren Upload läuft das Skript erst, wenn die Datei vollständig ist. - Ohne Dateinamen weist der Server den Upload mit 400 ab, das Skript läuft nicht.
UploadPath()undUploadName()sind im Skript also immer gefüllt. - Ein Upload-Körper wird nicht als JSON gelesen.
HasBody()ist false. - Zusatzangaben eines Formulars liest das Skript mit
oReader.Form('<name>'). Das sind die Partien ohnefilename=. Vom Namen bleiben nur Buchstaben, Ziffern und Unterstrich, höchstens 40 Zeichen. - Beim fortsetzbaren Upload gibt es keine Formularfelder. Zusatzangaben kommen dort über Query-Parameter oder Header.
- Ein Upload an einen Endpunkt ohne Datei-Upload beantwortet der Server mit 415. Überschreitet die Übertragung die maximale Dateigröße (MB) des Endpunkts, antwortet er mit 413.
Übertragung, Header und Statuscodes: Datei-Upload. Ein vollständiges Beispiel zeigt Beispiel 6.
Die Antwort schreiben: oWriter
Der Writer schreibt der Reihe nach: Jeder Aufruf hängt ein Feld an der Stelle an, an der er steht. Die äußere Klammer setzt der Server. Schreibt das Skript nichts, lautet die Antwort {}. Ohne weitere Angabe ist der Status 200 und der Content-Type application/json; charset=utf-8.
procedure Get(oReader: TxRestReader; oWriter: TxRestWriter);
begin
oWriter.Str('wert_string', '123');
oWriter.Int('wert_int' , 456);
end;
| Aufruf | Ergebnis |
|---|---|
oWriter.Str('name', cWert) |
Zeichenkette, immer maskiert |
oWriter.StrN('name', cWert) |
wie Str, aber null statt einer leeren Zeichenkette
|
oWriter.Int('anz', nWert) |
Ganzzahl |
oWriter.Num('preis', nWert, 2) |
Kommazahl mit fester Stellenzahl. Immer mit Dezimalpunkt, unabhängig von den Ländereinstellungen des Servers. |
oWriter.Bool('aktiv', lWert) |
true oder false
|
oWriter.Null('lat') |
ausdrücklich null
|
oWriter.ObjBegin('kunde') … oWriter.ObjEnd |
Unterobjekt |
oWriter.ArrBegin('dateien') … oWriter.ArrEnd |
Liste |
oWriter.RootArr() |
Die Wurzel ist eine Liste statt eines Objekts. Steht vor dem ersten Feld. Ein ArrEnd gehört nicht dazu.
|
oWriter.Raw('meta', cJson) |
Fertiges JSON-Fragment einbetten, siehe unten |
In einer Liste hat ein Eintrag keinen Namen. Der leere Feldname steht dafür:
oWriter.ArrBegin('dateien');
while (not qDat.EoF) do begin
oWriter.ObjBegin('');
oWriter.Str ('uid' , qDat.A2C('f_uid'));
oWriter.Int ('bytes' , qDat.A2I('f_bytes'));
oWriter.StrN('kategorie', AllTrim(qDat.A2C('f_kat'))); // null, wenn leer
oWriter.ObjEnd;
qDat.Next();
end;
oWriter.ArrEnd;
Ein Name in einer Liste, ein fehlender Name in einem Objekt und eine Ebene, die am Ende der Methode noch offen ist, sind Strukturfehler. Der Server antwortet dann mit 500 und nennt die Stelle im Protokoll. Halbes JSON liefert er nie aus.
procedure DateienSchreiben(oWriter: TxRestWriter; const cNr: string);Raw prüft das Fragment und bettet den Originaltext ein. Ungültiges JSON führt zu einem Serverfehler, der das Feld nennt. Gebraucht wird Raw für gespeicherte, signierte Dokumente: Neu aufgebaut, verlöre das Dokument die signierte Reihenfolge der Felder.
Zeitangaben
Zeitpunkte gehen als ISO 8601 mit Offset über die Leitung. Für die Umwandlung gibt es eigene Funktionen:
| Aufruf | Zweck |
|---|---|
RestIsoFromDate(dWert, cOffset) |
OBS-Zeitpunkt in 2026-09-09T14:12:00+02:00. Leere Zeichenkette bei leerem Datum. |
RestDateFromIso(cWert, cOffset) |
ISO-Zeichenkette in einen OBS-Zeitpunkt in Ortszeit des Servers |
oReader.Offset() |
Der Offset für beide Funktionen |
RestOffsetToMinutes(cOffset) |
Offset in Minuten, für eigene Rechnungen |
Antwort steuern: Statuscode, Header, traceId
Statuscode, Header, Fehler und Dateien setzen eigene Aufrufe des Writers, nicht Felder im Körper.
| Aufruf | Wirkung |
|---|---|
oWriter.Status(201) |
HTTP-Statuscode, z.B. 201, 204, 409 oder 422. Ohne Angabe: 200. Werte außerhalb von 100 bis 599 ignoriert der Server. |
oWriter.Header('ETag', '"7"') |
Beliebiger Header der Antwort, z.B. ETag, Location, Retry-After. Steuerzeichen in Name und Wert entfernt der Server.
|
oWriter.NoBody() |
Kein Körper, für 204 |
oWriter.Error(422, 'VALIDATION_FAILED', 'Feld "menge" fehlt') |
Fertige Fehlerantwort im Format des Servers, siehe Fehlerbehandlung |
oWriter.HasError() |
Steht schon eine Fehlerantwort im Writer? |
oWriter.JwtRevoke('session') |
Sperrt die Sitzung des vorgelegten Tokens, mit 'all' alle Sitzungen des Subjects. Siehe Anmeldung mit JWT.
|
oWriter.SendFile(cPfad, cName, cTyp) |
Eine Datei statt eines JSON-Körpers ausliefern. Die Datei bleibt liegen, der Download ist fortsetzbar. |
oWriter.SendTempFile(cPfad, cName, cTyp) |
Wie SendFile, die Datei wird nach dem Senden gelöscht. Für Ergebnisse, die je Abruf entstehen.
|
Dateiantworten beschreibt Datei-Download.
Jede Antwort trägt den Header X-Trace-Id. Dieselbe Kennung liefert oReader.TraceId(), und sie steht in jeder Fehlerzeile des Protokolls. So findet der Betreiber einen Fehler ohne Zugriff auf das Gerät.
Setzt das Skript den Header Content-Encoding selbst, packt der Server die Antwort nicht noch einmal.
Beispiel: Anlegen mit 201, Location und ETag
procedure Post(oReader: TxRestReader; oWriter: TxRestWriter);
var cNeueNr: string;
begin
// ... Datensatz anlegen, neue Nummer ermitteln ...
oWriter.Str('nr', cNeueNr);
oWriter.Status(201);
oWriter.Header('Location', '/beispiel/tickets/' + cNeueNr);
oWriter.Header('ETag' , '"1"');
end;
Beispiel: Versionsprüfung mit ETag und If-Match
Mit Statuscode, Header und dem Header If-Match der Anfrage führt das Skript je Datensatz einen Versionszähler. Veraltete Schreibzugriffe lehnt es mit 409 ab. Clients senden den ETag meist in Anführungszeichen ("7"), manche ohne.
procedure Put(oReader: TxRestReader; oWriter: TxRestWriter);
var nAktuell: Integer;
cETag : string;
cIfMatch: string;
begin
nAktuell := TicketVersion(oReader.Path('nr')); // eigene Funktion
cETag := '"' + IntToStr(nAktuell) + '"';
cIfMatch := AllTrim(oReader.Param('if-match'));
if (cIfMatch <> cETag) and (cIfMatch <> IntToStr(nAktuell)) then begin
// Der gültige ETag gehört auch an die Ablehnung,
// sonst scheitert der nächste Versuch des Clients wieder.
oWriter.Header('ETag', cETag);
oWriter.Error(409, 'VERSION_CONFLICT', 'Der Datensatz wurde zwischenzeitlich geändert');
exit;
end;
// ... speichern, Version hochzählen ...
oWriter.Header('ETag', '"' + IntToStr(nAktuell + 1) + '"');
end;
VERSION_CONFLICT ist hier ein eigener Code des Skripts. Der Server selbst verwendet für 409 den Code CONFLICT.
Transaktion
POST, PUT, PATCH und DELETE laufen in einer Datenbanktransaktion. Darin liegen alle Schreibvorgänge des Skripts und das Ergebnis der Idempotenz-Prüfung.
| Ende des Skripts | Wirkung |
|---|---|
| Status unter 400 | Alle Änderungen werden festgeschrieben. |
| Status 400 oder höher | Alle Änderungen werden zurückgerollt. |
| Exception oder Skriptfehler | Alle Änderungen werden zurückgerollt, der Client erhält 500. |
- Ablehnen ist gefahrlos. Ein Skript darf schreiben und danach mit
oWriter.Errorabbrechen. In der Datenbank bleibt nichts davon. - Auch eigene Protokollzeilen, die das Skript in eine Tabelle schreibt, werden bei Status 400 oder höher zurückgerollt. Die Fehlerzeile des Servers in
RESTSRV_PROTObleibt, siehe Fehler im Protokoll. - Eigene Transaktionen im Skript (
StartTransaction,Commit) sind wirkungslos. Sie liegen innerhalb der Transaktion des Servers, und nur deren Ende zählt. - Teilweise Schreibvorgänge bleiben nur stehen, wenn das Skript einen Schreibfehler übergeht und mit Status unter 400 antwortet. Werten Sie deshalb jeden Schreibvorgang aus, siehe Schreibfehler erkennen.
GET läuft ohne Transaktion. Schreibt ein GET-Skript, wirkt jeder Schreibvorgang sofort und bleibt auch bei einer Fehlerantwort stehen.
Idempotenz
Bei POST, PUT, PATCH und DELETE fängt der Server doppelte Sendungen über den Header Idempotency-Key ab. Das Skript braucht dafür keine eigene Logik. Fehlt der Header, läuft das Skript nicht.
Für das Skript gilt:
- Eine Wiederholung mit gespeicherter Antwort beantwortet der Server selbst. Das Skript läuft dabei nicht.
- Gespeichert wird nur eine Antwort mit Status 2xx ohne Datei. Was sie enthält, ist eingefroren. Schreiben Sie die Antwort deshalb vollständig.
- Melden Sie fachliche Ablehnungen mit 4xx (z.B. 404, 409, 422), nicht mit 200 und Fehlertext. Eine 2xx-Antwort würde gespeichert, und der Client bekäme sie bei jedem weiteren Versuch erneut.
- Nach Status 400 oder höher ist alles zurückgerollt und der Key wieder frei. Eine Wiederholung ist gefahrlos.
Den Ablauf aus Sicht des Clients beschreibt HTTP-Schnittstelle.
Fehlerbehandlung im Skript
Löst das Skript eine Exception aus oder lässt es sich nicht übersetzen, antwortet der Server mit 500 INTERNAL_ERROR und einer allgemeinen Meldung. Den Fehlertext schreibt er ins Protokoll. Der Client sieht keine internen Details.
Für einen gezielten Fehler gibt es einen Aufruf. Er erzeugt dieselbe Fehlerantwort wie die Fehler des Servers: Statuscode, code, message, uid und traceId.
procedure Post(oReader: TxRestReader; oWriter: TxRestWriter);
begin
if (Empty(oReader.Param('kundennr'))) then begin
oWriter.Error(422, 'VALIDATION_FAILED', 'Parameter "kundennr" fehlt');
exit;
end;
// ...
end;
Error verwirft einen schon begonnenen Körper und setzt die Fehlerantwort. Ein Skript darf also Felder schreiben und danach noch abbrechen. Nur eine noch offene Ebene (ObjBegin ohne ObjEnd) bleibt ein Strukturfehler.Codes, die auch der Server verwendet: VALIDATION_FAILED (422), NOT_FOUND (404), FORBIDDEN_ROLE (403), CONFLICT (409). Eigene, fachlich sprechende Codes sind erlaubt. Halten Sie sie stabil, denn Clients richten ihre Reaktion danach aus. Alle Codes des Servers: HTTP-Schnittstelle.
Fehler im Protokoll
Jede Antwort des Skripts mit Status 400 oder höher schreibt der Server als eine Zeile nach RESTSRV_PROTO, mit code und message aus dem Fehlerobjekt:
Fehler VALIDATION_FAILED [422 POST /beispiel/tickets] [trace=<traceId>]: Parameter "kundennr" fehlt
Daraus folgt:
- Verwenden Sie
oWriter.Error. Ohne Fehlerobjekt steht im Protokoll nur der Code aus dem Status und der Text „Antwort ohne error-Objekt“. - Schreiben Sie keine sensiblen Daten in die
message. Sie steht im Protokoll und geht an den Client. - Schreiben Sie für dieselbe Ablehnung keine eigene Protokollzeile. Der Server hat sie bereits.
Protokoll und Suche über die traceId: Betrieb und Fehlersuche.
Datenbankzugriff
Im Skript beginnt jede Datenbankfunktion mit oDB, ohne weiteren Parameter davor. Der Abfragetyp für DB_SOpen ist TxFQuery.
| Zweck | Aufruf |
|---|---|
| Lesen | DB_SOpen(oDB, cSql, qDat), dann qDat.EoF, qDat.Next(), qDat.A2C('feld'), A2I, A2F, A2D, A2UID(), am Ende DB_Close(qDat)
|
| Neu anlegen | qUpd := qSqlInit(oDB, 'TAB'), qUpd.qSet('feld', wert), qUpd.SaveData(NEW_RECORD) auswerten, qSqlFree(qUpd)
|
| Ändern | qUpd := qSqlInit(oDB, 'TAB'), qUpd.qSet('sys_uid', cUid), weitere qSet, qUpd.SaveData(UPDATE_RECORD) auswerten, qSqlFree(qUpd)
|
| Direkt ausführen | DB_SqlExec(oDB, cSql)
|
| Existenz prüfen | DB_LSeek(oDB, 'TAB', cWhere)
|
| Werte einsetzen (Pflicht) | DB_SQLVal(wert)
|
Ändern: qSqlInit statt qSqlRead
Zum Ändern eines Satzes nehmen Sie ebenfalls qSqlInit. Die sys_uid adressiert den Satz:
qUpd := qSqlInit(oDB, 'TICKETS');
qUpd.qSet('sys_uid' , cUid); // adressiert den vorhandenen Satz
qUpd.qSet('ti_status', '9');
Speichern(qUpd, UPDATE_RECORD, 'Ticket'); // siehe Schreibfehler erkennen
qSqlRead ist dafür die falsche Wahl:
- Es liest zuerst den kompletten Satz. Das kostet einen zusätzlichen Zugriff.
- Es schreibt nur Änderungen. Ist der neue Wert gleich dem alten, liefert
SaveDataFalse, genau wie bei einem echten Fehler.
sys_uid legt qSqlInit einen neuen Satz an. Setzen Sie die sys_uid bei jeder Änderung.Eine einzige Abfrage auf die sys_uid liefert Existenzprüfung und Schreibziel zugleich:
cUid := '';
if (DB_SOpen(oDB, 'SELECT sys_uid FROM TICKETS WHERE ' + cWhere + ' LIMIT 1', qDat)) then begin
if (not qDat.EoF) then begin
cUid := qDat.A2UID();
end;
end;
DB_Close(qDat);
if (not Empty(cUid)) then begin
// ändern: qSqlInit mit sys_uid
end else begin
// anlegen: qSqlInit ohne sys_uid
end;
Mehrere Felder sind ein Schreibvorgang
Ein qSqlInit-Objekt nimmt beliebig viele qSet an und schreibt sie mit einem SaveData. Felder derselben Zeile gehören in dasselbe Objekt:
// FALSCH: je Feld ein Aufruf mit eigener Abfrage und eigenem Schreibvorgang
FeldSetzen(cUid, 'ti_status', '9');
FeldSetzen(cUid, 'ti_grund' , cGrund);
FeldSetzen(cUid, 'ti_von' , cBenutzer);
// RICHTIG: ein Schreibobjekt, ein SaveData
qUpd := qSqlInit(oDB, 'TICKETS');
qUpd.qSet('sys_uid' , cUid);
qUpd.qSet('ti_status', '9');
qUpd.qSet('ti_grund' , cGrund);
qUpd.qSet('ti_von' , cBenutzer);
Speichern(qUpd, UPDATE_RECORD, 'Ticket');
Einzeln geschriebene Felder kosten je Feld eine Abfrage und einen Schreibvorgang. Wird nichts gesetzt, geben Sie das Schreibobjekt mit qSqlFree frei, statt ein leeres SaveData abzusetzen.
Keine Abfrage je Zeile
Was in einer Liste je Zeile nachgeschlagen wird, kostet N Abfragen für eine Antwort. Bei fünfzig Aufträgen sind das fünfzig Abfragen für ein einziges Feld. Der Ausweg:
- Werte aus einer 1:1-Beziehung über einen
LEFT JOINmitnehmen. Bei einem eindeutigen Index auf dem Join-Feld vervielfacht er die Zeilen nicht. - Einzelwerte aus einer 1:n-Beziehung über eine Unterabfrage in der SELECT-Liste holen, nicht über einen Join.
- Eine echte Unterliste (Positionen, Dateien) nur nachladen, wenn ein Zählfeld in der Hauptabfrage sagt, dass es eine gibt.
Schreibfehler erkennen
SaveData liefert einen Boolean, und der ist die einzige Fehlermeldung. Auch der Parameter ist ein Boolean: NEW_RECORD und UPDATE_RECORD sind Wahrheitswerte. Scheitert das Schreiben in der Datenbank (doppelter Wert in einem eindeutigen Index, zu langer Wert, fehlende Spalte), dann
- löst das keine Exception aus,
- steht nichts in
RESTSRV_PROTO, - läuft das Skript weiter und meldet den Erfolg, den es selbst schreibt.
Prüfen Sie den Rückgabewert deshalb immer. Am einfachsten über eine kleine Prozedur in der gemeinsamen Bibliothek:
procedure Speichern(qUpd: TqSQL; lNeu: Boolean; const cWas: string);
var lOk: Boolean;
begin
lOk := qUpd.SaveData(lNeu);
qSqlFree(qUpd); // auch im Fehlerfall freigeben
if (not lOk) then begin
raise Exception.Create('Schreiben fehlgeschlagen: ' + cWas);
end;
end;
// Aufruf statt SaveData und qSqlFree:
qUpd := qSqlInit(oDB, 'TICKETS');
qUpd.qSet('ti_betreff', cBetreff);
Speichern(qUpd, NEW_RECORD, 'Ticket');
Die Exception fängt der Server. Er schreibt den Text ins Protokoll, rollt alle Änderungen der Anfrage zurück und antwortet mit 500. Der Idempotency-Key wird frei, der Client kann wiederholen.
Anmeldeskript (JWT)
Zugänge mit JWT-Authentifizierung haben ein eigenes Anmeldeskript. Sie bearbeiten es in der Zugänge-Liste mit F7. Es enthält die Methoden Authenticate und Refresh mit derselben Signatur wie ein Endpunkt-Skript. Rückgabefelder, Beispiel und Fehlerfälle stehen unter Anmeldung mit JWT.
Gemeinsamen Code auslagern
Logik, die mehrere Endpunkte brauchen, muss nicht in jedes Skript kopiert werden. Eine Direktive lädt beim Übersetzen einen Textbaustein aus einer Tabelle nach:
{$L T="restsrv_endpoints" I="re_pathtemplate" V="/meinapp/lib" F="re_script"}
| Attribut | Bedeutung |
|---|---|
T |
Tabelle, aus der geladen wird |
I |
Spalte, über die gesucht wird |
V |
Wert, der in dieser Spalte stehen muss |
F |
Spalte, deren Inhalt an dieser Stelle eingesetzt wird |
Die Direktive steht üblicherweise direkt unter dem Kopfkommentar des Skripts. Eine Funktion aus der Bibliothek rufen Sie danach auf wie eine im Skript selbst geschriebene.
Bibliothek als eigener Endpunkt
Am wenigsten Verwaltung macht eine Bibliothek als eigener Endpunkt:
- Legen Sie einen Endpunkt mit eigenem Pfad-Template an, z.B.
/meinapp/lib. - Schreiben Sie den Quelltext der Bibliothek in das Skript dieses Endpunkts.
- Vergeben Sie für diesen Endpunkt keine Berechtigung. Ein Aufruf von außen endet dann mit 403.
- Fügen Sie in jedem nutzenden Skript die Direktive ein.
Eine Änderung an der Bibliothek gilt für alle Skripte, die sie einbinden.
Verfügbare Bibliotheken
Im Skript stehen die OBS-Funktionen bereit, die Sie aus Makros kennen:
- Zeichenketten, Datum, Zahlen und Konstanten wie
CRLF,SINGELQUOTEundMINDATETIME - Datenbank: lesen, schreiben, direkt ausführen
- Dateifunktionen
- Fachfunktionen, z.B. zu Aufträgen, Reparaturaufträgen, Angeboten, Einkauf und Artikelbewegungen
- Reader, Writer und die Zeitfunktionen dieser Seite
Eine JSON-Bibliothek braucht ein Endpunkt-Skript nicht. Der Reader liest den Körper, der Writer erzeugt die Antwort.
Fallstricke im Skript
| Stolperstein | Richtig |
|---|---|
| Datenbankfunktion mit zusätzlicher Kennung als erstem Parameter, wie im Delphi-Code | Im Skript ohne Kennung: DB_SOpen(oDB, cSql, qDat), qSqlInit(oDB, 'TAB'), qSqlRead(oDB, 'TAB', cWhere)
|
Generics, z.B. oReader.Str<T>(…) |
Gibt es in der Skriptsprache nicht. Je Typ ein eigener Leser: Str, Int, Num, Bool.
|
| Hilfsfunktion, die ein JSON-Fragment als Zeichenkette zurückgibt | Den Writer als Parameter übergeben und an der richtigen Stelle hineinschreiben |
oWriter.ArrEnd nach RootArr |
RootArr öffnet keine Ebene. Ein ArrEnd dazu ist ein Strukturfehler.
|
Zahlen selbst formatieren, z.B. mit NStr |
NStr liefert deutsche Schreibweise mit Tausenderpunkt. Für JSON oWriter.Num('preis', nWert, 2) verwenden.
|
fVal auf eine JSON-Zahl |
oReader.Num bzw. oReader.NumDef verwenden. Sie lesen den Dezimalpunkt richtig.
|
EMPTY_DATE für ein leeres Datum |
EMPTY_DATE ist im Skript eine Zeichenkette. Für Datumsvariablen und Vergleiche MINDATETIME verwenden.
|
TStringList für Zwischenlisten |
In Skripten unzuverlässig. Kleine Mengen als Zeichenkette mit Trennzeichen führen ('|' + wert + '|') und mit Pos prüfen.
|
| Vorgabewerte für Parameter eigener Funktionen | Werden nicht unterstützt. Alle Parameter ausschreiben. |
qUpd.SaveData(…) als Anweisung ohne Auswertung |
Rückgabewert immer auswerten, siehe Schreibfehler erkennen |
| Je Feld ein eigener Aufruf zum Setzen | Ein qSqlInit-Objekt, alle qSet, ein SaveData, siehe Mehrere Felder
|
| Ein Wert je Zeile nachgeschlagen | LEFT JOIN (1:1) oder Unterabfrage (1:n), siehe Keine Abfrage je Zeile
|
Ausgabeparameter vom Typ var … : TDateTime |
Bringt die Skriptausführung zum Absturz, und zwar erst beim Lesen des Werts. var string, var Integer und var Double laufen. Zeitpunkte als ISO-Zeichenkette zurückgeben und beim Aufrufer wandeln.
|
Skript-Cache
Der Server hält die Endpunkte samt Skript bis zu 60 Sekunden im Zwischenspeicher. Eine Änderung am Skript wirkt deshalb spätestens nach 60 Sekunden. Nach einem Neustart des Dienstes wirkt sie sofort.
Beispiel
Ein Endpunkt mit dem Pfad-Template /beispiel/tickets/{nr} liest ein Ticket und ändert seinen Status. Tabelle und Felder stehen für Ihre eigenen; Speichern ist die Prozedur aus Schreibfehler erkennen.
procedure Get(oReader: TxRestReader; oWriter: TxRestWriter);
var cSql : string;
qTick: TxFQuery;
lGef : Boolean;
begin
cSql := 'SELECT ti_nr, ti_betreff, ti_status FROM TICKETS' +
' WHERE ti_nr = ' + DB_SQLVal(oReader.Path('nr'));
lGef := false;
if (DB_SOpen(oDB, cSql, qTick)) then begin
if (not qTick.EoF) then begin
lGef := true;
oWriter.Str('nr' , AllTrim(qTick.A2C('ti_nr')));
oWriter.Str('betreff', AllTrim(qTick.A2C('ti_betreff')));
oWriter.Str('status' , AllTrim(qTick.A2C('ti_status')));
end;
end;
DB_Close(qTick);
if (not lGef) then begin
oWriter.Error(404, 'NOT_FOUND', 'Ticket nicht gefunden');
end;
end;
procedure Put(oReader: TxRestReader; oWriter: TxRestWriter);
var cNr : string;
cStatus: string;
cUid : string;
cSql : string;
qTick : TxFQuery;
qUpd : TqSQL;
begin
cNr := oReader.Path('nr');
cStatus := '';
if (not oReader.Str('status', cStatus)) then begin
oWriter.Error(422, 'VALIDATION_FAILED', 'Feld "status" fehlt');
exit;
end;
cUid := '';
cSql := 'SELECT sys_uid FROM TICKETS WHERE ti_nr = ' + DB_SQLVal(cNr);
if (DB_SOpen(oDB, cSql, qTick)) then begin
if (not qTick.EoF) then begin
cUid := qTick.A2UID();
end;
end;
DB_Close(qTick);
if (Empty(cUid)) then begin
oWriter.Error(404, 'NOT_FOUND', 'Ticket nicht gefunden');
exit;
end;
qUpd := qSqlInit(oDB, 'TICKETS');
qUpd.qSet('sys_uid' , cUid);
qUpd.qSet('ti_status', cStatus);
Speichern(qUpd, UPDATE_RECORD, 'Ticket');
oWriter.Str('nr' , cNr);
oWriter.Str('status', cStatus);
end;
Aufruf des PUT mit curl:
curl -X PUT "https://obs.example.com:8443/beispiel/tickets/4711" \
-H "apikey: abcdef-ghij-klmn-opqr-stuvwx" \
-H "Idempotency-Key: 3f2b8c1e-7d4a-4e9b-9c0f-5a6d2e1b8f47" \
-H "Content-Type: application/json; charset=utf-8" \
-d '{"status": "9"}'
Weitere vollständige Beispiele:
- Beispiel 1: Daten-Abruf mit JWT
- Beispiel 3: Datensatz anlegen mit JSON-Body
- Beispiel 4: Pfad-Parameter im Routing
- Beispiel 5: Schreibzugriff mit Statuscodes, ETag und Idempotenz
- Beispiel 6: Datei-Upload und Ablage