OBS/Kostenpflichtige Module/REST-Server/Beispiele/Datensatz anlegen mit JSON-Körper
Beispiel 3: Datensatz anlegen mit JSON-Body
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 geoeffnet 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
// Koerper: {"betreff":"...", "beschr":"..."}
//------------------------------------------------------------------------------
procedure Post(oReader: TxRestReader; oWriter: TxRestWriter);
var qTicket : TqSQL;
cId : string;
cBetreff: string;
cBeschr : string;
lOk : Boolean;
begin
// Kein Koerper 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 Rueckgabewert 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
// Koerper: {"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;
// Aendern: 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 geaendert werden');
exit;
end;
oWriter.Str('status', 'updated');
end;
//------------------------------------------------------------------------------
// DELETE /tickets/v1?id=... Ticket schliessen (Status 9 statt Loeschen)
//------------------------------------------------------------------------------
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 Schluessel je Vorgang. Fuer eine Wiederholung denselben Schluessel erneut uebergeben.
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 schliessen
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.