Zum Inhalt springen

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

Aus OBS Wiki
Rademacker (Diskussion | Beiträge)
Keine Bearbeitungszusammenfassung
MINERVA-Rademacker (Diskussion | Beiträge)
Überschrift an den neuen Titel angeglichen, Links auf die neuen Titel umgestellt, Umlaute in Kommentaren und Meldungstexten [Volltext ersetzt]
 
(3 dazwischenliegende Versionen desselben Benutzers werden nicht angezeigt)
Zeile 1: Zeile 1:
{{Kostenpflichtige Module}}
{{Vorlage:Kostenpflichtige Module}}
{{Seitentyp|Referenz}}
= 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.


Dieses Beispiel zeigt einen Endpunkt, der '''Dateien entgegennimmt''': Ein
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.
Aussendienst-Mitarbeiter fotografiert vor Ort ein Gerät, die App lädt das Foto zum
Auftrag hoch, der Server legt es ab und verknüpft es mit dem Vorgang.


Der Ablauf ist derselbe für Belege aus einem Scanner, Unterschriften-Bilder oder
== Einrichtung in OBS ==
Prüfprotokolle als PDF. Behandelt werden beide Übertragungsarten - der einfache
* '''Server-Profil:''' TLS-Profil ''Public-API'' mit einer Bindung auf Port 443
Upload für kleine Dateien und der fortsetzbare Upload für grosse.
* '''Zugang:''' ''Mobile-App'', '''API-Key''' vom System erzeugt, Haken '''JWT-Authentifizierung''' gesetzt
 
* '''Endpunkt:''' '''Pfad-Template''' <code>/orders/{uid}/photos</code>, '''Server''' ''Public-API''
==Einrichtung in OBS==
** Haken '''Datei-Upload''' setzen
 
** '''maximale Dateigröße (MB)''' auf ''20'' setzen
* '''Server-Profil:''' Standard-TLS-Profil ''Public-API'' (Port 443)
* '''Zugang:''' ''Mobile-App'', API-Key zufällig generiert, JWT aktiv
* '''Endpunkt:''' ''/orders/{uid}/photos'', Profil ''Public-API''
** '''Datei-Upload''' auf '''Ja''' setzen (<code>re_upload = 1</code>)
** '''Max. Upload-Grösse''' auf ''20'' (MB) setzen
* '''Berechtigung:''' Zugang ''Mobile-App'' für den Endpunkt freischalten
* '''Berechtigung:''' Zugang ''Mobile-App'' für den Endpunkt freischalten


{{Hinweis|Ohne den Haken '''Datei-Upload''' lehnt der Server jeden Upload mit
{{Hinweis|Ohne den Haken '''Datei-Upload''' lehnt der Server jeden Upload mit 415 ab, und das Skript läuft nicht an.}}
'''415''' ab und das Skript läuft gar nicht erst an. Das ist die häufigste Ursache,
wenn ein Upload "ohne erkennbaren Grund" scheitert.}}


==Was der Server erledigt, bevor das Skript läuft==
== 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:
Der Server nimmt die Datei entgegen, prüft die Grösse, legt sie in einem temporären
Verzeichnis ab und übergibt dem Skript drei Parameter:


{| class="wikitable"
{| class="wikitable"
! Aufruf !! Inhalt
! Aufruf !! Inhalt
|-
|-
| <code>oReader.UploadPath()</code> || Vollständiger Pfad zur temporären Datei
| <code>oReader.UploadPath()</code> || vollständiger Pfad der temporären Datei
|-
|-
| <code>oReader.UploadName()</code> || Originaldateiname, wie ihn der Client gesendet hat
| <code>oReader.UploadName()</code> || Dateiname, wie ihn der Client gesendet hat
|-
|-
| <code>oReader.UploadType()</code> || Content-Type der Datei
| <code>oReader.UploadType()</code> || Inhaltstyp der Datei
|-
|-
| <code>oReader.UploadSha()</code> || SHA-256 der gespeicherten Datei (hex, klein)
| <code>oReader.UploadSha()</code> || SHA-256 der gespeicherten Datei, hexadezimal in Kleinbuchstaben
|}
|}


