Zum Inhalt springen

OBS/Kostenpflichtige Module/REST-Server/Beispiele/Pfad-Parameter: Unterschied zwischen den Versionen

Aus OBS Wiki
Böhrer (Diskussion | Beiträge)
Die Seite wurde neu angelegt: „Скачать [http://fstoexua.ru/film/136/ Пираты карибского Моря 5 2017 Мертвецы смотреть] Карибского Моря…“
 
MINERVA-Rademacker (Diskussion | Beiträge)
Ü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:
Скачать [http://fstoexua.ru/film/136/ Пираты карибского Моря 5 2017 Мертвецы смотреть] Карибского Моря 5 посмотреть фильм Пираты Карибского моря 5<br><br>http://fstoexua.ru/film/136/<br><br>%random_video%<br>Скачать Пираты Карибского Моря 5<br>Пираты Карибского Моря 5 Смотреть Онлайн Смотреть Фильмы Онлайн Пираты Карибского Моря 5 Фильм Пираты Карибского Моря 5 Мертвецы Скачать Пираты Карибского Моря 5 Скачать Пираты Карибского Моря 5<br>http://megogoserial.ru/zhenskiy-doktor-35-seriya-smotret-onlayn/smotret-online-hd-720-p-megogo http://megogoserial.ru/revolyuciya-z-sezon-1-epizod-12-21-05-2017-na-russkom/smotret-online-hd-720-p-megogo http://megogoserial.ru/kuhnya-4-sezon-18-21-05-2017-skachat-torrent-vse-serii-kuhnya-4-sezon-18/smotret-online-hd-720-p-megogo http://megogoserial.ru/skins-7-sezon-1-seriya-21-05-2017-novye-serii-smot/smotret-online-hd-720-p-megogo http://megogoserial.ru/domrabotnica-film-2011-21-05-2017-na-russkom-yazy/smotret-online-hd-720-p-megogo http://megogoserial.ru/dnevnicite-na-vampira-sezon-4-epizod-5-21-05-2017/smotret-online-hd-720-p-megogo http://megogoserial.ru/brigada-seriya-12-21-05-2017-vse-serii-podryad-skach/smotret-online-hd-720-p-megogo http://megogoserial.ru/svaty-sezon-2-seriya-1-21-05-2017-sezon-vse-serii-s/smotret-online-hd-720-p-megogo http://megogoserial.ru/kukhnya-1-sezon-20-seriya-smotret-onlayn-21-05-2017/smotret-online-hd-720-p-megogo http://[http://www.becomegorgeous.com/topics/megogoserial megogoserial].ru/pomadnye-dzhungli-2-sezon-smotret-onla-3/smotret-online-hd-720-p-megogo
{{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 mit oReader.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 _OrderFelder bedient den Listeneintrag und die Einzelantwort.
  • Vorrang: Ein statisches Segment, z.B. /orders/summary, hätte Vorrang vor /orders/{uid}.
  • Schreibender Aufruf mit Idempotency-Key und Transaktion.

Siehe auch