OBS/Kostenpflichtige Module/REST-Server/Beispiele/Pfad-Parameter: Unterschied zwischen den Versionen
Böhrer (Diskussion | Beiträge) Die Seite wurde neu angelegt: „Скачать [http://fstoexua.ru/film/136/ Пираты карибского Моря 5 2017 Мертвецы смотреть] Карибского Моря…“ |
Überschrift an den neuen Titel angeglichen, Links auf die neuen Titel umgestellt, Umlaute in Kommentaren und Meldungstexten [Volltext ersetzt] |
||
| (9 dazwischenliegende Versionen von 2 Benutzern werden nicht angezeigt) | |||
| Zeile 1: | Zeile 1: | ||
{{Vorlage:Kostenpflichtige Module}} | |||
{{Seitentyp|Referenz}} | |||
= Pfad-Parameter = | |||
Dieses Beispiel zeigt das Routing über '''Pfad-Templates''' mit Platzhaltern. So entstehen sprechende Adressen, wie sie Entwickler von modernen REST-Schnittstellen erwarten. Eine Auftrags-Ressource wird über drei Endpunkte abgebildet: | |||
{| class="wikitable" | |||
! Methode und Pfad !! Zweck | |||
|- | |||
| <code>GET /orders</code> || Liste aller offenen Aufträge | |||
|- | |||
| <code>GET /orders/{uid}</code> || Einzelner Auftrag über seine UID | |||
|- | |||
| <code>PUT /orders/{uid}/modules/{code}</code> || Status eines Auftrags-Moduls ändern | |||
|} | |||
Die Platzhalter <code>{uid}</code> und <code>{code}</code> stehen im Skript über <code>oReader.Path('uid')</code> bzw. <code>oReader.Path('code')</code> bereit. | |||
== Einrichtung in OBS == | |||
* '''Server-Profil:''' TLS-Profil ''Public-API'' mit einer Bindung auf Port 443 | |||
* '''Zugang:''' ''Orders-Client'' mit '''API-Key''', berechtigt für die drei Endpunkte | |||
* '''Endpunkte''', alle mit '''Server''' ''Public-API'': | |||
{| class="wikitable" | |||
! Pfad-Template !! Skriptmethode | |||
|- | |||
| <code>/orders</code> || <code>Get</code> (Liste) | |||
|- | |||
| <code>/orders/{uid}</code> || <code>Get</code> (einzelner Auftrag) | |||
|- | |||
| <code>/orders/{uid}/modules/{code}</code> || <code>Put</code> | |||
|} | |||
Jeder Endpunkt hat sein eigenes Skript und seine eigene Berechtigung. Regeln für Templates und Vorrang: [[OBS/Kostenpflichtige Module/REST-Server/Endpunkte|Endpunkte]]. | |||
== Gemeinsamer Helfer == | |||
Die Skripte der Liste und des einzelnen Auftrags schreiben dieselben Felder. Der Helfer bekommt den Writer und schreibt in das Objekt, das gerade offen ist: einmal in einen Listeneintrag, einmal in die Wurzel der Antwort. Er steht in beiden Skripten oder einmal in einer ausgelagerten Bibliothek, siehe [[OBS/Kostenpflichtige Module/REST-Server/Scripting|Scripting]]. | |||
<syntaxhighlight lang="delphi"> | |||
// Schreibt die Felder eines Auftrags in das Objekt, das der Aufrufer geöffnet hat | |||
procedure _OrderFelder(oWriter: TxRestWriter; qOrder: TxFQuery; | |||
const cOffset: string); | |||
begin | |||
oWriter.Str ('uid' , qOrder.A2UID()); | |||
oWriter.Str ('nr' , qOrder.A2C('au_nr')); | |||
oWriter.Str ('kunde' , qOrder.A2C('au_kunde')); | |||
oWriter.Str ('status', qOrder.A2C('au_status')); | |||
// Zeitpunkt als ISO 8601 mit Offset des Servers; leeres Datum ergibt null | |||
oWriter.StrN('aenderung', RestIsoFromDate(qOrder.A2D('au_aend_dat'), cOffset)); | |||
end; | |||
</syntaxhighlight> | |||
== Endpunkt-Skript 1: <code>GET /orders</code> == | |||
<syntaxhighlight lang="delphi"> | |||
procedure Get(oReader: TxRestReader; oWriter: TxRestWriter); | |||
var cSql : string; | |||
qData : TxFQuery; | |||
cOffset: string; | |||
begin | |||
cOffset := oReader.Offset(); | |||
// Liste: RootArr vor der Abfrage, kein Treffer ergibt eine leere Liste | |||
oWriter.RootArr(); | |||
cSql := 'SELECT * FROM AUFTRAEGE' + | |||
' WHERE au_status <> ' + DB_SqlVal('9', 'C') + | |||
' ORDER BY au_nr'; | |||
if (DB_SOpen(oDB, cSql, qData)) then begin | |||
while (not qData.EoF) do begin | |||
oWriter.ObjBegin(''); | |||
_OrderFelder(oWriter, qData, cOffset); | |||
oWriter.ObjEnd; | |||
qData.Next(); | |||
end; | |||
end; | |||
DB_Close(qData); | |||
end; | |||
</syntaxhighlight> | |||
== Endpunkt-Skript 2: <code>GET /orders/{uid}</code> == | |||
<syntaxhighlight lang="delphi"> | |||
procedure Get(oReader: TxRestReader; oWriter: TxRestWriter); | |||
var cUid : string; | |||
cSql : string; | |||
qData : TxFQuery; | |||
lGefunden: Boolean; | |||
cOffset : string; | |||
begin | |||
// Der Wert kommt aus der URL des Clients. DB_SqlVal schützt die Abfrage, | |||
// ein unbekannter Wert führt zu 404. | |||
cUid := oReader.Path('uid'); | |||
cOffset := oReader.Offset(); | |||
lGefunden := false; | |||
cSql := 'SELECT * FROM AUFTRAEGE WHERE sys_uid = ' + DB_SqlVal(cUid, 'C'); | |||
if (DB_SOpen(oDB, cSql, qData)) then begin | |||
if (not qData.EoF) then begin | |||
_OrderFelder(oWriter, qData, cOffset); | |||
lGefunden := true; | |||
end; | |||
end; | |||
DB_Close(qData); | |||
if (not lGefunden) then begin | |||
oWriter.Error(404, 'NOT_FOUND', 'Auftrag nicht gefunden'); | |||
end; | |||
end; | |||
</syntaxhighlight> | |||
== Endpunkt-Skript 3: <code>PUT /orders/{uid}/modules/{code}</code> == | |||
<code>PUT</code> läuft in einer Datenbanktransaktion. Endet das Skript mit einem Status ab 400, nimmt der Server alle Änderungen zurück. | |||
<syntaxhighlight lang="delphi"> | |||
procedure Put(oReader: TxRestReader; oWriter: TxRestWriter); | |||
var cUid : string; | |||
cCode : string; | |||
cStatus: string; | |||
cSql : string; | |||
qChk : TxFQuery; | |||
qMod : TqSQL; | |||
cModUid: string; | |||
lOk : Boolean; | |||
begin | |||
// Beide Pfad-Parameter | |||
cUid := oReader.Path('uid'); | |||
cCode := oReader.Path('code'); | |||
// Nutzdaten aus dem JSON-Körper | |||
cStatus := ''; | |||
oReader.Str('status', cStatus); | |||
if (Empty(cStatus)) then begin | |||
oWriter.Error(422, 'VALIDATION_FAILED', 'Feld "status" fehlt'); | |||
exit; | |||
end; | |||
// Eine Abfrage auf die sys_uid liefert Existenzprüfung und Schreib-Index | |||
cSql := 'SELECT sys_uid FROM AUFTRAG_MODULE' + | |||
' WHERE am_auftrag = ' + DB_SqlVal(cUid, 'C') + | |||
' AND am_code = ' + DB_SqlVal(cCode, 'C') + ' LIMIT 1'; | |||
cModUid := ''; | |||
if (DB_SOpen(oDB, cSql, qChk)) then begin | |||
if (not qChk.EoF) then begin | |||
cModUid := qChk.A2UID(); | |||
end; | |||
end; | |||
DB_Close(qChk); | |||
if (Empty(cModUid)) then begin | |||
oWriter.Error(404, 'NOT_FOUND', 'Modul nicht gefunden'); | |||
exit; | |||
end; | |||
// Ändern: qSqlInit mit sys_uid als Schreib-Index | |||
qMod := qSqlInit(oDB, 'AUFTRAG_MODULE'); | |||
qMod.qSet('sys_uid' , cModUid); | |||
qMod.qSet('am_status', cStatus); | |||
// Ein Schreibfehler wirft keine Exception - nur der Rückgabewert zeigt ihn | |||
lOk := qMod.SaveData(UPDATE_RECORD); | |||
qSqlFree(qMod); | |||
if (not lOk) then begin | |||
oWriter.Error(500, 'INTERNAL_ERROR', 'Status konnte nicht gespeichert werden'); | |||
exit; | |||
end; | |||
oWriter.Str('status', 'ok'); | |||
end; | |||
</syntaxhighlight> | |||
== Test mit curl == | |||
<syntaxhighlight lang="bash"> | |||
# Liste | |||
curl -H "apikey: abcdef-ghij-klmn-opqr-stuvwx" \ | |||
https://obs.example.com/orders | |||
# Einzelner Auftrag (uid als Pfad-Parameter) | |||
curl -H "apikey: abcdef-ghij-klmn-opqr-stuvwx" \ | |||
https://obs.example.com/orders/4711 | |||
# Modul-Status ändern (uid und code als Pfad-Parameter, status im Körper) | |||
curl -X PUT \ | |||
-H "apikey: abcdef-ghij-klmn-opqr-stuvwx" \ | |||
-H "Idempotency-Key: 5b9e2c7a-1f43-4d8e-9a60-c3f1d7e2b845" \ | |||
-H "Content-Type: application/json" \ | |||
-d '{"status":"21"}' \ | |||
https://obs.example.com/orders/4711/modules/A1 | |||
</syntaxhighlight> | |||
Der <code>Idempotency-Key</code> ist bei <code>PUT</code> Pflicht. Ein wiederholter Aufruf mit demselben Schlüssel und demselben Körper liefert die gespeicherte Antwort mit dem Header <code>Idempotent-Replay: true</code>. Regeln: [[OBS/Kostenpflichtige Module/REST-Server/HTTP-Schnittstelle|HTTP-Schnittstelle]]. | |||
== Was zeigt das Beispiel? == | |||
* '''Eine Ressource, mehrere Pfad-Formen''' über getrennte Endpunkte mit eigenem Skript und eigener Berechtigung. | |||
* '''Pfad-Parameter''' werden über <code>{name}</code> im Template erfasst und im Skript mit <code>oReader.Path('name')</code> gelesen. Der Wert kommt vom Client und wird wie jede Eingabe geprüft. | |||
* Die Skriptmethoden haben die Parameter <code>(oReader: TxRestReader; oWriter: TxRestWriter)</code>, Reader zuerst. | |||
* '''Ein Helfer bekommt den Writer''' und schreibt an der Stelle hinein, an der er aufgerufen wird. Derselbe <code>_OrderFelder</code> bedient den Listeneintrag und die Einzelantwort. | |||
* '''Vorrang:''' Ein statisches Segment, z.B. <code>/orders/summary</code>, hätte Vorrang vor <code>/orders/{uid}</code>. | |||
* '''Schreibender Aufruf''' mit <code>Idempotency-Key</code> und Transaktion. | |||
== Siehe auch == | |||
* [[OBS/Kostenpflichtige Module/REST-Server/Endpunkte|Endpunkte]] | |||
* [[OBS/Kostenpflichtige Module/REST-Server/Scripting|Scripting]] | |||
* [[OBS/Kostenpflichtige Module/REST-Server/HTTP-Schnittstelle|HTTP-Schnittstelle]] | |||
* [[OBS/Kostenpflichtige Module/REST-Server/Beispiele/Datensatz anlegen mit JSON-Körper|Beispiel 3: Datensatz anlegen mit JSON-Body]] | |||
Aktuelle Version vom 17. November 2026, 07:23 Uhr
Pfad-Parameter
Dieses Beispiel zeigt das Routing über Pfad-Templates mit Platzhaltern. So entstehen sprechende Adressen, wie sie Entwickler von modernen REST-Schnittstellen erwarten. Eine Auftrags-Ressource wird über drei Endpunkte abgebildet:
| Methode und Pfad | Zweck |
|---|---|
GET /orders |
Liste aller offenen Aufträge |
GET /orders/{uid} |
Einzelner Auftrag über seine UID |
PUT /orders/{uid}/modules/{code} |
Status eines Auftrags-Moduls ändern |
Die Platzhalter {uid} und {code} stehen im Skript über oReader.Path('uid') bzw. oReader.Path('code') bereit.
Einrichtung in OBS
- Server-Profil: TLS-Profil Public-API mit einer Bindung auf Port 443
- Zugang: Orders-Client mit API-Key, berechtigt für die drei Endpunkte
- Endpunkte, alle mit Server Public-API:
| Pfad-Template | Skriptmethode |
|---|---|
/orders |
Get (Liste)
|
/orders/{uid} |
Get (einzelner Auftrag)
|
/orders/{uid}/modules/{code} |
Put
|
Jeder Endpunkt hat sein eigenes Skript und seine eigene Berechtigung. Regeln für Templates und Vorrang: Endpunkte.
Gemeinsamer Helfer
Die Skripte der Liste und des einzelnen Auftrags schreiben dieselben Felder. Der Helfer bekommt den Writer und schreibt in das Objekt, das gerade offen ist: einmal in einen Listeneintrag, einmal in die Wurzel der Antwort. Er steht in beiden Skripten oder einmal in einer ausgelagerten Bibliothek, siehe Scripting.
// Schreibt die Felder eines Auftrags in das Objekt, das der Aufrufer geöffnet hat
procedure _OrderFelder(oWriter: TxRestWriter; qOrder: TxFQuery;
const cOffset: string);
begin
oWriter.Str ('uid' , qOrder.A2UID());
oWriter.Str ('nr' , qOrder.A2C('au_nr'));
oWriter.Str ('kunde' , qOrder.A2C('au_kunde'));
oWriter.Str ('status', qOrder.A2C('au_status'));
// Zeitpunkt als ISO 8601 mit Offset des Servers; leeres Datum ergibt null
oWriter.StrN('aenderung', RestIsoFromDate(qOrder.A2D('au_aend_dat'), cOffset));
end;
Endpunkt-Skript 1: GET /orders
procedure Get(oReader: TxRestReader; oWriter: TxRestWriter);
var cSql : string;
qData : TxFQuery;
cOffset: string;
begin
cOffset := oReader.Offset();
// Liste: RootArr vor der Abfrage, kein Treffer ergibt eine leere Liste
oWriter.RootArr();
cSql := 'SELECT * FROM AUFTRAEGE' +
' WHERE au_status <> ' + DB_SqlVal('9', 'C') +
' ORDER BY au_nr';
if (DB_SOpen(oDB, cSql, qData)) then begin
while (not qData.EoF) do begin
oWriter.ObjBegin('');
_OrderFelder(oWriter, qData, cOffset);
oWriter.ObjEnd;
qData.Next();
end;
end;
DB_Close(qData);
end;
Endpunkt-Skript 2: GET /orders/{uid}
procedure Get(oReader: TxRestReader; oWriter: TxRestWriter);
var cUid : string;
cSql : string;
qData : TxFQuery;
lGefunden: Boolean;
cOffset : string;
begin
// Der Wert kommt aus der URL des Clients. DB_SqlVal schützt die Abfrage,
// ein unbekannter Wert führt zu 404.
cUid := oReader.Path('uid');
cOffset := oReader.Offset();
lGefunden := false;
cSql := 'SELECT * FROM AUFTRAEGE WHERE sys_uid = ' + DB_SqlVal(cUid, 'C');
if (DB_SOpen(oDB, cSql, qData)) then begin
if (not qData.EoF) then begin
_OrderFelder(oWriter, qData, cOffset);
lGefunden := true;
end;
end;
DB_Close(qData);
if (not lGefunden) then begin
oWriter.Error(404, 'NOT_FOUND', 'Auftrag nicht gefunden');
end;
end;
Endpunkt-Skript 3: PUT /orders/{uid}/modules/{code}
PUT läuft in einer Datenbanktransaktion. Endet das Skript mit einem Status ab 400, nimmt der Server alle Änderungen zurück.
procedure Put(oReader: TxRestReader; oWriter: TxRestWriter);
var cUid : string;
cCode : string;
cStatus: string;
cSql : string;
qChk : TxFQuery;
qMod : TqSQL;
cModUid: string;
lOk : Boolean;
begin
// Beide Pfad-Parameter
cUid := oReader.Path('uid');
cCode := oReader.Path('code');
// Nutzdaten aus dem JSON-Körper
cStatus := '';
oReader.Str('status', cStatus);
if (Empty(cStatus)) then begin
oWriter.Error(422, 'VALIDATION_FAILED', 'Feld "status" fehlt');
exit;
end;
// Eine Abfrage auf die sys_uid liefert Existenzprüfung und Schreib-Index
cSql := 'SELECT sys_uid FROM AUFTRAG_MODULE' +
' WHERE am_auftrag = ' + DB_SqlVal(cUid, 'C') +
' AND am_code = ' + DB_SqlVal(cCode, 'C') + ' LIMIT 1';
cModUid := '';
if (DB_SOpen(oDB, cSql, qChk)) then begin
if (not qChk.EoF) then begin
cModUid := qChk.A2UID();
end;
end;
DB_Close(qChk);
if (Empty(cModUid)) then begin
oWriter.Error(404, 'NOT_FOUND', 'Modul nicht gefunden');
exit;
end;
// Ändern: qSqlInit mit sys_uid als Schreib-Index
qMod := qSqlInit(oDB, 'AUFTRAG_MODULE');
qMod.qSet('sys_uid' , cModUid);
qMod.qSet('am_status', cStatus);
// Ein Schreibfehler wirft keine Exception - nur der Rückgabewert zeigt ihn
lOk := qMod.SaveData(UPDATE_RECORD);
qSqlFree(qMod);
if (not lOk) then begin
oWriter.Error(500, 'INTERNAL_ERROR', 'Status konnte nicht gespeichert werden');
exit;
end;
oWriter.Str('status', 'ok');
end;
Test mit curl
# Liste
curl -H "apikey: abcdef-ghij-klmn-opqr-stuvwx" \
https://obs.example.com/orders
# Einzelner Auftrag (uid als Pfad-Parameter)
curl -H "apikey: abcdef-ghij-klmn-opqr-stuvwx" \
https://obs.example.com/orders/4711
# Modul-Status ändern (uid und code als Pfad-Parameter, status im Körper)
curl -X PUT \
-H "apikey: abcdef-ghij-klmn-opqr-stuvwx" \
-H "Idempotency-Key: 5b9e2c7a-1f43-4d8e-9a60-c3f1d7e2b845" \
-H "Content-Type: application/json" \
-d '{"status":"21"}' \
https://obs.example.com/orders/4711/modules/A1
Der Idempotency-Key ist bei PUT Pflicht. Ein wiederholter Aufruf mit demselben Schlüssel und demselben Körper liefert die gespeicherte Antwort mit dem Header Idempotent-Replay: true. Regeln: HTTP-Schnittstelle.
Was zeigt das Beispiel?
- Eine Ressource, mehrere Pfad-Formen über getrennte Endpunkte mit eigenem Skript und eigener Berechtigung.
- Pfad-Parameter werden über
{name}im Template erfasst und im Skript mitoReader.Path('name')gelesen. Der Wert kommt vom Client und wird wie jede Eingabe geprüft. - Die Skriptmethoden haben die Parameter
(oReader: TxRestReader; oWriter: TxRestWriter), Reader zuerst. - Ein Helfer bekommt den Writer und schreibt an der Stelle hinein, an der er aufgerufen wird. Derselbe
_OrderFelderbedient den Listeneintrag und die Einzelantwort. - Vorrang: Ein statisches Segment, z.B.
/orders/summary, hätte Vorrang vor/orders/{uid}. - Schreibender Aufruf mit
Idempotency-Keyund Transaktion.