Zwei Dinge sind beim Schreiben des Skripts wichtig:
Für das Skript ist wichtig:
* '''Bei Uploads gibt es keinen JSON-Körper.''' <code>oReader.HasBody()</code> ist <code>false</code>. Zusatzangaben wie die Kategorie kommen als Query-Parameter oder, bei <code>multipart/form-data</code>, als weitere Formularfelder, lesbar über <code>oReader.Form('&lt;name&gt;')</code>.
* '''Die temporäre Datei bleibt liegen, wenn das Skript sie nicht übernimmt.''' Der Server verschiebt sie nicht selbst.


* '''Bei Uploads gibt es keinen JSON-Körper''' - <code>oReader.HasBody()</code> ist <code>false</code>, der Request-Body ist die Datei. Zusatzangaben (Kategorie, Bemerkung) kommen deshalb als '''Query-Parameter''' mit - oder, bei <code>multipart/form-data</code>, als weitere '''Formularfelder''', lesbar über <code>oReader.Form('&lt;name&gt;')</code>.
Alle Regeln der Übertragung: [[OBS/Kostenpflichtige Module/REST-Server/Datei-Upload|Datei-Upload]].
* '''Die temporäre Datei bleibt liegen, wenn das Skript sie nicht übernimmt.''' Der Server räumt sie nicht selbst weg.


==Endpunkt-Skript ''/orders/{uid}/photos''==
== 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 <code>POST</code> 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.


Das Skript prüft den Dateityp, baut einen Zielpfad aus Auftrag und Zeitstempel,
<syntaxhighlight lang="delphi">
verschiebt die Datei dorthin und schreibt einen Verweis in die Datenbank.
 
<syntaxhighlight lang="pascal" line>
procedure Post(oReader: TxRestReader; oWriter: TxRestWriter);
procedure Post(oReader: TxRestReader; oWriter: TxRestWriter);
const ZIEL_BASIS = 'D:\OBS\Daten\Auftragsfotos\';
const ZIEL_BASIS = '<Ablageverzeichnis>\';   // an Ihre Ablage anpassen
var cUid      : string;
var cUid      : string;
     cTmpPfad  : string;
     cTmpPfad  : string;
Zeile 64: Zeile 54:
     cZielPfad : string;
     cZielPfad : string;
     qNeu      : TqSQL;
     qNeu      : TqSQL;
    lOk      : Boolean;
begin
begin
     cUid      := oReader.Path('uid');
     cUid      := oReader.Path('uid');
Zeile 69: Zeile 60:
     cOrigName  := oReader.UploadName();
     cOrigName  := oReader.UploadName();
     cTyp      := oReader.UploadType();
     cTyp      := oReader.UploadType();
     cKategorie := oReader.Param('kategorie');  // Query-Parameter, nicht Body
     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 77: Zeile 68:
     end;
     end;


     // 2) Dateityp gegen eine Whitelist pruefen - niemals gegen eine
     // 2) Dateityp gegen eine Positivliste prüfen, nicht dem Inhaltstyp allein vertrauen
    //    Blacklist, und niemals dem Content-Type 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
Zeile 85: Zeile 75:
     end;
     end;


     // 3) Zielname selbst bilden. Den Originalnamen NICHT als Pfad
     // 3) Zielnamen selbst bilden. Der Originalname kommt vom Client und
     //    verwenden - er kommt vom Client und kann '..\' enthalten.
     //    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;
     cZielPfad := cZielDir + cZielName;
     cZielPfad := cZielDir + cZielName;
    MyForceDirectories(cZielDir);
    if (not FMove(cTmpPfad, cZielPfad)) then begin
        // Fehlgeschlagenes Verschieben ist ein Serverproblem -> 500.
        // Der Idempotency-Key wird bei 5xx wieder freigegeben, der
        // Client darf denselben Schluessel erneut senden.
        oWriter.Error(500, 'INTERNAL_ERROR', 'Datei konnte nicht abgelegt werden');
        exit;
    end;


     // 4) Verweis in der Datenbank ablegen
     // 4) Verweis in der Datenbank ablegen
