OBS/Kostenpflichtige Module/REST-Server/Datei-Download: Unterschied zwischen den Versionen
Die Seite wurde neu angelegt: „{{Kostenpflichtige Module}} = Datei-Download = Ein Endpunkt kann statt eines JSON-Körpers eine '''Datei''' ausliefern - PDF, CSV, Bilder, eine APK. Das Skript entscheidet das mit einem einzigen Aufruf, alles Weitere macht der Server: Content-Type, Dateiname, Bereichsanfragen und, bei temporären Dateien, das Aufräumen. Anders als beim Datei-Upload braucht es dafür '''keine Freischaltung''' am E…“ |
Links auf die neuen Titel (REST-Server, Zugänge, Beispiele) umgestellt, zitierte Meldungen mit Umlauten wie im Programm [Volltext ersetzt] |
||
| (3 dazwischenliegende Versionen von 2 Benutzern werden nicht angezeigt) | |||
| Zeile 1: | Zeile 1: | ||
{{Kostenpflichtige Module}} | {{Vorlage:Kostenpflichtige Module}} | ||
{{Seitentyp|Referenz}} | |||
= Datei-Download = | = Datei-Download = | ||
Ein Endpunkt | 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 [[OBS/Kostenpflichtige Module/ | Anders als beim [[OBS/Kostenpflichtige Module/REST-Server/Datei-Upload|Datei-Upload]] braucht der Endpunkt dafür keine Freischaltung. Ein Download entsteht, weil das Skript ihn erzeugt. | ||
braucht | |||
== | == Aufruf == | ||
<syntaxhighlight lang="delphi"> | |||
oWriter.SendFile(cPfad, cName, cTyp); | |||
oWriter.SendTempFile(cPfad, cName, cTyp); | |||
</syntaxhighlight> | |||
{| class="wikitable" | {| class="wikitable" | ||
! Aufruf !! Für !! Nach dem Senden !! | ! Aufruf !! Für !! Nach dem Senden !! Fortsetzbar | ||
|- | |- | ||
| <code> | | <code>SendFile</code> || Dateien, die es schon gibt und weiter geben wird || bleibt liegen || ✓ (206 mit <code>Range</code>) | ||
|- | |- | ||
| <code> | | <code>SendTempFile</code> || Ergebnisse, die je Abruf entstehen, z.B. ein Export || wird gelöscht || – | ||
|} | |} | ||
== Parameter == | |||
{| class="wikitable" | |||
! Parameter !! Typ !! Pflicht !! Standard !! Bedeutung | |||
|- | |||
| <code>cPfad</code> || string || ✓ || – || Vollständiger Pfad der Datei auf dem Server | |||
|- | |||
| <code>cName</code> || string || – || <code>download</code> || Dateiname, den der Client vorgeschlagen bekommt. Ein Verzeichnisanteil wird entfernt. | |||
|- | |||
| <code>cTyp</code> || string || – || <code>application/octet-stream</code> || Content-Type der Datei, z.B. <code>application/pdf</code> | |||
|} | |||
</ | |||
{{Hinweis|'''Datei oder Felder | {{Hinweis|'''Datei oder Felder, nicht beides.''' Schreibt ein Skript Felder '''und''' ruft <code>SendFile</code>, ist das ein Strukturfehler: Der Server antwortet mit '''500''' und nennt die Stelle im Protokoll. <code>oWriter.Error</code> nach <code>SendFile</code> verwirft die Datei und liefert die Fehlerantwort.}} | ||
'''und''' ruft <code>SendFile</code>, ist das ein Strukturfehler | |||
im Protokoll. <code>Error | |||
und liefert die | |||
== Was der Server dazu tut == | == Was der Server dazu tut == | ||
{| class="wikitable" | {| class="wikitable" | ||
! | ! Header !! Wert | ||
|- | |- | ||
| Content-Type || der übergebene Typ | | <code>Content-Type</code> || der übergebene Typ | ||
|- | |- | ||
| Content-Disposition || <code>attachment</code> mit dem übergebenen Namen, nach RFC | | <code>Content-Disposition</code> || <code>attachment</code> mit dem übergebenen Namen, nach RFC 5987 kodiert | ||
|- | |- | ||
| Content-Length || Länge der Datei bzw. des angeforderten Bereichs | | <code>Content-Length</code> || Länge der Datei bzw. des angeforderten Bereichs | ||
|- | |- | ||
| Accept-Ranges || <code>bytes</code> bei <code>SendFile</code>, <code>none</code> bei <code>SendTempFile</code> | | <code>Accept-Ranges</code> || <code>bytes</code> bei <code>SendFile</code>, <code>none</code> bei <code>SendTempFile</code> | ||
|- | |- | ||
| ETag, Last-Modified || nur bei <code>SendFile</code>, aus | | <code>ETag</code>, <code>Last-Modified</code> || nur bei <code>SendFile</code>, aus Größe und Änderungszeitpunkt der Datei | ||
|} | |} | ||
'''Umlaute im Dateinamen''' sind unbedenklich. Header-Werte müssen ASCII sein | '''Umlaute im Dateinamen''' sind unbedenklich. Header-Werte müssen ASCII sein. Der Server schreibt deshalb zwei Angaben: <code>filename=</code> mit einem Ersatznamen (''Rechnung_Müller.pdf'' wird zu ''Rechnung_Mueller.pdf'') und <code>filename*=</code> mit dem echten Namen in UTF-8. Heutige Browser verwenden den zweiten. | ||
deshalb | |||
''Rechnung_Mueller.pdf'') und <code>filename*=</code> mit dem echten Namen | |||
UTF-8 | |||
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. | |||
{{Achtung|'''Bilden Sie den Pfad nie ungeprüft aus einem Wert des Clients.''' Ein Endpunkt <code>/public/{name}</code>, der <code>{name}</code> an ein Verzeichnis hängt, liefert bei <code>..%2F..%2Fobs.ini</code> die Konfiguration aus. Ordnen Sie im Skript fest zu (''apk'' → fester Pfad) oder führen Sie eine Tabelle freigegebener Dateien.}} | |||
Bei <code>SendFile</code> wertet der Server den | == Fortsetzen abgebrochener Downloads == | ||
Unterstützt wird '''ein''' Bereich je Anfrage | Bei <code>SendFile</code> wertet der Server den Header <code>Range</code> aus. Unterstützt wird '''ein''' Bereich je Anfrage: | ||
{| class="wikitable" | {| class="wikitable" | ||
! Range !! Bedeutung | ! Range !! Bedeutung | ||
|- | |- | ||
| <code>bytes=0-1023</code> || fester Bereich | | <code>bytes=0-1023</code> || fester Bereich. Ein Ende hinter dem Dateiende kürzt der Server auf das Dateiende. | ||
|- | |- | ||
| <code>bytes=500-</code> || ab | | <code>bytes=500-</code> || ab Position 500 bis zum Ende | ||
|- | |- | ||
| <code>bytes=-500</code> || die letzten 500 Bytes | | <code>bytes=-500</code> || die letzten 500 Bytes | ||
|} | |} | ||
Der Server antwortet dann mit '''206 Partial Content''' und | Der Server antwortet dann mit '''206 Partial Content''' und <code>Content-Range: bytes <von>-<bis>/<gesamt></code>. | ||
<code>Content-Range: bytes <von>-<bis>/<gesamt></code>. | |||
{| class="wikitable" | {| class="wikitable" | ||
! Fall !! Antwort | ! Fall !! Antwort | ||
|- | |- | ||
| Kein <code>Range</code>- | | Kein <code>Range</code>-Header || '''200''' mit der ganzen Datei | ||
|- | |||
| Mehrere Bereiche (mit Komma) || '''200''' mit der ganzen Datei | |||
|- | |||
| Anderer Wert als <code>bytes=</code> oder nicht lesbar || '''200''' mit der ganzen Datei | |||
|- | |- | ||
| | | Bereich beginnt hinter dem Dateiende, oder die Datei ist leer || '''416''' <code>RANGE_NOT_SATISFIABLE</code> mit <code>Content-Range: bytes */<gesamt></code> | ||
|- | |- | ||
| | | <code>If-Range</code> passt nicht zum aktuellen <code>ETag</code> || '''200''' mit der ganzen Datei | ||
|- | |- | ||
| <code> | | <code>SendTempFile</code> || <code>Range</code> wird ignoriert, '''200''' mit der ganzen Datei | ||
|} | |} | ||
'''Warum <code>If-Range</code> zählt:''' | '''Warum <code>If-Range</code> 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 <code>ETag</code> in <code>If-Range</code> mit. Der Server vergleicht nur den <code>ETag</code>. Ein Datum in <code>If-Range</code> gilt als „passt nicht“, der Server liefert dann die ganze Datei. | ||
die Datei | |||
Datei, die erst beim Öffnen auffällt. | {{Hinweis|<code>SendTempFile</code> 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 <code>Accept-Ranges: none</code>.}} | ||
<code>If-Range</code> mit | |||
In der Statistik steht der tatsächlich gesendete Status, also auch '''206''' und '''416''', siehe [[OBS/Kostenpflichtige Module/REST-Server/Betrieb und Fehlersuche|Betrieb und Fehlersuche]]. | |||
== Öffentliche Dateien ohne API-Key == | == Ö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 <code>apikey</code> erreichbar sein. Dafür genügt die Einrichtung unter [[OBS/Kostenpflichtige Module/REST-Server/Zugänge|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. | |||
Für | Die Berechtigung ist die eigentliche Grenze: Für jeden anderen Endpunkt antwortet der Server diesem Zugang mit '''403'''. | ||
der | |||
{{Achtung|'''Nur für wirklich öffentliche Dateien.''' Ohne API-Key kennt der Endpunkt weder Mandant noch Rolle. Kundenbelege gehören über den Weg mit Anmeldung, nicht hierher.}} | |||
Für eine Android-App übergeben Sie als Typ <code>application/vnd.android.package-archive</code>. | |||
Für eine Android- | |||
<code>application/vnd.android.package-archive</code> | |||
== Grenzen == | == Grenzen == | ||
{| class="wikitable" | |||
! Was !! Verhalten | |||
|- | |||
| <code>HEAD</code> || 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 <code>Idempotency-Key</code> ist danach wieder frei. | |||
|- | |||
| Kompression || Dateiantworten packt der Server nicht, auch nicht bei <code>Accept-Encoding: gzip</code>. Länge, <code>ETag</code> und Fortsetzen hängen an den ungepackten Bytes. Einen großen Export packen Sie im Skript selbst und liefern ihn als <code>.gz</code> aus. | |||
|} | |||
== Rückgabe == | |||
{| class="wikitable" | {| class="wikitable" | ||
! | ! 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''' <code>/beispiel/belege/{nr}/pdf</code> liefert einen Beleg aus. <code>BelegGehoertZuMandant</code> und <code>BelegPfad</code> stehen für Ihre eigenen Funktionen. | |||
<syntaxhighlight lang="delphi"> | |||
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; | |||
</syntaxhighlight> | |||
Fortsetzen eines abgebrochenen Downloads ab Byte 1048576. <code>If-Range</code> trägt den <code>ETag</code> der ersten Antwort unverändert, mit Anführungszeichen: | |||
<syntaxhighlight lang="bash"> | |||
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 | |||
</syntaxhighlight> | |||
== Siehe auch == | |||
* [[OBS/Kostenpflichtige Module/REST-Server/Scripting|Scripting]] | |||
* [[OBS/Kostenpflichtige Module/REST-Server/Datei-Upload|Datei-Upload]] | |||
* [[OBS/Kostenpflichtige Module/REST-Server/HTTP-Schnittstelle|HTTP-Schnittstelle]] | |||
* [[OBS/Kostenpflichtige Module/REST-Server/Zugänge|Zugänge]] | |||
* [[OBS/Kostenpflichtige Module/REST-Server/Betrieb und Fehlersuche|Betrieb und Fehlersuche]] | |||
Aktuelle Version vom 17. November 2026, 07:23 Uhr
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