Zum Inhalt springen

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

Aus OBS Wiki
MINERVA-Rademacker (Diskussion | Beiträge)
Reader-Aufrufe statt _OBS_UPLOAD_-Felder, Idempotency-Key-Pflicht bei Uploads ergaenzt [Volltext ersetzt]
MINERVA-Rademacker (Diskussion | Beiträge)
Idempotenz für alle Größen, Key je Teilstück, 308-Fälle, 415 ohne Datei-Upload, Größe für ganzen Körper, Formularfelder 40 Zeichen, Rückgabe-Tabelle ergänzt [Volltext ersetzt]
Zeile 1: Zeile 1:
{{Kostenpflichtige Module}}
{{Vorlage:Kostenpflichtige Module}}
 
{{Seitentyp|Referenz}}
= Datei-Upload =
= Datei-Upload =


Ein Endpunkt nimmt Dateien nur entgegen, wenn er dafür freigeschaltet ist
Fotos, Unterschriften, Dokumente: Ein Endpunkt nimmt Dateien direkt vom Gerät entgegen. Große Dateien überträgt der Client in Teilstücken und setzt nach einem Verbindungsabbruch dort fort, wo er stehen geblieben ist. Diese Seite beschreibt die Übertragung: was ein Client senden muss und was der Server antwortet.
(<code>re_upload = 1</code>, siehe
[[OBS/Kostenpflichtige Module/RESTServer/Endpunkte|Endpunkte]]). Dann gilt nicht
das JSON-Body-Limit von 10&nbsp;MB, sondern die pro Endpunkt konfigurierte Grösse
(<code>re_upload_size</code>, Standard 25&nbsp;MB; Überschreitung -> '''413''').