Zeile 109: Zeile 89:
     qNeu.qSet('ad_kategorie', cKategorie);
     qNeu.qSet('ad_kategorie', cKategorie);
     qNeu.qSet('ad_datum'    , Now());
     qNeu.qSet('ad_datum'    , Now());
     // Rueckgabewert auswerten: ohne das bestaetigt der Endpunkt eine
     lOk := qNeu.SaveData(NEW_RECORD);
    // Ablage, die es nicht gibt - die Datei liegt dann im Zielverzeichnis,
    qSqlFree(qNeu);
    // aber ohne Verweis in der Datenbank.
 
    if (not qNeu.SaveData(NEW_RECORD)) then begin
    if (not lOk) then begin
        qSqlFree(qNeu);
         oWriter.Error(500, 'INTERNAL_ERROR', 'Verweis konnte nicht gespeichert werden');
         oWriter.Error(500, 'INTERNAL_ERROR', 'Verweis konnte nicht gespeichert werden');
         exit;
         exit;
     end;
     end;
    qSqlFree(qNeu);


     // 5) 201 mit Location auf die abgelegte Datei
     // 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.Str('dateiname', cZielName);
     oWriter.Int('groesse'  , FSize(cZielPfad));
     oWriter.Int('groesse'  , FSize(cZielPfad));
Zeile 127: Zeile 113:
</syntaxhighlight>
</syntaxhighlight>


{{Hinweis|Soll die Datei statt in ein Verzeichnis in das '''OBS-Dokumenten-System'''
<code>AuftragGehoertZuMandant</code> und die Tabelle <code>AUFTRAG_DOKUMENT</code> stehen für Ihre Fachlogik.
wandern, ersetzt der DMS-Aufruf die Schritte 3 bis 5. Welche Funktion dafür
zuständig ist, hängt vom eingesetzten Dokumenttyp ab - bitte mit dem OBS-Support
klären.}}


{{Hinweis|'''Fünf Fehlerausgänge, fünf Zeilen.''' Vorher baute jeder von ihnen
== Test mit curl ==
sein ''error''-Objekt, seinen Statuscode und seine ''traceId'' von Hand - fünfmal
Jeder Upload ist ein <code>POST</code> und braucht einen <code>Idempotency-Key</code>: je Foto einen eigenen, über alle Wiederholungen desselben Fotos derselbe.
dasselbe Muster, das an einer Stelle abweichen kann, ohne dass es auffällt.
<code>oWriter.Error</code> setzt alles davon, auch die ''traceId'', und verwirft
einen bereits begonnenen Körper. Ein ''exit'' danach genügt.}}


==Test mit curl==
Einfacher Upload (<code>-F</code> erzeugt <code>multipart/form-data</code>):


Einfacher Upload einer Datei (''-F'' erzeugt ''multipart/form-data''):
<syntaxhighlight lang="bash">
 
curl -i -X POST \
curl -i -X POST -H "apikey: [API-KEY]" -H "Authorization: Bearer eyJ..." ^
    -H "apikey: abcdef-ghij-klmn-opqr-stuvwx" \
      -F "datei=@C:\Fotos\geraet.jpg" ^
    -H "Authorization: Bearer <accessToken>" \
      "https://api.meinserver.de/orders/4711/photos?kategorie=VORHER"
    -H "Idempotency-Key: 6e1a3f8c-2b7d-4c90-a4e5-d8b3f0c71a29" \
    -F "datei=@geraet.jpg" \
    "https://obs.example.com/orders/4711/photos?kategorie=VORHER"
</syntaxhighlight>


Antwort:
Antwort:


