Zum Inhalt springen

OBS/Kostenpflichtige Module/REST-Server/Beispiele/Datei-Upload und Ablage: Unterschied zwischen den Versionen

Aus OBS Wiki
MINERVA-Rademacker (Diskussion | Beiträge)
K MINERVA-Rademacker verschob die Seite OBS/Kostenpflichtige Module/RESTServer/Beispiel6 nach OBS/Kostenpflichtige Module/REST-Server/Beispiele/Datei-Upload und Ablage: Titel an Überschrift angeglichen (REST-Server, Umlaute, sprechende Beispieltitel)
MINERVA-Rademacker (Diskussion | Beiträge)
Überschrift an den neuen Titel angeglichen, Links auf die neuen Titel umgestellt, Umlaute in Kommentaren und Meldungstexten [Volltext ersetzt]
 
Zeile 1: Zeile 1:
{{Vorlage:Kostenpflichtige Module}}
{{Vorlage:Kostenpflichtige Module}}
{{Seitentyp|Referenz}}
{{Seitentyp|Referenz}}
= Beispiel 6: Datei-Upload und Ablage =
= 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.
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.
Zeile 36: Zeile 36:
* '''Die temporäre Datei bleibt liegen, wenn das Skript sie nicht übernimmt.''' Der Server verschiebt sie nicht selbst.
* '''Die temporäre Datei bleibt liegen, wenn das Skript sie nicht übernimmt.''' Der Server verschiebt sie nicht selbst.


Alle Regeln der Übertragung: [[OBS/Kostenpflichtige Module/RESTServer/Datei-Upload|Datei-Upload]].
Alle Regeln der Übertragung: [[OBS/Kostenpflichtige Module/REST-Server/Datei-Upload|Datei-Upload]].


== Endpunkt-Skript ==
== Endpunkt-Skript ==
Zeile 60: Zeile 60:
     cOrigName  := oReader.UploadName();
     cOrigName  := oReader.UploadName();
     cTyp      := oReader.UploadType();
     cTyp      := oReader.UploadType();
     cKategorie := oReader.Param('kategorie');  // Query-Parameter, kein Koerper
     cKategorie := oReader.Param('kategorie');  // Query-Parameter, kein Körper


     // 1) Gehoert der Auftrag zum Mandanten aus dem Token?
     // 1) Gehört der Auftrag zum Mandanten aus dem Token?
     if (not AuftragGehoertZuMandant(oReader.Claim('tenant'), cUid)) then begin
     if (not AuftragGehoertZuMandant(oReader.Claim('tenant'), cUid)) then begin
         oWriter.Error(404, 'NOT_FOUND', 'Auftrag nicht gefunden');
         oWriter.Error(404, 'NOT_FOUND', 'Auftrag nicht gefunden');
Zeile 68: Zeile 68:
     end;
     end;


     // 2) Dateityp gegen eine Positivliste pruefen, nicht dem Inhaltstyp allein vertrauen
     // 2) Dateityp gegen eine Positivliste prüfen, nicht dem Inhaltstyp allein vertrauen
     cEndung := Lower(ExtractFileExt(cOrigName));
     cEndung := Lower(ExtractFileExt(cOrigName));
     if ((cEndung <> '.jpg') and (cEndung <> '.jpeg') and (cEndung <> '.png') and (cEndung <> '.pdf')) then begin
     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');
         oWriter.Error(422, 'VALIDATION_FAILED', 'Nur JPG, PNG und PDF sind zulässig');
         exit;
         exit;
     end;
     end;


     // 3) Zielnamen selbst bilden. Der Originalname kommt vom Client und
     // 3) Zielnamen selbst bilden. Der Originalname kommt vom Client und
     //    gehoert nie in den Pfad.
     //    gehört nie in den Pfad.
     cZielDir  := ZIEL_BASIS + DToS(Date()) + '\' + cUid + '\';
     cZielDir  := ZIEL_BASIS + DToS(Date()) + '\' + cUid + '\';
     cZielName := DToSF(Now()) + '_' + GlobalUID() + cEndung;
     cZielName := DToSF(Now()) + '_' + GlobalUID() + cEndung;
