OBS/Kostenpflichtige Module/REST-Server/Beispiele/Datensatz anlegen mit JSON-Körper: Unterschied zwischen den Versionen
Keine Bearbeitungszusammenfassung |
Überschrift an den neuen Titel angeglichen, Links auf die neuen Titel umgestellt, Umlaute in Kommentaren und Meldungstexten [Volltext ersetzt] |
||
| (11 dazwischenliegende Versionen von 2 Benutzern werden nicht angezeigt) | |||
| Zeile 1: | Zeile 1: | ||
{{Kostenpflichtige Module}} | {{Vorlage:Kostenpflichtige Module}} | ||
{{Seitentyp|Referenz}} | |||
= Datensatz anlegen mit JSON-Körper = | |||
Dieses Beispiel zeigt einen Endpunkt mit allen vier Grundzugriffen: lesen (<code>GET</code>), anlegen (<code>POST</code>), ändern (<code>PUT</code>) und schließen (<code>DELETE</code>). Ein externer Servicedesk liefert damit Tickets in OBS ein, ruft sie ab, aktualisiert und schließt sie – direkt, ohne Dateiaustausch. | |||
Dieses Beispiel | {{Hinweis|Dieses Beispiel adressiert ein einzelnes Ticket über den Query-Parameter <code>?id=…</code>. Dieselbe Ressource lässt sich auch über ein Pfad-Template wie <code>/tickets/{id}</code> ansprechen; die ID steht dann in <code>oReader.Path('id')</code>. Ein vollständiges Beispiel dazu zeigt [[OBS/Kostenpflichtige Module/REST-Server/Beispiele/Pfad-Parameter|Beispiel 4]].}} | ||
==Einrichtung in OBS== | == Einrichtung in OBS == | ||
* '''Server-Profil:''' TLS-Profil ''Public-API'' mit einer Bindung auf Port 443 | |||
* '''Server-Profil:''' | |||
* '''Zugang:''' ''Servicedesk-X'' | * '''Zugang:''' ''Servicedesk-X'' | ||
** API-Key: | ** '''API-Key:''' vom System erzeugt | ||
** Host: ''servicedesk. | ** '''Host:''' ''servicedesk.example.com''. Der Server nimmt Anfragen dieses Zugangs nur von der Adresse an, auf die der Name auflöst; andere Absender erhalten 403. | ||
** JWT: nicht | ** '''JWT-Authentifizierung:''' nicht gesetzt | ||
* '''Endpunkt:''' ''tickets/v1'' | * '''Endpunkt:''' '''Pfad-Template''' <code>/tickets/v1</code>, '''Server''' ''Public-API'' | ||
* '''Berechtigung:''' Zugang ''Servicedesk-X'' | * '''Berechtigung:''' Zugang ''Servicedesk-X'' für den Endpunkt <code>/tickets/v1</code> freigeschaltet | ||
==Endpunkt-Skript | == Endpunkt-Skript == | ||
Das Skript enthält je HTTP-Methode eine gleichnamige Prozedur. <code>POST</code>, <code>PUT</code> und <code>DELETE</code> laufen in einer Datenbanktransaktion: Endet das Skript mit einem Status ab 400 oder mit einem Laufzeitfehler, nimmt der Server alle Änderungen zurück. Details: [[OBS/Kostenpflichtige Module/REST-Server/Scripting|Scripting]]. | |||
<syntaxhighlight lang=" | <syntaxhighlight lang="delphi"> | ||
// | // Schreibt die Felder eines Tickets in das Objekt, das der Aufrufer geöffnet hat | ||
procedure _TicketFelder(oWriter: TxRestWriter; qTicket: TxFQuery; | |||
const cOffset: string); | |||
begin | begin | ||
oWriter.Str ('id' , qTicket.A2UID()); | |||
oWriter.Str ('nr' , qTicket.A2C('ti_nr')); | |||
oWriter.Str ('betreff', qTicket.A2C('ti_betreff')); | |||
oWriter.Str ('status' , qTicket.A2C('ti_status')); | |||
oWriter.Str ('beschr' , qTicket.A2C('ti_beschr')); | |||
// Zeitpunkt als ISO 8601 mit Offset des Servers; leeres Datum ergibt null | |||
oWriter.StrN('aenderung', RestIsoFromDate(qTicket.A2D('ti_aend_dat'), cOffset)); | |||
end; | end; | ||
//------------------------------------------------------------------------------ | //------------------------------------------------------------------------------ | ||
// GET | // GET /tickets/v1?id=... einzelnes Ticket | ||
// GET | // GET /tickets/v1 alle offenen Tickets | ||
//------------------------------------------------------------------------------ | //------------------------------------------------------------------------------ | ||
procedure Get(oReader: TxRestReader; oWriter: TxRestWriter); | |||
var cSql : string; | |||
var cSql | qData : TxFQuery; | ||
qData : TxFQuery; | cId : string; | ||
cOffset : string; | |||
lGefunden: Boolean; | |||
begin | begin | ||
cId := | cId := oReader.Param('id'); | ||
cOffset := oReader.Offset(); | |||
if (not Empty(cId)) then begin | if (not Empty(cId)) then begin | ||
cSql := 'SELECT * FROM | lGefunden := false; | ||
if (DB_SOpen( | cSql := 'SELECT * FROM TICKETS WHERE sys_uid = ' + DB_SqlVal(cId, 'C'); | ||
if (DB_SOpen(oDB, cSql, qData)) then begin | |||
if (not qData.EoF) then begin | |||
_TicketFelder(oWriter, qData, cOffset); | |||
lGefunden := true; | |||
end; | |||
end; | end; | ||
DB_Close(qData); | DB_Close(qData); | ||
if (not lGefunden) then begin | |||
oWriter.Error(404, 'NOT_FOUND', 'Ticket nicht gefunden'); | |||
end; | |||
end else begin | end else begin | ||
// Liste: RootArr vor der Abfrage, kein Treffer ergibt eine leere Liste | |||
oWriter.RootArr(); | |||
cSql := 'SELECT * FROM TICKETS' + | |||
' WHERE ti_status <> ' + DB_SqlVal('9', 'C') + | |||
' ORDER BY ti_aend_dat DESC'; | |||
if (DB_SOpen(oDB, cSql, qData)) then begin | |||
while (not qData.EoF) do begin | |||
oWriter.ObjBegin(''); | |||
_TicketFelder(oWriter, qData, cOffset); | |||
oWriter.ObjEnd; | |||
qData.Next(); | |||
end; | end; | ||
end; | end; | ||
DB_Close(qData); | |||
end; | end; | ||
end; | end; | ||
//------------------------------------------------------------------------------ | //------------------------------------------------------------------------------ | ||
// POST | // POST /tickets/v1 neues Ticket anlegen | ||
// | // Körper: {"betreff":"...", "beschr":"..."} | ||
//------------------------------------------------------------------------------ | //------------------------------------------------------------------------------ | ||
procedure Post(oReader: TxRestReader; oWriter: TxRestWriter); | |||
var qTicket : TqSQL; | |||
var | |||
cId : string; | cId : string; | ||
cBetreff: string; | cBetreff: string; | ||
cBeschr : string; | cBeschr : string; | ||
lOk : Boolean; | |||
begin | begin | ||
if (not | // Kein Körper ist 400, ein fehlendes Feld 422 | ||
if (not oReader.HasBody()) then begin | |||
oWriter.Error(400, 'BAD_REQUEST', 'JSON-Body erforderlich'); | |||
exit; | exit; | ||
end; | end; | ||
| Zeile 92: | Zeile 98: | ||
cBetreff := ''; | cBetreff := ''; | ||
cBeschr := ''; | cBeschr := ''; | ||
oReader.Str('betreff', cBetreff); | |||
oReader.Str('beschr' , cBeschr); | |||
if (Empty(cBetreff)) then begin | if (Empty(cBetreff)) then begin | ||
oWriter.Error(422, 'VALIDATION_FAILED', 'Feld "betreff" fehlt'); | |||
exit; | exit; | ||
end; | end; | ||
| Zeile 102: | Zeile 108: | ||
cId := GetNewId(oDB); | cId := GetNewId(oDB); | ||
lOk := false; | |||
qTicket := qSqlInit(oDB, 'TICKETS'); | |||
qTicket.lNoSysUID := true; | |||
try | try | ||
qTicket.qSet('sys_uid' , cId); | |||
qTicket.qSet('ti_nr' , DB_NeuNum(oDB, 'TICKETS', 'ti_nr', NEUNUM_HOLE, '', '', 1, 999999, '0')); | |||
qTicket.qSet('ti_betreff' , cBetreff); | |||
qTicket.qSet('ti_beschr' , cBeschr); | |||
qTicket.qSet('ti_status' , '1'); | |||
qTicket.qSet('ti_anl_dat' , Now()); | |||
qTicket.qSet('ti_aend_dat', Now()); | |||
// Ein Schreibfehler wirft keine Exception - nur der Rückgabewert zeigt ihn | |||
lOk := qTicket.SaveData(NEW_RECORD); | |||
finally | finally | ||
qSqlFree( | qSqlFree(qTicket); | ||
end; | end; | ||
if (not lOk) then begin | |||
oWriter.Error(500, 'INTERNAL_ERROR', 'Ticket konnte nicht angelegt werden'); | |||
exit; | |||
end; | end; | ||
oWriter.Str('id' , cId); | |||
oWriter.Str('status', 'created'); | |||
oWriter.Status(201); | |||
oWriter.Header('Location', '/tickets/v1?id=' + cId); | |||
end; | end; | ||
//------------------------------------------------------------------------------ | //------------------------------------------------------------------------------ | ||
// PUT | // PUT /tickets/v1 Ticket aktualisieren | ||
// | // Körper: {"id":"...", "status":"...", "beschr":"..."} | ||
//------------------------------------------------------------------------------ | //------------------------------------------------------------------------------ | ||
procedure Put(oReader: TxRestReader; oWriter: TxRestWriter); | |||
var qTicket: TqSQL; | |||
var | lOk : Boolean; | ||
cId : string; | cId : string; | ||
cStat : string; | cStat : string; | ||
cBeschr: string; | cBeschr: string; | ||
begin | begin | ||
if (not | if (not oReader.HasBody()) then begin | ||
oWriter.Error(400, 'BAD_REQUEST', 'JSON-Body erforderlich'); | |||
exit; | exit; | ||
end; | end; | ||
| Zeile 146: | Zeile 155: | ||
cStat := ''; | cStat := ''; | ||
cBeschr := ''; | cBeschr := ''; | ||
oReader.Str('id' , cId); | |||
oReader.Str('status', cStat); | |||
oReader.Str('beschr', cBeschr); | |||
if (Empty(cId)) then begin | if (Empty(cId)) then begin | ||
oWriter.Error(422, 'VALIDATION_FAILED', 'Feld "id" fehlt'); | |||
exit; | exit; | ||
end; | end; | ||
if (not DB_LSeek(oDB, ' | if (not DB_LSeek(oDB, 'TICKETS', 'sys_uid = ' + DB_SqlVal(cId, 'C'))) then begin | ||
oWriter.Error(404, 'NOT_FOUND', 'Ticket nicht gefunden'); | |||
exit; | exit; | ||
end; | end; | ||
// Ändern: qSqlInit mit sys_uid als Schreib-Index | |||
lOk := false; | |||
qTicket := qSqlInit(oDB, 'TICKETS'); | |||
try | try | ||
if (not Empty(cStat)) | qTicket.qSet('sys_uid', cId); | ||
if (not Empty(cBeschr)) then | if (not Empty(cStat)) then begin | ||
qTicket.qSet('ti_status', cStat); | |||
end; | |||
if (not Empty(cBeschr)) then begin | |||
qTicket.qSet('ti_beschr', cBeschr); | |||
end; | |||
qTicket.qSet('ti_aend_dat', Now()); | |||
lOk := qTicket.SaveData(UPDATE_RECORD); | |||
finally | finally | ||
qSqlFree( | qSqlFree(qTicket); | ||
end; | end; | ||
if (not lOk) then begin | |||
oWriter.Error(500, 'INTERNAL_ERROR', 'Ticket konnte nicht geändert werden'); | |||
exit; | |||
end; | |||
oWriter.Str('status', 'updated'); | |||
end; | end; | ||
//------------------------------------------------------------------------------ | //------------------------------------------------------------------------------ | ||
// DELETE /tickets/v1?id=... | // DELETE /tickets/v1?id=... Ticket schließen (Status 9 statt Löschen) | ||
//------------------------------------------------------------------------------ | //------------------------------------------------------------------------------ | ||
procedure Delete(oReader: TxRestReader; oWriter: TxRestWriter); | |||
var qTicket: TqSQL; | |||
var | |||
cId : string; | cId : string; | ||
lOk : Boolean; | |||
begin | begin | ||
cId := | cId := oReader.Param('id'); | ||
if (Empty(cId)) then begin | if (Empty(cId)) then begin | ||
oWriter.Error(422, 'VALIDATION_FAILED', 'Parameter "id" fehlt'); | |||
exit; | exit; | ||
end; | end; | ||
if (not DB_LSeek(oDB, ' | if (not DB_LSeek(oDB, 'TICKETS', 'sys_uid = ' + DB_SqlVal(cId, 'C'))) then begin | ||
oWriter.Error(404, 'NOT_FOUND', 'Ticket nicht gefunden'); | |||
exit; | exit; | ||
end; | end; | ||
lOk := false; | |||
qTicket := qSqlInit(oDB, 'TICKETS'); | |||
try | try | ||
qTicket.qSet('sys_uid' , cId); | |||
qTicket.qSet('ti_status' , '9'); | |||
qTicket.qSet('ti_aend_dat', Now()); | |||
lOk := qTicket.SaveData(UPDATE_RECORD); | |||
finally | finally | ||
qSqlFree( | qSqlFree(qTicket); | ||
end; | end; | ||
if (not lOk) then begin | |||
oWriter.Error(500, 'INTERNAL_ERROR', 'Ticket konnte nicht geschlossen werden'); | |||
exit; | |||
end; | |||
oWriter.Str('status', 'closed'); | |||
end; | end; | ||
</syntaxhighlight> | </syntaxhighlight> | ||
==Aufruf mit curl== | == Aufruf mit curl == | ||
Jeder schreibende Aufruf trägt einen <code>Idempotency-Key</code>. Erzeugen Sie je Vorgang einen neuen Schlüssel, z.B. mit <code>uuidgen</code>, und senden Sie bei einer Wiederholung desselben Vorgangs denselben. Regeln: [[OBS/Kostenpflichtige Module/REST-Server/HTTP-Schnittstelle|HTTP-Schnittstelle]]. | |||
Liste aller offenen Tickets: | Liste aller offenen Tickets: | ||
<syntaxhighlight lang="bash"> | |||
curl -H "apikey: abcdef-ghij-klmn-opqr-stuvwx" \ | |||
https://obs.example.com/tickets/v1 | |||
</syntaxhighlight> | |||
Einzelnes Ticket: | Einzelnes Ticket: | ||
<syntaxhighlight lang="bash"> | |||
curl -H "apikey: abcdef-ghij-klmn-opqr-stuvwx" \ | |||
"https://obs.example.com/tickets/v1?id=abc-123" | |||
</syntaxhighlight> | |||
Neues Ticket anlegen: | Neues Ticket anlegen: | ||
<syntaxhighlight lang="bash"> | |||
curl -X POST \ | |||
-H "apikey: abcdef-ghij-klmn-opqr-stuvwx" \ | |||
-H "Idempotency-Key: 3f2b8c1e-7d4a-4e9b-9c0f-5a6d2e1b8f47" \ | |||
-H "Content-Type: application/json" \ | |||
-d '{"betreff":"Drucker offline","beschr":"Etage 2, Raum 23"}' \ | |||
https://obs.example.com/tickets/v1 | |||
</syntaxhighlight> | |||
Ticket aktualisieren: | Ticket aktualisieren: | ||
<syntaxhighlight lang="bash"> | |||
curl -X PUT \ | |||
-H "apikey: abcdef-ghij-klmn-opqr-stuvwx" \ | |||
-H "Idempotency-Key: 8a1d4f62-0c3b-4b7e-a5d9-2e6f9c0b7a13" \ | |||
-H "Content-Type: application/json" \ | |||
-d '{"id":"abc-123","status":"2"}' \ | |||
https://obs.example.com/tickets/v1 | |||
</syntaxhighlight> | |||
Ticket | Ticket schließen: | ||
<syntaxhighlight lang="bash"> | |||
curl -X DELETE \ | |||
-H "apikey: abcdef-ghij-klmn-opqr-stuvwx" \ | |||
-H "Idempotency-Key: c7e05b9a-6f21-4d8c-b3a4-91d2e8f0a6c5" \ | |||
"https://obs.example.com/tickets/v1?id=abc-123" | |||
</syntaxhighlight> | |||
Ohne <code>Idempotency-Key</code> antwortet der Server auf <code>POST</code>, <code>PUT</code> und <code>DELETE</code> mit 400 <code>IDEMPOTENCY_KEY_MISSING</code>, ohne das Skript aufzurufen. | |||
<syntaxhighlight lang="php" | == Aufruf aus PHP == | ||
<syntaxhighlight lang="php"> | |||
<?php | <?php | ||
$apikey = ' | $apikey = 'abcdef-ghij-klmn-opqr-stuvwx'; | ||
$base = 'https:// | $base = 'https://obs.example.com/tickets/v1'; | ||
function rest($method, $url, $apikey, $body = null) { | // Neuer Schlüssel je Vorgang. Für eine Wiederholung denselben Schlüssel erneut übergeben. | ||
function neuerKey() { | |||
return bin2hex(random_bytes(16)); | |||
} | |||
function rest($method, $url, $apikey, $body = null, $idemKey = null) { | |||
$ch = curl_init(); | $ch = curl_init(); | ||
curl_setopt($ch, CURLOPT_URL , $url); | curl_setopt($ch, CURLOPT_URL , $url); | ||
| Zeile 244: | Zeile 300: | ||
curl_setopt($ch, CURLOPT_CUSTOMREQUEST , $method); | curl_setopt($ch, CURLOPT_CUSTOMREQUEST , $method); | ||
$headers = ['apikey: ' . $apikey]; | $headers = ['apikey: ' . $apikey]; | ||
if ($idemKey !== null) { | |||
$headers[] = 'Idempotency-Key: ' . $idemKey; | |||
} | |||
if ($body !== null) { | if ($body !== null) { | ||
$headers[] = 'Content-Type: application/json'; | $headers[] = 'Content-Type: application/json'; | ||
| Zeile 249: | Zeile 308: | ||
} | } | ||
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers); | curl_setopt($ch, CURLOPT_HTTPHEADER, $headers); | ||
$res = curl_exec($ch); | $res = curl_exec($ch); | ||
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE); | |||
curl_close($ch); | curl_close($ch); | ||
$data = json_decode($res, true); | |||
if ($status >= 400) { | |||
$code = isset($data['error']['code']) ? $data['error']['code'] : 'HTTP_' . $status; | |||
throw new Exception($code . ': ' . ($data['error']['message'] ?? '')); | |||
} | |||
return $data; | |||
} | } | ||
| Zeile 258: | Zeile 324: | ||
'betreff' => 'Drucker offline', | 'betreff' => 'Drucker offline', | ||
'beschr' => 'Etage 2, Raum 23' | 'beschr' => 'Etage 2, Raum 23' | ||
]); | ], neuerKey()); | ||
$id = $neu['id']; | $id = $neu['id']; | ||
// Status aktualisieren | // Status aktualisieren | ||
rest('PUT', $base, $apikey, ['id' => $id, 'status' => '2']); | rest('PUT', $base, $apikey, ['id' => $id, 'status' => '2'], neuerKey()); | ||
// Liste auslesen | // Liste auslesen | ||
| Zeile 269: | Zeile 335: | ||
echo $t['nr'] . ' - ' . $t['betreff'] . PHP_EOL; | echo $t['nr'] . ' - ' . $t['betreff'] . PHP_EOL; | ||
} | } | ||
// Ticket schließen | |||
rest('DELETE', $base . '?id=' . urlencode($id), $apikey, null, neuerKey()); | |||
?> | ?> | ||
</syntaxhighlight> | </syntaxhighlight> | ||
==Was zeigt das Beispiel?== | == Was zeigt das Beispiel? == | ||
* Lesen, Anlegen, Ändern und Schließen über einen Endpunkt, je Methode eine Prozedur <code>Get</code>, <code>Post</code>, <code>Put</code> und <code>Delete</code>. | |||
* JSON-Körper für umfangreichere Eingaben (<code>POST</code>, <code>PUT</code>), Query-Parameter für einfache Werte (<code>GET</code>, <code>DELETE</code>). | |||
* 400 für fehlenden Körper, 422 für fehlende Felder, 404 für unbekannte Tickets, 201 mit <code>Location</code> beim Anlegen. | |||
* Jeder Schreibvorgang wird über den Rückgabewert von <code>SaveData</code> geprüft. Scheitert er, antwortet das Skript mit 500, und der Server nimmt alle Änderungen zurück. | |||
* Schließen über eine Statusänderung statt physischer Löschung. | |||
* <code>Idempotency-Key</code> bei jedem schreibenden Aufruf, auch aus PHP. | |||
* Host-Beschränkung des Zugangs als zweite Sicherheitsebene neben dem API-Key. | |||
* | == Siehe auch == | ||
* | * [[OBS/Kostenpflichtige Module/REST-Server/Scripting|Scripting]] | ||
* | * [[OBS/Kostenpflichtige Module/REST-Server/HTTP-Schnittstelle|HTTP-Schnittstelle]] | ||
* | * [[OBS/Kostenpflichtige Module/REST-Server/Endpunkte|Endpunkte]] | ||
* | * [[OBS/Kostenpflichtige Module/REST-Server/Zugänge|Zugänge]] | ||
* [[OBS/Kostenpflichtige Module/REST-Server/Beispiele/Pfad-Parameter|Beispiel 4 – Pfad-Parameter (REST-Routing über Templates)]] | |||
Aktuelle Version vom 17. November 2026, 07:23 Uhr
Datensatz anlegen mit JSON-Körper
Dieses Beispiel zeigt einen Endpunkt mit allen vier Grundzugriffen: lesen (GET), anlegen (POST), ändern (PUT) und schließen (DELETE). Ein externer Servicedesk liefert damit Tickets in OBS ein, ruft sie ab, aktualisiert und schließt sie – direkt, ohne Dateiaustausch.
Einrichtung in OBS
- Server-Profil: TLS-Profil Public-API mit einer Bindung auf Port 443
- Zugang: Servicedesk-X
- API-Key: vom System erzeugt
- Host: servicedesk.example.com. Der Server nimmt Anfragen dieses Zugangs nur von der Adresse an, auf die der Name auflöst; andere Absender erhalten 403.
- JWT-Authentifizierung: nicht gesetzt
- Endpunkt: Pfad-Template
/tickets/v1, Server Public-API - Berechtigung: Zugang Servicedesk-X für den Endpunkt
/tickets/v1freigeschaltet
Endpunkt-Skript
Das Skript enthält je HTTP-Methode eine gleichnamige Prozedur. POST, PUT und DELETE laufen in einer Datenbanktransaktion: Endet das Skript mit einem Status ab 400 oder mit einem Laufzeitfehler, nimmt der Server alle Änderungen zurück. Details: Scripting.
// Schreibt die Felder eines Tickets in das Objekt, das der Aufrufer geöffnet hat
procedure _TicketFelder(oWriter: TxRestWriter; qTicket: TxFQuery;
const cOffset: string);
begin
oWriter.Str ('id' , qTicket.A2UID());
oWriter.Str ('nr' , qTicket.A2C('ti_nr'));
oWriter.Str ('betreff', qTicket.A2C('ti_betreff'));
oWriter.Str ('status' , qTicket.A2C('ti_status'));
oWriter.Str ('beschr' , qTicket.A2C('ti_beschr'));
// Zeitpunkt als ISO 8601 mit Offset des Servers; leeres Datum ergibt null
oWriter.StrN('aenderung', RestIsoFromDate(qTicket.A2D('ti_aend_dat'), cOffset));
end;
//------------------------------------------------------------------------------
// GET /tickets/v1?id=... einzelnes Ticket
// GET /tickets/v1 alle offenen Tickets
//------------------------------------------------------------------------------
procedure Get(oReader: TxRestReader; oWriter: TxRestWriter);
var cSql : string;
qData : TxFQuery;
cId : string;
cOffset : string;
lGefunden: Boolean;
begin
cId := oReader.Param('id');
cOffset := oReader.Offset();
if (not Empty(cId)) then begin
lGefunden := false;
cSql := 'SELECT * FROM TICKETS WHERE sys_uid = ' + DB_SqlVal(cId, 'C');
if (DB_SOpen(oDB, cSql, qData)) then begin
if (not qData.EoF) then begin
_TicketFelder(oWriter, qData, cOffset);
lGefunden := true;
end;
end;
DB_Close(qData);
if (not lGefunden) then begin
oWriter.Error(404, 'NOT_FOUND', 'Ticket nicht gefunden');
end;
end else begin
// Liste: RootArr vor der Abfrage, kein Treffer ergibt eine leere Liste
oWriter.RootArr();
cSql := 'SELECT * FROM TICKETS' +
' WHERE ti_status <> ' + DB_SqlVal('9', 'C') +
' ORDER BY ti_aend_dat DESC';
if (DB_SOpen(oDB, cSql, qData)) then begin
while (not qData.EoF) do begin
oWriter.ObjBegin('');
_TicketFelder(oWriter, qData, cOffset);
oWriter.ObjEnd;
qData.Next();
end;
end;
DB_Close(qData);
end;
end;
//------------------------------------------------------------------------------
// POST /tickets/v1 neues Ticket anlegen
// Körper: {"betreff":"...", "beschr":"..."}
//------------------------------------------------------------------------------
procedure Post(oReader: TxRestReader; oWriter: TxRestWriter);
var qTicket : TqSQL;
cId : string;
cBetreff: string;
cBeschr : string;
lOk : Boolean;
begin
// Kein Körper ist 400, ein fehlendes Feld 422
if (not oReader.HasBody()) then begin
oWriter.Error(400, 'BAD_REQUEST', 'JSON-Body erforderlich');
exit;
end;
cBetreff := '';
cBeschr := '';
oReader.Str('betreff', cBetreff);
oReader.Str('beschr' , cBeschr);
if (Empty(cBetreff)) then begin
oWriter.Error(422, 'VALIDATION_FAILED', 'Feld "betreff" fehlt');
exit;
end;
cId := GetNewId(oDB);
lOk := false;
qTicket := qSqlInit(oDB, 'TICKETS');
qTicket.lNoSysUID := true;
try
qTicket.qSet('sys_uid' , cId);
qTicket.qSet('ti_nr' , DB_NeuNum(oDB, 'TICKETS', 'ti_nr', NEUNUM_HOLE, '', '', 1, 999999, '0'));
qTicket.qSet('ti_betreff' , cBetreff);
qTicket.qSet('ti_beschr' , cBeschr);
qTicket.qSet('ti_status' , '1');
qTicket.qSet('ti_anl_dat' , Now());
qTicket.qSet('ti_aend_dat', Now());
// Ein Schreibfehler wirft keine Exception - nur der Rückgabewert zeigt ihn
lOk := qTicket.SaveData(NEW_RECORD);
finally
qSqlFree(qTicket);
end;
if (not lOk) then begin
oWriter.Error(500, 'INTERNAL_ERROR', 'Ticket konnte nicht angelegt werden');
exit;
end;
oWriter.Str('id' , cId);
oWriter.Str('status', 'created');
oWriter.Status(201);
oWriter.Header('Location', '/tickets/v1?id=' + cId);
end;
//------------------------------------------------------------------------------
// PUT /tickets/v1 Ticket aktualisieren
// Körper: {"id":"...", "status":"...", "beschr":"..."}
//------------------------------------------------------------------------------
procedure Put(oReader: TxRestReader; oWriter: TxRestWriter);
var qTicket: TqSQL;
lOk : Boolean;
cId : string;
cStat : string;
cBeschr: string;
begin
if (not oReader.HasBody()) then begin
oWriter.Error(400, 'BAD_REQUEST', 'JSON-Body erforderlich');
exit;
end;
cId := '';
cStat := '';
cBeschr := '';
oReader.Str('id' , cId);
oReader.Str('status', cStat);
oReader.Str('beschr', cBeschr);
if (Empty(cId)) then begin
oWriter.Error(422, 'VALIDATION_FAILED', 'Feld "id" fehlt');
exit;
end;
if (not DB_LSeek(oDB, 'TICKETS', 'sys_uid = ' + DB_SqlVal(cId, 'C'))) then begin
oWriter.Error(404, 'NOT_FOUND', 'Ticket nicht gefunden');
exit;
end;
// Ändern: qSqlInit mit sys_uid als Schreib-Index
lOk := false;
qTicket := qSqlInit(oDB, 'TICKETS');
try
qTicket.qSet('sys_uid', cId);
if (not Empty(cStat)) then begin
qTicket.qSet('ti_status', cStat);
end;
if (not Empty(cBeschr)) then begin
qTicket.qSet('ti_beschr', cBeschr);
end;
qTicket.qSet('ti_aend_dat', Now());
lOk := qTicket.SaveData(UPDATE_RECORD);
finally
qSqlFree(qTicket);
end;
if (not lOk) then begin
oWriter.Error(500, 'INTERNAL_ERROR', 'Ticket konnte nicht geändert werden');
exit;
end;
oWriter.Str('status', 'updated');
end;
//------------------------------------------------------------------------------
// DELETE /tickets/v1?id=... Ticket schließen (Status 9 statt Löschen)
//------------------------------------------------------------------------------
procedure Delete(oReader: TxRestReader; oWriter: TxRestWriter);
var qTicket: TqSQL;
cId : string;
lOk : Boolean;
begin
cId := oReader.Param('id');
if (Empty(cId)) then begin
oWriter.Error(422, 'VALIDATION_FAILED', 'Parameter "id" fehlt');
exit;
end;
if (not DB_LSeek(oDB, 'TICKETS', 'sys_uid = ' + DB_SqlVal(cId, 'C'))) then begin
oWriter.Error(404, 'NOT_FOUND', 'Ticket nicht gefunden');
exit;
end;
lOk := false;
qTicket := qSqlInit(oDB, 'TICKETS');
try
qTicket.qSet('sys_uid' , cId);
qTicket.qSet('ti_status' , '9');
qTicket.qSet('ti_aend_dat', Now());
lOk := qTicket.SaveData(UPDATE_RECORD);
finally
qSqlFree(qTicket);
end;
if (not lOk) then begin
oWriter.Error(500, 'INTERNAL_ERROR', 'Ticket konnte nicht geschlossen werden');
exit;
end;
oWriter.Str('status', 'closed');
end;
Aufruf mit curl
Jeder schreibende Aufruf trägt einen Idempotency-Key. Erzeugen Sie je Vorgang einen neuen Schlüssel, z.B. mit uuidgen, und senden Sie bei einer Wiederholung desselben Vorgangs denselben. Regeln: HTTP-Schnittstelle.
Liste aller offenen Tickets:
curl -H "apikey: abcdef-ghij-klmn-opqr-stuvwx" \
https://obs.example.com/tickets/v1
Einzelnes Ticket:
curl -H "apikey: abcdef-ghij-klmn-opqr-stuvwx" \
"https://obs.example.com/tickets/v1?id=abc-123"
Neues Ticket anlegen:
curl -X POST \
-H "apikey: abcdef-ghij-klmn-opqr-stuvwx" \
-H "Idempotency-Key: 3f2b8c1e-7d4a-4e9b-9c0f-5a6d2e1b8f47" \
-H "Content-Type: application/json" \
-d '{"betreff":"Drucker offline","beschr":"Etage 2, Raum 23"}' \
https://obs.example.com/tickets/v1
Ticket aktualisieren:
curl -X PUT \
-H "apikey: abcdef-ghij-klmn-opqr-stuvwx" \
-H "Idempotency-Key: 8a1d4f62-0c3b-4b7e-a5d9-2e6f9c0b7a13" \
-H "Content-Type: application/json" \
-d '{"id":"abc-123","status":"2"}' \
https://obs.example.com/tickets/v1
Ticket schließen:
curl -X DELETE \
-H "apikey: abcdef-ghij-klmn-opqr-stuvwx" \
-H "Idempotency-Key: c7e05b9a-6f21-4d8c-b3a4-91d2e8f0a6c5" \
"https://obs.example.com/tickets/v1?id=abc-123"
Ohne Idempotency-Key antwortet der Server auf POST, PUT und DELETE mit 400 IDEMPOTENCY_KEY_MISSING, ohne das Skript aufzurufen.
Aufruf aus PHP
<?php
$apikey = 'abcdef-ghij-klmn-opqr-stuvwx';
$base = 'https://obs.example.com/tickets/v1';
// Neuer Schlüssel je Vorgang. Für eine Wiederholung denselben Schlüssel erneut übergeben.
function neuerKey() {
return bin2hex(random_bytes(16));
}
function rest($method, $url, $apikey, $body = null, $idemKey = null) {
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL , $url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST , $method);
$headers = ['apikey: ' . $apikey];
if ($idemKey !== null) {
$headers[] = 'Idempotency-Key: ' . $idemKey;
}
if ($body !== null) {
$headers[] = 'Content-Type: application/json';
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($body));
}
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
$res = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
$data = json_decode($res, true);
if ($status >= 400) {
$code = isset($data['error']['code']) ? $data['error']['code'] : 'HTTP_' . $status;
throw new Exception($code . ': ' . ($data['error']['message'] ?? ''));
}
return $data;
}
// Neues Ticket anlegen
$neu = rest('POST', $base, $apikey, [
'betreff' => 'Drucker offline',
'beschr' => 'Etage 2, Raum 23'
], neuerKey());
$id = $neu['id'];
// Status aktualisieren
rest('PUT', $base, $apikey, ['id' => $id, 'status' => '2'], neuerKey());
// Liste auslesen
$alle = rest('GET', $base, $apikey);
foreach ($alle as $t) {
echo $t['nr'] . ' - ' . $t['betreff'] . PHP_EOL;
}
// Ticket schließen
rest('DELETE', $base . '?id=' . urlencode($id), $apikey, null, neuerKey());
?>
Was zeigt das Beispiel?
- Lesen, Anlegen, Ändern und Schließen über einen Endpunkt, je Methode eine Prozedur
Get,Post,PutundDelete. - JSON-Körper für umfangreichere Eingaben (
POST,PUT), Query-Parameter für einfache Werte (GET,DELETE). - 400 für fehlenden Körper, 422 für fehlende Felder, 404 für unbekannte Tickets, 201 mit
Locationbeim Anlegen. - Jeder Schreibvorgang wird über den Rückgabewert von
SaveDatageprüft. Scheitert er, antwortet das Skript mit 500, und der Server nimmt alle Änderungen zurück. - Schließen über eine Statusänderung statt physischer Löschung.
Idempotency-Keybei jedem schreibenden Aufruf, auch aus PHP.- Host-Beschränkung des Zugangs als zweite Sicherheitsebene neben dem API-Key.