HTTP/1.1 201 Created
<syntaxhighlight lang="text">
Location: /orders/4711/photos/20260817091233_A1B2C3.jpg
HTTP/1.1 201 Created
X-Trace-Id: 20260817T091233123-00001A
Location: /orders/4711/photos/20261117091233_A1B2C3.jpg
X-Trace-Id: 20261117T091233123-00001A


{"dateiname":"20260817091233_A1B2C3.jpg","groesse":248113}
{"dateiname":"20261117091233_A1B2C3.jpg","groesse":248113}
</syntaxhighlight>


Ein Upload an einen Endpunkt '''ohne''' Upload-Freigabe:
Weitere Antworten:
* Upload an einen Endpunkt ohne Haken '''Datei-Upload''': 415 <code>UNSUPPORTED_MEDIA_TYPE</code>
* Datei über der '''maximalen Dateigröße (MB)''': 413 <code>PAYLOAD_TOO_LARGE</code>
* Upload ohne <code>Idempotency-Key</code>: 400 <code>IDEMPOTENCY_KEY_MISSING</code>


HTTP/1.1 415 Unsupported Media Type
== 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.


Eine Datei über der eingestellten Grenze:
Jedes Teilstück ist ein <code>POST</code> und trägt einen <code>Idempotency-Key</code>. Verwenden Sie für alle Teilstücke einer Datei denselben Schlüssel. Gespeichert wird nur die abschließende Antwort des Skripts.


HTTP/1.1 413 Payload Too Large
Das erste Teilstück trägt den Dateinamen (Base64-kodiert im Header <code>Upload-Metadata</code>) und erhält eine <code>Upload-Id</code>:


==Grosse Dateien: fortsetzbarer Upload==
<syntaxhighlight lang="bash">
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
</syntaxhighlight>


Bei einem Foto aus dem Mobilfunknetz reisst die Verbindung schnell einmal ab. Für
<syntaxhighlight lang="text">
solche Fälle überträgt der Client die Datei in Teilstücken und kann nach einem
HTTP/1.1 308 Resume Incomplete
Abbruch dort weitermachen, wo er aufgehört hat. '''Am Endpunkt-Skript ändert sich
Upload-Id: <Upload-Id>
dafür nichts''' - der Server sammelt die Teilstücke selbst ein und ruft das Skript
Upload-Offset: 1048576
erst auf, wenn die Datei vollständig ist.
Range: bytes=0-1048575
</syntaxhighlight>


Der erste Teil trägt den Dateinamen (Base64-kodiert im Header
Jedes weitere Teilstück sendet die <code>Upload-Id</code> 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:
<code>Upload-Metadata</code>) und liefert eine <code>Upload-Id</code> zurück:


curl -i -X POST -H "apikey: [API-KEY]" -H "Authorization: Bearer eyJ..." ^
<syntaxhighlight lang="bash">
      -H "Content-Range: bytes 0-1048575/5000000" ^
curl -i -X POST \
      -H "Upload-Metadata: filename Z2VyYWV0LmpwZw==,filetype aW1hZ2UvanBlZw==" ^
    -H "apikey: abcdef-ghij-klmn-opqr-stuvwx" \
      --data-binary "@teil1.bin" ^
    -H "Authorization: Bearer <accessToken>" \
      https://api.meinserver.de/orders/4711/photos
    -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
</syntaxhighlight>


HTTP/1.1 308 Resume Incomplete
<syntaxhighlight lang="text">
Upload-Id: 7f2a9c84...
HTTP/1.1 308 Resume Incomplete
Upload-Offset: 1048576
Upload-Offset: 3145728
Range: bytes=0-1048575
</syntaxhighlight>
 
Jeder weitere Teil sendet die ''Upload-Id'' mit. Der letzte Teil bekommt die
normale Antwort des Skripts (hier '''201'''). Nach einem Abbruch fragt der Client
den Stand ab und setzt dort auf:
 