Zeile 98: Zeile 98:


     // 5) Datei verschieben. Scheitert das, nimmt der Server den Verweis
     // 5) Datei verschieben. Scheitert das, nimmt der Server den Verweis
     //    aus Schritt 4 mit der Fehlerantwort zurueck.
     //    aus Schritt 4 mit der Fehlerantwort zurück.
     MyForceDirectories(cZielDir);
     MyForceDirectories(cZielDir);
     if (not FMove(cTmpPfad, cZielPfad)) then begin
     if (not FMove(cTmpPfad, cZielPfad)) then begin
Zeile 186: Zeile 186:
</syntaxhighlight>
</syntaxhighlight>


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: [[OBS/Kostenpflichtige Module/RESTServer/Datei-Upload|Datei-Upload]].
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: [[OBS/Kostenpflichtige Module/REST-Server/Datei-Upload|Datei-Upload]].


== Doppelte Uploads vermeiden ==
== 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 <code>Idempotency-Key</code> und derselben Datei erkennt der Server die Wiederholung: Er liefert die gespeicherte 201-Antwort mit dem Header <code>Idempotent-Replay: true</code>, ohne das Skript erneut zu starten. Es entsteht weder eine zweite Datei noch ein zweiter Datenbankeintrag. Ein neuer <code>boundary</code>-Wert bei <code>multipart/form-data</code> stört dabei nicht. Regeln: [[OBS/Kostenpflichtige Module/RESTServer/HTTP-Schnittstelle|HTTP-Schnittstelle]].
Bricht die Verbindung ab, nachdem der Server die Datei schon abgelegt hat, würde eine Wiederholung dasselbe Foto ein zweites Mal einliefern. Mit demselben <code>Idempotency-Key</code> und derselben Datei erkennt der Server die Wiederholung: Er liefert die gespeicherte 201-Antwort mit dem Header <code>Idempotent-Replay: true</code>, ohne das Skript erneut zu starten. Es entsteht weder eine zweite Datei noch ein zweiter Datenbankeintrag. Ein neuer <code>boundary</code>-Wert bei <code>multipart/form-data</code> stört dabei nicht. Regeln: [[OBS/Kostenpflichtige Module/REST-Server/HTTP-Schnittstelle|HTTP-Schnittstelle]].


== Was zeigt das Beispiel? ==
== Was zeigt das Beispiel? ==
Zeile 203: Zeile 203:


== Siehe auch ==
== Siehe auch ==
* [[OBS/Kostenpflichtige Module/RESTServer/Datei-Upload|Datei-Upload]]
* [[OBS/Kostenpflichtige Module/REST-Server/Datei-Upload|Datei-Upload]]
* [[OBS/Kostenpflichtige Module/RESTServer/Scripting|Scripting]]
* [[OBS/Kostenpflichtige Module/REST-Server/Scripting|Scripting]]
* [[OBS/Kostenpflichtige Module/RESTServer/Endpunkte|Endpunkte]]
* [[OBS/Kostenpflichtige Module/REST-Server/Endpunkte|Endpunkte]]
* [[OBS/Kostenpflichtige Module/RESTServer/HTTP-Schnittstelle|HTTP-Schnittstelle]]
* [[OBS/Kostenpflichtige Module/REST-Server/HTTP-Schnittstelle|HTTP-Schnittstelle]]
* [[OBS/Kostenpflichtige Module/RESTServer/Beispiel5|Beispiel 5: Schreibzugriff mit Statuscodes, ETag und Idempotenz]]
* [[OBS/Kostenpflichtige Module/REST-Server/Beispiele/Schreibzugriff mit Statuscodes, ETag und Idempotenz|Beispiel 5: Schreibzugriff mit Statuscodes, ETag und Idempotenz]]

Aktuelle Version vom 17. November 2026, 07:23 Uhr

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
HINWEIS: Ohne den Haken Datei-Upload lehnt der Server jeden Upload mit 415 ab, und das Skript läuft nicht an.

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() ist false. Zusatzangaben wie die Kategorie kommen als Query-Parameter oder, bei multipart/form-data, als weitere Formularfelder, lesbar über oReader.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 Körper

    // 1) Gehört 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 prüfen, 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 zulässig');
        exit;
    end;

    // 3) Zielnamen selbst bilden. Der Originalname kommt vom Client und
    //    gehört 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 zurück.
    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: 400 IDEMPOTENCY_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() und UploadSha().
  • 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.

Siehe auch