Zum Inhalt springen

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

Aus OBS Wiki
MINERVA-Rademacker (Diskussion | Beiträge)
K MINERVA-Rademacker verschob die Seite OBS/Kostenpflichtige Module/RESTServer/Datei-Upload nach OBS/Kostenpflichtige Module/REST-Server/Datei-Upload: Titel an Überschrift angeglichen (REST-Server, Umlaute, sprechende Beispieltitel)
MINERVA-Rademacker (Diskussion | Beiträge)
Links auf die neuen Titel (REST-Server, Zugänge, Beispiele) umgestellt, zitierte Meldungen mit Umlauten wie im Programm [Volltext ersetzt]
 
Zeile 5: Zeile 5:
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.
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 [[OBS/Kostenpflichtige Module/RESTServer/Scripting#Datei-Uploads|Scripting]]. Ein vollständiges Beispiel zeigt [[OBS/Kostenpflichtige Module/RESTServer/Beispiel6|Beispiel 6]].
Was das Skript von einem Upload sieht, steht unter [[OBS/Kostenpflichtige Module/REST-Server/Scripting#Datei-Uploads|Scripting]]. Ein vollständiges Beispiel zeigt [[OBS/Kostenpflichtige Module/REST-Server/Beispiele/Datei-Upload und Ablage|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 [[OBS/Kostenpflichtige Module/RESTServer/Endpunkte|Endpunkte]].}}
{{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/REST-Server/Endpunkte|Endpunkte]].}}


== Aufruf ==
== Aufruf ==
Zeile 41: Zeile 41:
|}
|}


API-Key, Token und die übrigen Header jeder Anfrage beschreibt [[OBS/Kostenpflichtige Module/RESTServer/HTTP-Schnittstelle|HTTP-Schnittstelle]].
API-Key, Token und die übrigen Header jeder Anfrage beschreibt [[OBS/Kostenpflichtige Module/REST-Server/HTTP-Schnittstelle|HTTP-Schnittstelle]].


== Einfacher Upload (multipart/form-data) ==
== Einfacher Upload (multipart/form-data) ==
Zeile 111: Zeile 111:
{{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>.}}
{{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]].
Regeln zur Idempotenz allgemein: [[OBS/Kostenpflichtige Module/REST-Server/HTTP-Schnittstelle#Idempotenz|HTTP-Schnittstelle]].


== Komprimierte Uploads ==
== Komprimierte Uploads ==
Zeile 139: Zeile 139:
|}
|}


Alle übrigen Fehlercodes: [[OBS/Kostenpflichtige Module/RESTServer/HTTP-Schnittstelle#Fehlercodes|HTTP-Schnittstelle]].
Alle übrigen Fehlercodes: [[OBS/Kostenpflichtige Module/REST-Server/HTTP-Schnittstelle#Fehlercodes|HTTP-Schnittstelle]].


== Beispiel ==
== Beispiel ==
Zeile 157: Zeile 157:


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


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


     oWriter.Str('dateiname', cName);
     oWriter.Str('dateiname', cName);
Zeile 183: Zeile 183:


== Siehe auch ==
== Siehe auch ==
* [[OBS/Kostenpflichtige Module/RESTServer/Scripting|Scripting]]
* [[OBS/Kostenpflichtige Module/REST-Server/Scripting|Scripting]]
* [[OBS/Kostenpflichtige Module/RESTServer/Datei-Download|Datei-Download]]
* [[OBS/Kostenpflichtige Module/REST-Server/Datei-Download|Datei-Download]]
* [[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/Beispiel6|Beispiel 6]]
* [[OBS/Kostenpflichtige Module/REST-Server/Beispiele/Datei-Upload und Ablage|Beispiel 6]]

Aktuelle Version vom 17. November 2026, 07:23 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', 'Prüfsumme der Datei passt nicht');
        exit;
    end;

    // ... Datei aus cPfad an ihren Zielort übernehmen, 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