OBS/Kostenpflichtige Module/REST-Server/Datei-Download
Datei-Download
Rechnungen als PDF, Exporte als CSV, Bilder oder eine App zum Installieren: Ein Endpunkt liefert statt JSON eine Datei aus. Das Skript entscheidet das mit einem einzigen Aufruf. Content-Type, Dateiname, fortsetzbare Downloads und das Aufräumen temporärer Dateien übernimmt der Server.
Anders als beim Datei-Upload braucht der Endpunkt dafür keine Freischaltung. Ein Download entsteht, weil das Skript ihn erzeugt.
Aufruf
oWriter.SendFile(cPfad, cName, cTyp);
oWriter.SendTempFile(cPfad, cName, cTyp);
| Aufruf | Für | Nach dem Senden | Fortsetzbar |
|---|---|---|---|
SendFile |
Dateien, die es schon gibt und weiter geben wird | bleibt liegen | ✓ (206 mit Range)
|
SendTempFile |
Ergebnisse, die je Abruf entstehen, z.B. ein Export | wird gelöscht | – |
Parameter
| Parameter | Typ | Pflicht | Standard | Bedeutung |
|---|---|---|---|---|
cPfad |
string | ✓ | – | Vollständiger Pfad der Datei auf dem Server |
cName |
string | – | download |
Dateiname, den der Client vorgeschlagen bekommt. Ein Verzeichnisanteil wird entfernt. |
cTyp |
string | – | application/octet-stream |
Content-Type der Datei, z.B. application/pdf
|
SendFile, ist das ein Strukturfehler: Der Server antwortet mit 500 und nennt die Stelle im Protokoll. oWriter.Error nach SendFile verwirft die Datei und liefert die Fehlerantwort.Was der Server dazu tut
| Header | Wert |
|---|---|
Content-Type |
der übergebene Typ |
Content-Disposition |
attachment mit dem übergebenen Namen, nach RFC 5987 kodiert
|
Content-Length |
Länge der Datei bzw. des angeforderten Bereichs |
Accept-Ranges |
bytes bei SendFile, none bei SendTempFile
|
ETag, Last-Modified |
nur bei SendFile, aus Größe und Änderungszeitpunkt der Datei
|
Umlaute im Dateinamen sind unbedenklich. Header-Werte müssen ASCII sein. Der Server schreibt deshalb zwei Angaben: filename= mit einem Ersatznamen (Rechnung_Müller.pdf wird zu Rechnung_Mueller.pdf) und filename*= mit dem echten Namen in UTF-8. Heutige Browser verwenden den zweiten.
Den Statuscode der Datei bestimmt das Skript, ohne Angabe 200. Wird ein Bereich angefordert und geliefert, wird daraus 206.
Der Pfad wird nicht geprüft. Ein Skript kann über die Dateifunktionen ohnehin jede Datei lesen, auf die der Dienst Zugriff hat.
/public/{name}, der {name} an ein Verzeichnis hängt, liefert bei ..%2F..%2Fobs.ini die Konfiguration aus. Ordnen Sie im Skript fest zu (apk → fester Pfad) oder führen Sie eine Tabelle freigegebener Dateien.Fortsetzen abgebrochener Downloads
Bei SendFile wertet der Server den Header Range aus. Unterstützt wird ein Bereich je Anfrage:
| Range | Bedeutung |
|---|---|
bytes=0-1023 |
fester Bereich. Ein Ende hinter dem Dateiende kürzt der Server auf das Dateiende. |
bytes=500- |
ab Position 500 bis zum Ende |
bytes=-500 |
die letzten 500 Bytes |
Der Server antwortet dann mit 206 Partial Content und Content-Range: bytes <von>-<bis>/<gesamt>.
| Fall | Antwort |
|---|---|
Kein Range-Header |
200 mit der ganzen Datei |
| Mehrere Bereiche (mit Komma) | 200 mit der ganzen Datei |
Anderer Wert als bytes= oder nicht lesbar |
200 mit der ganzen Datei |
| Bereich beginnt hinter dem Dateiende, oder die Datei ist leer | 416 RANGE_NOT_SATISFIABLE mit Content-Range: bytes */<gesamt>
|
If-Range passt nicht zum aktuellen ETag |
200 mit der ganzen Datei |
SendTempFile |
Range wird ignoriert, 200 mit der ganzen Datei
|
Warum If-Range zählt: Ändert sich die Datei zwischen zwei Teilen, entstünde aus zwei Ständen eine Datei, die erst beim Öffnen auffällt. Senden Sie deshalb beim Fortsetzen den ETag in If-Range mit. Der Server vergleicht nur den ETag. Ein Datum in If-Range gilt als „passt nicht“, der Server liefert dann die ganze Datei.
SendTempFile ist nicht fortsetzbar. Die Datei ist nach dem Senden gelöscht, und eine Neuerzeugung lieferte andere Bytes, sobald sich die Daten geändert haben. Der Server meldet deshalb Accept-Ranges: none.In der Statistik steht der tatsächlich gesendete Status, also auch 206 und 416, siehe Betrieb und Fehlersuche.
Öffentliche Dateien ohne API-Key
Für Dateien, die für jeden bestimmt sind, etwa eine Test-App oder ein Handbuch, kann ein Endpunkt ohne Header apikey erreichbar sein. Dafür genügt die Einrichtung unter Zugänge:
- Ein Zugang mit API-Key *, ohne Haken JWT-Authentifizierung und mit leerem CORS-Origin.
- Für diesen Zugang die Berechtigung nur für diesen einen Endpunkt.
Die Berechtigung ist die eigentliche Grenze: Für jeden anderen Endpunkt antwortet der Server diesem Zugang mit 403.
Für eine Android-App übergeben Sie als Typ application/vnd.android.package-archive.
Grenzen
| Was | Verhalten |
|---|---|
HEAD |
wird nicht unterstützt (405) |
| Mehrere Bereiche je Anfrage | nicht unterstützt, ganze Datei mit 200 |
| Idempotenz | Eine Dateiantwort auf einen schreibenden Aufruf speichert der Server nicht. Der Idempotency-Key ist danach wieder frei.
|
| Kompression | Dateiantworten packt der Server nicht, auch nicht bei Accept-Encoding: gzip. Länge, ETag und Fortsetzen hängen an den ungepackten Bytes. Einen großen Export packen Sie im Skript selbst und liefern ihn als .gz aus.
|
Rückgabe
| Status | Bedeutung |
|---|---|
| 200 bzw. Status des Skripts | ganze Datei |
| 206 | angeforderter Bereich |
| 416 | Bereich nicht erfüllbar, JSON-Fehlerantwort statt Datei |
| 500 | Datei existiert nicht, Skript setzt Status 204 zusammen mit einer Datei, oder Skript schreibt Felder und Datei |
Ein Skript, das auf eine fehlende Datei zeigt, erzeugt also nie eine leere Antwort mit 200. Der Grund steht im Protokoll.
Beispiel
Ein Endpunkt mit dem Pfad-Template /beispiel/belege/{nr}/pdf liefert einen Beleg aus. BelegGehoertZuMandant und BelegPfad stehen für Ihre eigenen Funktionen.
procedure Get(oReader: TxRestReader; oWriter: TxRestWriter);
var cNr : string;
cPfad: string;
begin
cNr := oReader.Path('nr');
if (not BelegGehoertZuMandant(oReader.Claim('tenant'), cNr)) then begin
oWriter.Error(404, 'NOT_FOUND', 'Beleg nicht gefunden');
exit;
end;
cPfad := BelegPfad(cNr);
oWriter.SendFile(cPfad, 'Rechnung_' + cNr + '.pdf', 'application/pdf');
end;
Fortsetzen eines abgebrochenen Downloads ab Byte 1048576. If-Range trägt den ETag der ersten Antwort unverändert, mit Anführungszeichen:
curl "https://obs.example.com:8443/beispiel/belege/4711/pdf" \
-H "apikey: abcdef-ghij-klmn-opqr-stuvwx" \
-H "Authorization: Bearer <Access-Token>" \
-H "Range: bytes=1048576-" \
-H 'If-Range: "4C4B40-6F1A2B3C"' \
-o rechnung_teil2.pdf