OBS/Kostenpflichtige Module/REST-Server/Beispiele/Datei-Upload und Ablage
Beispiel 6: Datei-Upload und Ablage
Dieses Beispiel zeigt einen Endpunkt, der Dateien entgegennimmt: Ein Außendienst-Mitarbeiter fotografiert vor Ort ein Gerät, die App lädt das Foto zum Auftrag hoch, und OBS legt es ab und verknüpft es mit dem Vorgang – ohne Umweg über E-Mail oder USB-Stick.
Der Ablauf ist derselbe für Belege aus einem Scanner, Unterschriften als Bild oder Prüfprotokolle als PDF. Behandelt werden beide Übertragungsarten: der einfache Upload für kleine Dateien und der fortsetzbare Upload für große.
Einrichtung in OBS
- Server-Profil: TLS-Profil Public-API mit einer Bindung auf Port 443
- Zugang: Mobile-App, API-Key vom System erzeugt, Haken JWT-Authentifizierung gesetzt
- Endpunkt: Pfad-Template
/orders/{uid}/photos, Server Public-API- Haken Datei-Upload setzen
- maximale Dateigröße (MB) auf 20 setzen
- Berechtigung: Zugang Mobile-App für den Endpunkt freischalten
Was der Server vor dem Skript erledigt
Der Server nimmt die Datei entgegen, prüft die Größe, legt sie in einem temporären Verzeichnis ab und stellt dem Skript vier Angaben bereit:
| Aufruf | Inhalt |
|---|---|
oReader.UploadPath() |
vollständiger Pfad der temporären Datei |
oReader.UploadName() |
Dateiname, wie ihn der Client gesendet hat |
oReader.UploadType() |
Inhaltstyp der Datei |
oReader.UploadSha() |
SHA-256 der gespeicherten Datei, hexadezimal in Kleinbuchstaben |
Für das Skript ist wichtig:
- Bei Uploads gibt es keinen JSON-Körper.
oReader.HasBody()istfalse. Zusatzangaben wie die Kategorie kommen als Query-Parameter oder, beimultipart/form-data, als weitere Formularfelder, lesbar überoReader.Form('<name>'). - Die temporäre Datei bleibt liegen, wenn das Skript sie nicht übernimmt. Der Server verschiebt sie nicht selbst.
Alle Regeln der Übertragung: Datei-Upload.
Endpunkt-Skript
Das Skript prüft den Dateityp, bildet einen Zielpfad aus Auftrag und Zeitstempel, schreibt den Verweis in die Datenbank und verschiebt die Datei an ihren Zielort. Der Upload ist ein POST und läuft in einer Datenbanktransaktion. Deshalb steht der Datenbankeintrag vor dem Verschieben: Scheitert das Verschieben, antwortet das Skript mit 500, und der Server nimmt den Eintrag zurück.
procedure Post(oReader: TxRestReader; oWriter: TxRestWriter);
const ZIEL_BASIS = '<Ablageverzeichnis>\'; // an Ihre Ablage anpassen
var cUid : string;
cTmpPfad : string;
cOrigName : string;
cTyp : string;
cEndung : string;
cKategorie: string;
cZielDir : string;
cZielName : string;
cZielPfad : string;
qNeu : TqSQL;
lOk : Boolean;
begin
cUid := oReader.Path('uid');
cTmpPfad := oReader.UploadPath();
cOrigName := oReader.UploadName();
cTyp := oReader.UploadType();
cKategorie := oReader.Param('kategorie'); // Query-Parameter, kein Koerper
// 1) Gehoert der Auftrag zum Mandanten aus dem Token?
if (not AuftragGehoertZuMandant(oReader.Claim('tenant'), cUid)) then begin
oWriter.Error(404, 'NOT_FOUND', 'Auftrag nicht gefunden');
exit;
end;
// 2) Dateityp gegen eine Positivliste pruefen, nicht dem Inhaltstyp allein vertrauen
cEndung := Lower(ExtractFileExt(cOrigName));
if ((cEndung <> '.jpg') and (cEndung <> '.jpeg') and (cEndung <> '.png') and (cEndung <> '.pdf')) then begin
oWriter.Error(422, 'VALIDATION_FAILED', 'Nur JPG, PNG und PDF sind zulaessig');
exit;
end;
// 3) Zielnamen selbst bilden. Der Originalname kommt vom Client und
// gehoert nie in den Pfad.
cZielDir := ZIEL_BASIS + DToS(Date()) + '\' + cUid + '\';
cZielName := DToSF(Now()) + '_' + GlobalUID() + cEndung;
cZielPfad := cZielDir + cZielName;
// 4) Verweis in der Datenbank ablegen
qNeu := qSqlInit(oDB, 'AUFTRAG_DOKUMENT');
qNeu.qSet('ad_auftrag' , cUid);
qNeu.qSet('ad_pfad' , cZielPfad);
qNeu.qSet('ad_dateiname', cOrigName);
qNeu.qSet('ad_typ' , cTyp);
qNeu.qSet('ad_kategorie', cKategorie);
qNeu.qSet('ad_datum' , Now());
lOk := qNeu.SaveData(NEW_RECORD);
qSqlFree(qNeu);
if (not lOk) then begin
oWriter.Error(500, 'INTERNAL_ERROR', 'Verweis konnte nicht gespeichert werden');
exit;
end;
// 5) Datei verschieben. Scheitert das, nimmt der Server den Verweis
// aus Schritt 4 mit der Fehlerantwort zurueck.
MyForceDirectories(cZielDir);
if (not FMove(cTmpPfad, cZielPfad)) then begin
oWriter.Error(500, 'INTERNAL_ERROR', 'Datei konnte nicht abgelegt werden');
exit;
end;
// 6) 201 mit Location auf die abgelegte Datei
oWriter.Str('dateiname', cZielName);
oWriter.Int('groesse' , FSize(cZielPfad));
oWriter.Status(201);
oWriter.Header('Location', '/orders/' + cUid + '/photos/' + cZielName);
end;
AuftragGehoertZuMandant und die Tabelle AUFTRAG_DOKUMENT stehen für Ihre Fachlogik.
Test mit curl
Jeder Upload ist ein POST und braucht einen Idempotency-Key: je Foto einen eigenen, über alle Wiederholungen desselben Fotos derselbe.
Einfacher Upload (-F erzeugt multipart/form-data):
curl -i -X POST \
-H "apikey: abcdef-ghij-klmn-opqr-stuvwx" \
-H "Authorization: Bearer <accessToken>" \
-H "Idempotency-Key: 6e1a3f8c-2b7d-4c90-a4e5-d8b3f0c71a29" \
-F "datei=@geraet.jpg" \
"https://obs.example.com/orders/4711/photos?kategorie=VORHER"
Antwort:
HTTP/1.1 201 Created
Location: /orders/4711/photos/20261117091233_A1B2C3.jpg
X-Trace-Id: 20261117T091233123-00001A
{"dateiname":"20261117091233_A1B2C3.jpg","groesse":248113}
Weitere Antworten:
- Upload an einen Endpunkt ohne Haken Datei-Upload: 415
UNSUPPORTED_MEDIA_TYPE - Datei über der maximalen Dateigröße (MB): 413
PAYLOAD_TOO_LARGE - Upload ohne
Idempotency-Key: 400IDEMPOTENCY_KEY_MISSING
Große Dateien: fortsetzbarer Upload
Im Mobilfunknetz reißt eine Verbindung schnell einmal ab. Für solche Fälle überträgt der Client die Datei in Teilstücken und setzt nach einem Abbruch dort fort, wo er aufgehört hat. Am Endpunkt-Skript ändert sich dafür nichts: Der Server sammelt die Teilstücke selbst und ruft das Skript erst auf, wenn die Datei vollständig ist.
Jedes Teilstück ist ein POST und trägt einen Idempotency-Key. Verwenden Sie für alle Teilstücke einer Datei denselben Schlüssel. Gespeichert wird nur die abschließende Antwort des Skripts.
Das erste Teilstück trägt den Dateinamen (Base64-kodiert im Header Upload-Metadata) und erhält eine Upload-Id:
curl -i -X POST \
-H "apikey: abcdef-ghij-klmn-opqr-stuvwx" \
-H "Authorization: Bearer <accessToken>" \
-H "Idempotency-Key: 0f4c9e27-8a1b-4d36-b5e2-7c3a9d1f6b84" \
-H "Content-Range: bytes 0-1048575/5000000" \
-H "Upload-Metadata: filename Z2VyYWV0LmpwZw==,filetype aW1hZ2UvanBlZw==" \
--data-binary "@teil1.bin" \
https://obs.example.com/orders/4711/photos
HTTP/1.1 308 Resume Incomplete
Upload-Id: <Upload-Id>
Upload-Offset: 1048576
Range: bytes=0-1048575
Jedes weitere Teilstück sendet die Upload-Id mit. Das letzte Teilstück erhält die Antwort des Skripts, hier 201. Nach einem Abbruch fragt der Client den Stand ab und setzt dort an:
curl -i -X POST \
-H "apikey: abcdef-ghij-klmn-opqr-stuvwx" \
-H "Authorization: Bearer <accessToken>" \
-H "Idempotency-Key: 0f4c9e27-8a1b-4d36-b5e2-7c3a9d1f6b84" \
-H "Content-Range: bytes */5000000" \
-H "Upload-Id: <Upload-Id>" \
https://obs.example.com/orders/4711/photos
HTTP/1.1 308 Resume Incomplete
Upload-Offset: 3145728
Der Zwischenstand liegt im Arbeitsspeicher des Dienstes. Nach einem Neustart meldet die Statusabfrage den Stand 0, und der Upload beginnt von vorn. Header und Antworten im Einzelnen: Datei-Upload.
Doppelte Uploads vermeiden
Bricht die Verbindung ab, nachdem der Server die Datei schon abgelegt hat, würde eine Wiederholung dasselbe Foto ein zweites Mal einliefern. Mit demselben Idempotency-Key und derselben Datei erkennt der Server die Wiederholung: Er liefert die gespeicherte 201-Antwort mit dem Header Idempotent-Replay: true, ohne das Skript erneut zu starten. Es entsteht weder eine zweite Datei noch ein zweiter Datenbankeintrag. Ein neuer boundary-Wert bei multipart/form-data stört dabei nicht. Regeln: HTTP-Schnittstelle.
Was zeigt das Beispiel?
- Endpunkt mit Haken Datei-Upload und eigener maximaler Dateigröße (MB).
- Zugriff auf die hochgeladene Datei über
oReader.UploadPath(),UploadName(),UploadType()undUploadSha(). - Zusatzangaben als Query-Parameter oder Formularfeld, weil bei Uploads kein JSON-Körper vorliegt.
- Positivliste für zulässige Dateitypen und ein selbst gebildeter Zielname: Der Originalname landet nie im Pfad.
- Erst der Datenbankeintrag, dann das Verschieben: Die Transaktion nimmt den Eintrag zurück, wenn das Verschieben scheitert.
- Übernahme der temporären Datei mit
FMove; ohne diesen Schritt bleibt sie liegen. - Antwort mit 201 und
Location. - Fortsetzbarer Upload ohne Änderung am Skript.
- Schutz gegen doppelte Einlieferung über den
Idempotency-Key.