curl -i -X POST -H "apikey: [API-KEY]" -H "Authorization: Bearer eyJ..." ^
      -H "Content-Range: bytes */5000000" -H "Upload-Id: 7f2a9c84..." ^
      https://api.meinserver.de/orders/4711/photos
 
HTTP/1.1 308 Resume Incomplete
Upload-Offset: 3145728
 
{{Hinweis|Der Zwischenstand liegt im Arbeitsspeicher des Dienstes. Wird der
REST-Dienst neu gestartet, muss ein unvollständiger Upload von vorn beginnen.}}
 
==Doppelte Uploads vermeiden==
 
Bricht die Verbindung ab, nachdem der Server die Datei schon abgelegt hat, würde ein
Wiederholversuch dasselbe Foto ein zweites Mal einliefern. Dagegen sendet der Client
den Header <code>Idempotency-Key</code> - für jedes Foto einen eigenen, über alle
Wiederholversuche hinweg denselben:
 
-H "Idempotency-Key: foto-4711-0003"
 
Der Server erkennt die Wiederholung und liefert die '''gespeicherte 201-Antwort'''
samt Header <code>Idempotent-Replay: true</code> zurück, ohne das Skript erneut zu
starten. Es entsteht also weder eine zweite Datei noch ein zweiter DB-Eintrag.
Details: [[OBS/Kostenpflichtige Module/RESTServer/Endpunkte|Endpunkte]], Abschnitt
Idempotenz.


==Was zeigt das Beispiel?==
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]].


* Endpunkt mit '''Datei-Upload-Freigabe''' (<code>re_upload</code>) und eigener Grössenbegrenzung.
== Doppelte Uploads vermeiden ==
* Zugriff auf die hochgeladene Datei über ''oReader.UploadPath()'', ''UploadName()'' und ''UploadType()''.
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]].
* Zusatzangaben als '''Query-Parameter''' oder Formularfeld, weil bei Uploads kein JSON-Körper vorliegt.
* '''Whitelist''' für zulässige Dateitypen und ein '''selbst gebildeter Zielname''' - der Originalname landet nie im Pfad.
* Übernahme der temporären Datei mit ''FMove''; ohne diesen Schritt bleibt sie liegen.
* Antwort mit '''201''' und ''Location''-Header.
* Fortsetzbarer Upload ohne jede Änderung am Skript.
* Schutz gegen doppelte Einlieferung über den ''Idempotency-Key''.


==Siehe auch==
== Was zeigt das Beispiel? ==
* Endpunkt mit Haken '''Datei-Upload''' und eigener '''maximaler Dateigröße (MB)'''.
* Zugriff auf die hochgeladene Datei über <code>oReader.UploadPath()</code>, <code>UploadName()</code>, <code>UploadType()</code> und <code>UploadSha()</code>.
* 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 <code>FMove</code>; ohne diesen Schritt bleibt sie liegen.
* Antwort mit 201 und <code>Location</code>.
* Fortsetzbarer Upload ohne Änderung am Skript.
* Schutz gegen doppelte Einlieferung über den <code>Idempotency-Key</code>.


* [[OBS/Kostenpflichtige Module/RESTServer/Scripting|Scripting]] - Upload-Parameter und Protokoll im Detail
== Siehe auch ==
* [[OBS/Kostenpflichtige Module/RESTServer/Endpunkte|Endpunkte]] - Freigabe, Grössenlimit, Idempotenz
* [[OBS/Kostenpflichtige Module/REST-Server/Datei-Upload|Datei-Upload]]
* [[OBS/Kostenpflichtige Module/RESTServer/Beispiel5|Beispiel 5]] - Schreibzugriff mit Statuscodes und ETag
* [[OBS/Kostenpflichtige Module/REST-Server/Scripting|Scripting]]
* [[OBS/Kostenpflichtige Module/REST-Server/Endpunkte|Endpunkte]]
* [[OBS/Kostenpflichtige Module/REST-Server/HTTP-Schnittstelle|HTTP-Schnittstelle]]
* [[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