Diese Seite beschreibt die '''Übertragung''' - was ein Client senden muss und was
Was das Skript von einem Upload sieht, steht unter [[OBS/Kostenpflichtige Module/RESTServer/Scripting#Datei-Uploads|Scripting]]. Ein vollständiges Beispiel zeigt [[OBS/Kostenpflichtige Module/RESTServer/Beispiel6|Beispiel 6]].
der Server antwortet. Was das '''Skript''' davon sieht, sind vier Aufrufe
(<code>oReader.UploadPath()</code>, <code>UploadName()</code>,
<code>UploadType()</code>, <code>UploadSha()</code>) und steht unter
[[OBS/Kostenpflichtige Module/RESTServer/Scripting#Datei-Uploads|Scripting]].
Ein vollständiges Beispiel zeigt
[[OBS/Kostenpflichtige Module/RESTServer/Beispiel6|Beispiel 6]].


{{Hinweis|Der Server legt die Datei in einem temporären Verzeichnis ab und
{{Hinweis|Ein Endpunkt nimmt Dateien nur an, wenn in seiner Eingabemaske der Haken '''Datei-Upload''' gesetzt ist. Die Grenze legt das Feld '''maximale Dateigröße (MB)''' fest, ohne Angabe 25 MB. Siehe [[OBS/Kostenpflichtige Module/RESTServer/Endpunkte|Endpunkte]].}}
'''verschiebt sie nicht selbst'''. Übernimmt das Skript sie nicht an ihren
Zielort, bleibt sie dort liegen.}}


{{Achtung|Ein Upload läuft über ''POST'' und braucht deshalb - wie jeder
== Aufruf ==
schreibende Aufruf - den Header <code>Idempotency-Key</code>. Fehlt er, antwortet
Ein Upload ist ein <code>POST</code> an den Endpunkt. Es gibt zwei Wege:
der Server mit '''400''' <code>IDEMPOTENCY_KEY_MISSING</code>, und zwar bevor eine
Datei entgegengenommen wird. Beim resumable Upload gehört er an '''jedes'''
Teilstück; wirksam wird er beim letzten, weil erst dort eine Antwort entsteht, die
sich speichern lässt. Siehe
[[OBS/Kostenpflichtige Module/RESTServer/Endpunkte|Endpunkte]], Abschnitt
Idempotenz.}}


== Einfacher Upload (multipart/form-data) ==
{| class="wikitable"
! Weg !! Erkennung !! Wofür
|-
| [[#Einfacher Upload (multipart/form-data)|Einfacher Upload]] || <code>Content-Type: multipart/form-data</code> || eine Datei in einer Anfrage, mit Formularfeldern
|-
| [[#Fortsetzbarer Upload (Content-Range)|Fortsetzbarer Upload]] || Header <code>Content-Range</code> || große Dateien in Teilstücken, fortsetzbar nach einem Abbruch
|}


Eine Datei pro Request. Name und Content-Type stammen aus der
Beide Wege brauchen wie jeder schreibende Aufruf den Header <code>Idempotency-Key</code>, siehe [[#Idempotenz|Idempotenz]].
<code>Content-Disposition</code> der Datei-Partie (<code>filename=</code>). Der
Server speichert die erste Datei-Partie und ruft das Skript auf.


Die '''übrigen Partien''' des Formulars - alles ohne <code>filename=</code> -
== Parameter ==
liest das Skript über <code>oReader.Form('&lt;name&gt;')</code>. Der Wert ist UTF-8 und
{| class="wikitable"
auf 1024 Zeichen begrenzt, der Name auf Buchstaben, Ziffern und Unterstrich
! Parameter !! Typ !! Pflicht !! Standard !! Bedeutung
reduziert. Zusatzangaben lassen sich damit im selben Request mitschicken, ohne sie
|-
an die URL zu hängen:
| <code>Idempotency-Key</code> || Header || ✓ || – || Kennung des Vorgangs, höchstens 128 Zeichen. Beim fortsetzbaren Upload an jedem Teilstück.
|-
| <code>Content-Type</code> || Header || ✓ || – || Einfacher Upload: <code>multipart/form-data; boundary=…</code>
|-
| Datei-Partie || Formular || ✓ || – || Einfacher Upload: Partie mit <code>filename=</code> in <code>Content-Disposition</code>. Ihr <code>Content-Type</code> wird zu <code>UploadType()</code>.
|-
| weitere Partien || Formular || – || – || Einfacher Upload: Zusatzangaben ohne <code>filename=</code>, im Skript über <code>oReader.Form</code>
|-
| <code>Content-Range</code> || Header || ✓ || – || Fortsetzbarer Upload: <code>bytes START-END/TOTAL</code> für ein Teilstück, <code>bytes */TOTAL</code> für eine Statusabfrage
|-
| <code>Upload-Id</code> || Header || – || vom Server vergeben || Fortsetzbarer Upload: Kennung des Uploads. Fehlt sie am ersten Teilstück, vergibt der Server eine. Alle weiteren Anfragen senden sie mit.
|-
| <code>Upload-Metadata</code> || Header || ✓ || – || Fortsetzbarer Upload, nur am ersten Teilstück: <code>filename</code> (Pflicht) und <code>filetype</code> (optional), Werte Base64-kodiert
|}


<syntaxhighlight lang="pascal" line>
API-Key, Token und die übrigen Header jeder Anfrage beschreibt [[OBS/Kostenpflichtige Module/RESTServer/HTTP-Schnittstelle|HTTP-Schnittstelle]].
procedure Post(oReader: TxRestReader; oWriter: TxRestWriter);
 
var cPfad : string;
== Einfacher Upload (multipart/form-data) ==
    cName : string;
Eine Datei je Anfrage. Name und Content-Type der Datei stammen aus der Datei-Partie. Der Server speichert die '''erste''' Partie mit <code>filename=</code>, weitere Datei-Partien ignoriert er. Danach ruft er das Skript auf.
    cTyp  : string;
    cBemerk: string;
begin
    cPfad  := oReader.UploadPath();
    cName  := oReader.UploadName();
    cTyp    := oReader.UploadType();
    cBemerk := oReader.Form('bemerkung');  // Formularfeld derselben Uebertragung


    // ... Datei aus cPfad ins DMS / Zielverzeichnis uebernehmen ...
* Die '''maximale Dateigröße (MB)''' gilt für den gesamten Körper der Anfrage, also Datei samt Formularfeldern.
* Die übrigen Partien liest das Skript mit <code>oReader.Form('&lt;name&gt;')</code>. Der Wert ist UTF-8 und wird nach 1024 Zeichen gekürzt. Vom Namen bleiben nur Buchstaben, Ziffern und Unterstrich, höchstens 40 Zeichen.
* Fehlt eine Datei-Partie oder ihr Dateiname, antwortet der Server mit '''400'''. Das Skript läuft nicht.


    oWriter.Str('status'   , 'ok');
<syntaxhighlight lang="bash">
    oWriter.Str('dateiname', cName);
curl -X POST "https://obs.example.com:8443/beispiel/belege" \
    oWriter.Status(201);
   -H "apikey: abcdef-ghij-klmn-opqr-stuvwx" \
end;
  -H "Idempotency-Key: 7b1e4c2a-9f3d-4a6e-8c5b-2d0f1e3a4b6c" \
  -F "datei=@lieferschein.pdf;type=application/pdf" \
  -F "bemerkung=Unterschrift Kunde"
</syntaxhighlight>
</syntaxhighlight>


== Resumable/Chunked Upload (Content-Range) ==
== Fortsetzbarer Upload (Content-Range) ==
 
Für große Dateien sendet der Client die Datei in Teilstücken, jedes als eigenen <code>POST</code> mit dem Header <code>Content-Range</code>. Der Server hängt die Teilstücke der Reihe nach an. Das Skript läuft erst, wenn die Datei vollständig ist. Es erhält dann dieselben Werte wie beim einfachen Upload.
Für grosse Dateien überträgt der Client die Datei in Teilstücken (Chunks) mit dem
Header <code>Content-Range: bytes START-END/TOTAL</code>. Der Server hängt die
Chunks '''sequentiell''' an eine Session-Datei an und behandelt unvollständige
Uploads selbst - das Endpunkt-Skript läuft '''erst beim vollständigen Upload''',
und dann liefern ''oReader.UploadPath()'', ''UploadName()'' und ''UploadType()''
dasselbe wie beim einfachen Upload. Für die Teilstücke läuft es '''nicht'''.


Name und Content-Type sind im <code>Content-Range</code>-Protokoll nicht enthalten;
Name und Typ der Datei sendet der Client im '''ersten''' Teilstück im Header <code>Upload-Metadata</code>. Das Format: durch Komma getrennte Paare aus Schlüssel und Base64-Wert.
der Client liefert sie deshalb '''im ersten Chunk''' über den Header
<code>Upload-Metadata</code> (Format wie bei tus: kommagetrennte Paare
<code>schlüssel base64wert</code>, Werte Base64-kodiert):


<pre>
<syntaxhighlight lang="text">
Upload-Metadata: filename ZmlsZS5wZGY=,filetype YXBwbGljYXRpb24vcGRm
Upload-Metadata: filename ZmlsZS5wZGY=,filetype YXBwbGljYXRpb24vcGRm
</pre>
</syntaxhighlight>


Erkannt werden die Schlüssel <code>filename</code> (Pflicht) und
Fehlt <code>filename</code> im ersten Teilstück, antwortet der Server mit '''400''' und legt keine Datei an. Folgende Teilstücke und Statusabfragen brauchen die Angaben nicht erneut.
<code>filetype</code> (optional). Fehlt <code>filename</code> im ersten Chunk,
wird der Upload mit '''400''' abgelehnt, ohne dass eine Datei angelegt wird.
Folge-Chunks und Statusabfragen müssen die Metadaten nicht erneut senden.


Ablauf (vom Client gesteuert, der Server antwortet jeweils):
=== Ablauf ===
{| class="wikitable"
! Anfrage !! Antwort des Servers
|-
| Erstes Teilstück, z.B. <code>Content-Range: bytes 0-1048575/5000000</code>, mit <code>Upload-Metadata</code> || '''308''' mit <code>Upload-Id</code>, <code>Upload-Offset</code> und <code>Range</code>
|-
| Weitere Teilstücke, jeweils mit <code>Upload-Id</code> || '''308''' mit aktuellem <code>Upload-Offset</code>
|-
| Letztes Teilstück: Die gespeicherten Bytes erreichen TOTAL || Antwort des Skripts, z.B. '''201'''
|-
| Statusabfrage <code>Content-Range: bytes */5000000</code> mit <code>Upload-Id</code> || '''308''' mit aktuellem <code>Upload-Offset</code>, ohne etwas anzuhängen
|}


{| class="wikitable"
{| class="wikitable"
! Request !! Server-Antwort
! Header der Antwort !! Bedeutung
|-
| Erster Chunk <code>Content-Range: bytes 0-1048575/5000000</code> + <code>Upload-Metadata</code> || '''308''' Resume Incomplete + Header <code>Upload-Id</code>, <code>Upload-Offset</code>, <code>Range</code>
|-
|-
| weitere Chunks (jeweils <code>Upload-Id</code> mitsenden) || '''308''' mit aktualisiertem <code>Upload-Offset</code>
| <code>Upload-Id</code> || Kennung des Uploads
|-
|-
| letzter Chunk (Bereich erreicht TOTAL) || normale Skript-Antwort (z.B. '''200'''/'''201''')
| <code>Upload-Offset</code> || Zahl der gespeicherten Bytes = Startposition des nächsten Teilstücks
|-
|-
| Statusabfrage <code>Content-Range: bytes */5000000</code> || aktueller <code>Upload-Offset</code>, ohne anzuhängen (Resume)
| <code>Range</code> || Gespeicherter Bereich, z.B. <code>bytes=0-1048575</code>. Fehlt, solange nichts gespeichert ist.
|}
|}


=== Fortsetzen nach einem Abbruch ===
* Der Server hängt ein Teilstück nur an, wenn START genau dem gespeicherten Stand entspricht. Passt START nicht (doppeltes Teilstück, Lücke), hängt er nichts an und antwortet mit '''308''' und dem aktuellen <code>Upload-Offset</code>. Der Client setzt dort neu an. Eine eigene Statusabfrage ist dafür nicht nötig.
* Ist die <code>Upload-Id</code> unbekannt, antwortet der Server auf eine Statusabfrage oder ein Teilstück mit START größer 0 mit '''308''' und <code>Upload-Offset: 0</code>. Der Client beginnt dann von vorn.
* Der Stand eines Uploads liegt im Arbeitsspeicher des Dienstes. Nach einem Neustart ist er verloren, die <code>Upload-Id</code> ist dann unbekannt.
=== Grenzen ===
* Ist TOTAL größer als die '''maximale Dateigröße (MB)''', antwortet der Server mit '''413'''. Dasselbe gilt, wenn ein Teilstück die Grenze überschreiten würde.
* Formularfelder gibt es hier nicht. Zusatzangaben sendet der Client als Query-Parameter oder Header, das Skript liest sie mit <code>oReader.Param</code>.
* Ein ungültiger <code>Content-Range</code>-Wert führt zu '''400'''.
== Idempotenz ==
Jeder Upload ist ein <code>POST</code> und braucht den Header <code>Idempotency-Key</code>. Fehlt er, antwortet der Server mit '''400''' <code>IDEMPOTENCY_KEY_MISSING</code>, bevor er die Datei speichert.
* '''Gleicher Inhalt''' heißt: dieselben Bytes. Das gilt für jede Dateigröße. Bei <code>multipart/form-data</code> zählt der <code>boundary</code>-Wert nicht mit. Ein neuer Trenner bei der Wiederholung ist also erlaubt.
* '''Fortsetzbarer Upload:''' Jedes Teilstück braucht den Header. Sie können für alle Teilstücke denselben Key verwenden. Eine Antwort '''308''' gibt den Key wieder frei, gespeichert wird erst die abschließende 2xx-Antwort des Skripts.
* Wiederholt der Client das letzte Teilstück oder einen einfachen Upload mit demselben Key und Inhalt, erhält er die gespeicherte Antwort. Das Skript läuft nicht noch einmal.
{{Achtung|Verwenden Sie für eine '''andere''' Datei immer einen neuen Key. Derselbe Key mit anderem Inhalt endet mit '''422''' <code>IDEMPOTENCY_KEY_REUSED</code>.}}
Regeln zur Idempotenz allgemein: [[OBS/Kostenpflichtige Module/RESTServer/HTTP-Schnittstelle#Idempotenz|HTTP-Schnittstelle]].
== Komprimierte Uploads ==
Einen Upload mit dem Header <code>Content-Encoding</code>, z.B. <code>gzip</code>, weist der Server mit '''415''' ab. Das gilt für beide Wege. Nur <code>identity</code> ist zulässig.
Der Grund: Beim fortsetzbaren Upload bliebe offen, ob <code>Content-Range</code> gepackte oder entpackte Bytes zählt. Und die Prüfsumme <code>UploadSha()</code> bezöge sich auf eine andere Datei, als der Client gesendet hat.
Wollen Sie gepackt hochladen, packen Sie die Datei selbst und laden sie z.B. als <code>export.csv.gz</code> hoch. Offsets, Prüfsumme und Fortsetzen stimmen dann.
== Rückgabe ==
{| class="wikitable"
{| class="wikitable"
! Header !! Richtung !! Bedeutung
! Status !! code !! Bedeutung
|-
|-
| Content-Range || Request || <code>bytes START-END/TOTAL</code>; <code>bytes */TOTAL</code> nur als Statusabfrage
| 2xx || – || Antwort des Skripts nach vollständigem Upload
|-
|-
| Upload-Metadata || Request || tus-Metadaten im ersten Chunk: <code>filename</code> (Pflicht), <code>filetype</code> (optional), Base64-kodiert
| 308 || – || Teilstück gespeichert oder Statusabfrage beantwortet. Weiter ab <code>Upload-Offset</code>.
|-
|-
| Upload-Id || Request/Response || Session-Kennung. Fehlt sie im ersten Request, erzeugt der Server eine und gibt sie zurück; alle Folge-Chunks müssen sie mitsenden.
| 400 || <code>BAD_REQUEST</code> || Keine Datei-Partie, kein Dateiname, kein <code>filename</code> im ersten Teilstück oder ungültiger <code>Content-Range</code>
|-
|-
| Upload-Offset || Response || Anzahl der bereits gespeicherten Bytes (= Startoffset des nächsten Chunks)
| 400 || <code>IDEMPOTENCY_KEY_MISSING</code> || <code>Idempotency-Key</code> fehlt
|-
|-
| Range || Response || Bereits gespeicherter Bereich (<code>bytes=0-N</code>)
| 413 || <code>PAYLOAD_TOO_LARGE</code> || '''maximale Dateigröße (MB)''' überschritten
|-
| 415 || <code>UNSUPPORTED_MEDIA_TYPE</code> || Endpunkt ohne '''Datei-Upload''' oder Upload mit <code>Content-Encoding</code>
|-
| 422 || <code>IDEMPOTENCY_KEY_REUSED</code> || Derselbe Key mit anderem Inhalt
|}
|}


Der Server hängt einen Chunk '''nur an, wenn START dem bereits gespeicherten Stand
Alle übrigen Fehlercodes: [[OBS/Kostenpflichtige Module/RESTServer/HTTP-Schnittstelle#Fehlercodes|HTTP-Schnittstelle]].
entspricht'''. Bei Abweichung (doppelter Chunk, Lücke) wird nicht angehängt,
 
sondern der aktuelle ''Upload-Offset'' zurückgemeldet - der Client setzt ab dort
== Beispiel ==
neu auf. Eine separate Statusabfrage ist für ein Resume daher nicht zwingend nötig.
Das Skript prüft eine mitgesendete Prüfsumme und übernimmt die Datei. Die Ablage steht für Ihre eigene Verarbeitung.
 
<syntaxhighlight lang="delphi">
procedure Post(oReader: TxRestReader; oWriter: TxRestWriter);
var cPfad  : string;
    cName  : string;
    cSha    : string;
    cBemerk : string;
begin
    cPfad  := oReader.UploadPath();
    cName  := oReader.UploadName();
    cSha    := Lower(AllTrim(oReader.Param('x-datei-sha256')));
    cBemerk := oReader.Form('bemerkung');
 
    if (not Empty(cSha)) and (cSha <> oReader.UploadSha()) then begin
        oWriter.Error(422, 'CHECKSUM_MISMATCH', 'Pruefsumme der Datei passt nicht');
        exit;
    end;


Überschreitet ein Chunk bzw. die Gesamtgrösse das Limit (''re_upload_size''),
    // ... Datei aus cPfad an ihren Zielort uebernehmen, cBemerk speichern ...
antwortet der Server mit '''413 Payload Too Large'''.


{{Hinweis|Der Upload-Status liegt prozesslokal im Speicher. Nach einem Neustart des Servers muss ein unvollständiger Upload neu begonnen werden.}}
    oWriter.Str('dateiname', cName);
    oWriter.Status(201);
end;
</syntaxhighlight>


== Komprimierte Uploads ==
Erstes Teilstück eines fortsetzbaren Uploads:


Ein Upload-Körper mit dem Header <code>Content-Encoding</code> wird mit '''415 Unsupported Media Type''' abgewiesen - bei beiden Verfahren, einfach wie chunked.
<syntaxhighlight lang="bash">
curl -X POST "https://obs.example.com:8443/beispiel/belege" \
  -H "apikey: abcdef-ghij-klmn-opqr-stuvwx" \
  -H "Idempotency-Key: 5c8a2e4f-1b3d-4f6a-9e7c-0d2b4a6c8e1f" \
  -H "Content-Range: bytes 0-1048575/5000000" \
  -H "Upload-Metadata: filename ZmlsZS5wZGY=,filetype YXBwbGljYXRpb24vcGRm" \
  -H "Content-Type: application/octet-stream" \
  --data-binary @teil1.bin
</syntaxhighlight>


Der Grund ist nicht Bequemlichkeit. Bei einem chunked Upload bliebe offen, ob <code>Content-Range</code> die gepackten oder die rohen Bytes zählt, und die SHA256-Prüfsumme bezöge sich nach einem Entpacken auf eine andere Datei, als der Client gesendet hat. Etablierte Protokolle - tus, S3 Multipart, Google Resumable Upload, Azure Blob - behandeln Kompression aus demselben Grund als Eigenschaft der '''gespeicherten Datei''' und nicht der Übertragung.
Die Antwort '''308''' enthält die <code>Upload-Id</code>. Das nächste Teilstück sendet sie mit und beginnt bei <code>Upload-Offset</code>.


Wer gepackt hochladen will, packt die Datei '''selbst''' und lädt sie als <code>export.csv.gz</code> hoch. Offsets, Prüfsumme und Wiederaufnahme stimmen dann, und das Endpunkt-Skript bekommt Name und Typ wie gewohnt über <code>oReader.UploadName()</code> und <code>oReader.UploadType()</code>.
== Siehe auch ==
* [[OBS/Kostenpflichtige Module/RESTServer/Scripting|Scripting]]
* [[OBS/Kostenpflichtige Module/RESTServer/Datei-Download|Datei-Download]]
* [[OBS/Kostenpflichtige Module/RESTServer/Endpunkte|Endpunkte]]
* [[OBS/Kostenpflichtige Module/RESTServer/HTTP-Schnittstelle|HTTP-Schnittstelle]]
* [[OBS/Kostenpflichtige Module/RESTServer/Beispiel6|Beispiel 6]]

Version vom 17. November 2026, 06:59 Uhr

Datei-Upload

Fotos, Unterschriften, Dokumente: Ein Endpunkt nimmt Dateien direkt vom Gerät entgegen. Große Dateien überträgt der Client in Teilstücken und setzt nach einem Verbindungsabbruch dort fort, wo er stehen geblieben ist. Diese Seite beschreibt die Übertragung: was ein Client senden muss und was der Server antwortet.

Was das Skript von einem Upload sieht, steht unter Scripting. Ein vollständiges Beispiel zeigt Beispiel 6.

HINWEIS: Ein Endpunkt nimmt Dateien nur an, wenn in seiner Eingabemaske der Haken Datei-Upload gesetzt ist. Die Grenze legt das Feld maximale Dateigröße (MB) fest, ohne Angabe 25 MB. Siehe Endpunkte.

Aufruf

Ein Upload ist ein POST an den Endpunkt. Es gibt zwei Wege:

Weg Erkennung Wofür
Einfacher Upload Content-Type: multipart/form-data eine Datei in einer Anfrage, mit Formularfeldern
Fortsetzbarer Upload Header Content-Range große Dateien in Teilstücken, fortsetzbar nach einem Abbruch

Beide Wege brauchen wie jeder schreibende Aufruf den Header Idempotency-Key, siehe Idempotenz.

Parameter

Parameter Typ Pflicht Standard Bedeutung
Idempotency-Key Header ✓ – Kennung des Vorgangs, höchstens 128 Zeichen. Beim fortsetzbaren Upload an jedem Teilstück.
Content-Type Header ✓ – Einfacher Upload: multipart/form-data; boundary=…
Datei-Partie Formular ✓ – Einfacher Upload: Partie mit filename= in Content-Disposition. Ihr Content-Type wird zu UploadType().
weitere Partien Formular – – Einfacher Upload: Zusatzangaben ohne filename=, im Skript über oReader.Form
Content-Range Header ✓ – Fortsetzbarer Upload: bytes START-END/TOTAL für ein Teilstück, bytes */TOTAL für eine Statusabfrage
Upload-Id Header – vom Server vergeben Fortsetzbarer Upload: Kennung des Uploads. Fehlt sie am ersten Teilstück, vergibt der Server eine. Alle weiteren Anfragen senden sie mit.
Upload-Metadata Header ✓ – Fortsetzbarer Upload, nur am ersten Teilstück: filename (Pflicht) und filetype (optional), Werte Base64-kodiert

API-Key, Token und die übrigen Header jeder Anfrage beschreibt HTTP-Schnittstelle.

Einfacher Upload (multipart/form-data)

Eine Datei je Anfrage. Name und Content-Type der Datei stammen aus der Datei-Partie. Der Server speichert die erste Partie mit filename=, weitere Datei-Partien ignoriert er. Danach ruft er das Skript auf.

  • Die maximale Dateigröße (MB) gilt für den gesamten Körper der Anfrage, also Datei samt Formularfeldern.
  • Die übrigen Partien liest das Skript mit oReader.Form('<name>'). Der Wert ist UTF-8 und wird nach 1024 Zeichen gekürzt. Vom Namen bleiben nur Buchstaben, Ziffern und Unterstrich, höchstens 40 Zeichen.
  • Fehlt eine Datei-Partie oder ihr Dateiname, antwortet der Server mit 400. Das Skript läuft nicht.
curl -X POST "https://obs.example.com:8443/beispiel/belege" \
  -H "apikey: abcdef-ghij-klmn-opqr-stuvwx" \
  -H "Idempotency-Key: 7b1e4c2a-9f3d-4a6e-8c5b-2d0f1e3a4b6c" \
  -F "datei=@lieferschein.pdf;type=application/pdf" \
  -F "bemerkung=Unterschrift Kunde"

Fortsetzbarer Upload (Content-Range)

Für große Dateien sendet der Client die Datei in Teilstücken, jedes als eigenen POST mit dem Header Content-Range. Der Server hängt die Teilstücke der Reihe nach an. Das Skript läuft erst, wenn die Datei vollständig ist. Es erhält dann dieselben Werte wie beim einfachen Upload.

Name und Typ der Datei sendet der Client im ersten Teilstück im Header Upload-Metadata. Das Format: durch Komma getrennte Paare aus Schlüssel und Base64-Wert.

Upload-Metadata: filename ZmlsZS5wZGY=,filetype YXBwbGljYXRpb24vcGRm

Fehlt filename im ersten Teilstück, antwortet der Server mit 400 und legt keine Datei an. Folgende Teilstücke und Statusabfragen brauchen die Angaben nicht erneut.

Ablauf

Anfrage Antwort des Servers
Erstes Teilstück, z.B. Content-Range: bytes 0-1048575/5000000, mit Upload-Metadata 308 mit Upload-Id, Upload-Offset und Range
Weitere Teilstücke, jeweils mit Upload-Id 308 mit aktuellem Upload-Offset
Letztes Teilstück: Die gespeicherten Bytes erreichen TOTAL Antwort des Skripts, z.B. 201
Statusabfrage Content-Range: bytes */5000000 mit Upload-Id 308 mit aktuellem Upload-Offset, ohne etwas anzuhängen
Header der Antwort Bedeutung
Upload-Id Kennung des Uploads
Upload-Offset Zahl der gespeicherten Bytes = Startposition des nächsten Teilstücks
Range Gespeicherter Bereich, z.B. bytes=0-1048575. Fehlt, solange nichts gespeichert ist.

Fortsetzen nach einem Abbruch

  • Der Server hängt ein Teilstück nur an, wenn START genau dem gespeicherten Stand entspricht. Passt START nicht (doppeltes Teilstück, Lücke), hängt er nichts an und antwortet mit 308 und dem aktuellen Upload-Offset. Der Client setzt dort neu an. Eine eigene Statusabfrage ist dafür nicht nötig.
  • Ist die Upload-Id unbekannt, antwortet der Server auf eine Statusabfrage oder ein Teilstück mit START größer 0 mit 308 und Upload-Offset: 0. Der Client beginnt dann von vorn.
  • Der Stand eines Uploads liegt im Arbeitsspeicher des Dienstes. Nach einem Neustart ist er verloren, die Upload-Id ist dann unbekannt.

Grenzen

  • Ist TOTAL größer als die maximale Dateigröße (MB), antwortet der Server mit 413. Dasselbe gilt, wenn ein Teilstück die Grenze überschreiten würde.
  • Formularfelder gibt es hier nicht. Zusatzangaben sendet der Client als Query-Parameter oder Header, das Skript liest sie mit oReader.Param.
  • Ein ungültiger Content-Range-Wert führt zu 400.

Idempotenz

Jeder Upload ist ein POST und braucht den Header Idempotency-Key. Fehlt er, antwortet der Server mit 400 IDEMPOTENCY_KEY_MISSING, bevor er die Datei speichert.

  • Gleicher Inhalt heißt: dieselben Bytes. Das gilt für jede Dateigröße. Bei multipart/form-data zählt der boundary-Wert nicht mit. Ein neuer Trenner bei der Wiederholung ist also erlaubt.
  • Fortsetzbarer Upload: Jedes Teilstück braucht den Header. Sie können für alle Teilstücke denselben Key verwenden. Eine Antwort 308 gibt den Key wieder frei, gespeichert wird erst die abschließende 2xx-Antwort des Skripts.
  • Wiederholt der Client das letzte Teilstück oder einen einfachen Upload mit demselben Key und Inhalt, erhält er die gespeicherte Antwort. Das Skript läuft nicht noch einmal.
ACHTUNG: Verwenden Sie für eine andere Datei immer einen neuen Key. Derselbe Key mit anderem Inhalt endet mit 422 IDEMPOTENCY_KEY_REUSED.

Regeln zur Idempotenz allgemein: HTTP-Schnittstelle.

Komprimierte Uploads

Einen Upload mit dem Header Content-Encoding, z.B. gzip, weist der Server mit 415 ab. Das gilt für beide Wege. Nur identity ist zulässig.

Der Grund: Beim fortsetzbaren Upload bliebe offen, ob Content-Range gepackte oder entpackte Bytes zählt. Und die Prüfsumme UploadSha() bezöge sich auf eine andere Datei, als der Client gesendet hat.

Wollen Sie gepackt hochladen, packen Sie die Datei selbst und laden sie z.B. als export.csv.gz hoch. Offsets, Prüfsumme und Fortsetzen stimmen dann.

Rückgabe

Status code Bedeutung
2xx – Antwort des Skripts nach vollständigem Upload
308 – Teilstück gespeichert oder Statusabfrage beantwortet. Weiter ab Upload-Offset.
400 BAD_REQUEST Keine Datei-Partie, kein Dateiname, kein filename im ersten Teilstück oder ungültiger Content-Range
400 IDEMPOTENCY_KEY_MISSING Idempotency-Key fehlt
413 PAYLOAD_TOO_LARGE maximale Dateigröße (MB) überschritten
415 UNSUPPORTED_MEDIA_TYPE Endpunkt ohne Datei-Upload oder Upload mit Content-Encoding
422 IDEMPOTENCY_KEY_REUSED Derselbe Key mit anderem Inhalt

Alle übrigen Fehlercodes: HTTP-Schnittstelle.

Beispiel

Das Skript prüft eine mitgesendete Prüfsumme und übernimmt die Datei. Die Ablage steht für Ihre eigene Verarbeitung.

procedure Post(oReader: TxRestReader; oWriter: TxRestWriter);
var cPfad   : string;
    cName   : string;
    cSha    : string;
    cBemerk : string;
begin
    cPfad   := oReader.UploadPath();
    cName   := oReader.UploadName();
    cSha    := Lower(AllTrim(oReader.Param('x-datei-sha256')));
    cBemerk := oReader.Form('bemerkung');

    if (not Empty(cSha)) and (cSha <> oReader.UploadSha()) then begin
        oWriter.Error(422, 'CHECKSUM_MISMATCH', 'Pruefsumme der Datei passt nicht');
        exit;
    end;

    // ... Datei aus cPfad an ihren Zielort uebernehmen, cBemerk speichern ...

    oWriter.Str('dateiname', cName);
    oWriter.Status(201);
end;

Erstes Teilstück eines fortsetzbaren Uploads:

curl -X POST "https://obs.example.com:8443/beispiel/belege" \
  -H "apikey: abcdef-ghij-klmn-opqr-stuvwx" \
  -H "Idempotency-Key: 5c8a2e4f-1b3d-4f6a-9e7c-0d2b4a6c8e1f" \
  -H "Content-Range: bytes 0-1048575/5000000" \
  -H "Upload-Metadata: filename ZmlsZS5wZGY=,filetype YXBwbGljYXRpb24vcGRm" \
  -H "Content-Type: application/octet-stream" \
  --data-binary @teil1.bin

Die Antwort 308 enthält die Upload-Id. Das nächste Teilstück sendet sie mit und beginnt bei Upload-Offset.

Siehe auch