Zum Inhalt springen

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

Aus OBS Wiki
Rademacker (Diskussion | Beiträge)
Keine Bearbeitungszusammenfassung
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]
 
(2 dazwischenliegende Versionen desselben Benutzers werden nicht angezeigt)
Zeile 1: Zeile 1:
{{Kostenpflichtige Module}}
{{Vorlage:Kostenpflichtige Module}}
 
{{Seitentyp|Referenz}}
= Datei-Download =
= Datei-Download =


Ein Endpunkt kann statt eines JSON-Körpers eine '''Datei''' ausliefern - PDF, CSV,
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.
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 [[OBS/Kostenpflichtige Module/RESTServer/Datei-Upload|Datei-Upload]]
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 es dafür '''keine Freischaltung''' am Endpunkt. Ein Download entsteht
dadurch, dass das Skript ihn erzeugt, nicht dadurch, dass ein Client ihn anfragt.


== Die zwei Aufrufe ==
== 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 !! Wiederaufsetzbar
! Aufruf !! Für !! Nach dem Senden !! Fortsetzbar
|-
|-
| <code>oWriter.SendFile(cPfad, cName, cTyp)</code> || Dateien, die es schon gibt und weiter geben wird || bleibt liegen || '''ja''' (206/Range)
| <code>SendFile</code> || Dateien, die es schon gibt und weiter geben wird || bleibt liegen || ✓ (206 mit <code>Range</code>)
|-
|-
| <code>oWriter.SendTempFile(cPfad, cName, cTyp)</code> || Ergebnisse, die je Abruf entstehen || wird '''gelöscht''' || nein
| <code>SendTempFile</code> || Ergebnisse, die je Abruf entstehen, z.B. ein Export || wird gelöscht || –
|}
|}


<syntaxhighlight lang="pascal" line>
== Parameter ==
procedure Get(oReader: TxRestReader; oWriter: TxRestWriter);
{| class="wikitable"
var cUid : string;
! Parameter !! Typ !! Pflicht !! Standard !! Bedeutung
    cPfad: string;
|-
    cName: string;
| <code>cPfad</code> || string || ✓ || – || Vollständiger Pfad der Datei auf dem Server
begin
|-
    cUid := oReader.Path('uid');
| <code>cName</code> || string || – || <code>download</code> || Dateiname, den der Client vorgeschlagen bekommt. Ein Verzeichnisanteil wird entfernt.
 
|-
    if (not BelegGehoertZuMandant(oReader.Claim('tenant'), cUid)) then begin
| <code>cTyp</code> || string || – || <code>application/octet-stream</code> || Content-Type der Datei, z.B. <code>application/pdf</code>
        oWriter.Error(404, 'NOT_FOUND', 'Beleg nicht gefunden');
|}
        exit;
    end;
 
    cPfad := BelegPfad(cUid);
    cName := 'Rechnung_' + cUid + '.pdf';
 
    oWriter.SendFile(cPfad, cName, 'application/pdf');
end;
</syntaxhighlight>


{{Hinweis|'''Datei oder Felder - nicht beides.''' Schreibt ein Skript 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 wie eine
unbalancierte Verschachtelung: der Server antwortet '''500''' und nennt die Stelle
im Protokoll. <code>Error()</code> nach <code>SendFile</code> verwirft die Datei
und liefert die Fehlerhülle - die Ablehnung gewinnt.}}


== Was der Server dazu tut ==
== Was der Server dazu tut ==
{| class="wikitable"
{| class="wikitable"
! Kopfzeile !! Wert
! Header !! Wert
|-
|-
| Content-Type || der übergebene Typ; ohne Angabe <code>application/octet-stream</code>
| <code>Content-Type</code> || der übergebene Typ
|-
|-
| Content-Disposition || <code>attachment</code> mit dem übergebenen Namen, nach RFC&nbsp;5987 kodiert
| <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 Grösse und Änderungszeitpunkt
| <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 schreibt der Server zwei Angaben: <code>filename=</code> mit einem
ausgeschriebenen Rückfallnamen (''Rechnung_Müller.pdf'' wird zu
''Rechnung_Mueller.pdf'') und <code>filename*=</code> mit dem echten Namen
UTF-8-kodiert. Jeder heutige Browser nimmt den zweiten.


Der Pfad wird '''nicht geprüft'''. Ein Skript kann über <code>Base.GFile</code>
Den '''Statuscode''' der Datei bestimmt das Skript, ohne Angabe 200. Wird ein Bereich angefordert und geliefert, wird daraus '''206'''.
ohnehin jede Datei des Servers lesen; eine Schranke nur an dieser Stelle würde
Sicherheit vortäuschen, die es nicht gibt.


{{Hinweis|'''Den Pfad niemals ungeprüft aus einem Client-Wert bilden.''' Ein
Der '''Pfad wird nicht geprüft'''. Ein Skript kann über die Dateifunktionen ohnehin jede Datei lesen, auf die der Dienst Zugriff hat.
Endpunkt <code>/public/{name}</code>, der <code>{name}</code> an ein
Basisverzeichnis hängt, liefert bei <code>..%2F..%2Fobs.ini</code> die
Konfiguration aus. Entweder eine feste Zuordnung im Skript (''apk'' -> fester
Pfad), oder eine Tabelle mit freigegebenen Dateien - nie den Rohwert.}}


== Wiederaufnahme abgebrochener Downloads ==
{{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 Kopf <code>Range</code> aus.
== Fortsetzen abgebrochener Downloads ==
Unterstützt wird '''ein''' Bereich je Anfrage, in den drei Formen, die Clients
Bei <code>SendFile</code> wertet der Server den Header <code>Range</code> aus. Unterstützt wird '''ein''' Bereich je Anfrage:
tatsächlich senden:


{| 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 Offset bis zum Ende
| <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 &lt;von&gt;-&lt;bis&gt;/&lt;gesamt&gt;</code>.
<code>Content-Range: bytes &lt;von&gt;-&lt;bis&gt;/&lt;gesamt&gt;</code>.


{| class="wikitable"
{| class="wikitable"
! Fall !! Antwort
! Fall !! Antwort
|-
|-
| Kein <code>Range</code>-Kopf || '''200''' mit der ganzen Datei
| 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
|-
|-
| Mehrere Bereiche (Komma) || '''200''' mit der ganzen Datei - die Spezifikation erlaubt das ausdrücklich
| Bereich beginnt hinter dem Dateiende, oder die Datei ist leer || '''416''' <code>RANGE_NOT_SATISFIABLE</code> mit <code>Content-Range: bytes */&lt;gesamt&gt;</code>
|-
|-
| Bereich hinter dem Dateiende || '''416 Range Not Satisfiable''' mit <code>Content-Range: bytes */&lt;gesamt&gt;</code>
| <code>If-Range</code> passt nicht zum aktuellen <code>ETag</code> || '''200''' mit der ganzen Datei
|-
|-
| <code>If-Range</code> stimmt nicht mehr || '''200''' mit der ganzen Datei
| <code>SendTempFile</code> || <code>Range</code> wird ignoriert, '''200''' mit der ganzen Datei
|}
|}


'''Warum <code>If-Range</code> zählt:''' Setzt ein Client einen Download fort und
'''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 hat sich zwischenzeitlich geändert, entstünde aus zwei Ständen eine
 
Datei, die erst beim Öffnen auffällt. Schickt der Client seinen ETag in
{{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 und passt der nicht mehr, liefert der Server lieber alles
neu.


{{Hinweis|'''SendTempFile kann nicht fortgesetzt werden''', und das ist keine
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]].
Lücke: Die Datei ist nach dem Senden gelöscht, ein zweiter Abruf fände sie nicht
mehr vor - und eine Neuerzeugung lieferte andere Bytes, sobald sich die Daten
geändert haben. Der Server meldet deshalb <code>Accept-Ranges: none</code>, damit
ein Client es gar nicht erst versucht.}}


== Ö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 Artefakte, die für jeden bestimmt sind - eine Test-APK, ein Handbuch - kann
Die Berechtigung ist die eigentliche Grenze: Für jeden anderen Endpunkt antwortet der Server diesem Zugang mit '''403'''.
der Endpunkt ohne <code>apikey</code>-Header erreichbar sein. Dafür genügt
Konfiguration, siehe
[[OBS/Kostenpflichtige Module/RESTServer/Zugaenge|Zugänge]]:
 
# Zugang mit <code>ra_apikey = *</code>, <code>ra_jwt = 0</code>, <code>ra_cors_origin</code> '''leer'''
# In <code>RESTSRV_ACCESS</code> '''nur''' diesen einen Endpunkt freigeben
 
Die zweite Zeile ist die eigentliche Grenze: Für jeden anderen Endpunkt antwortet
der Server '''403''', auch wenn der Zugang existiert.


{{Hinweis|'''Nur für wirklich öffentliche Dateien.''' Ohne API-Key kennt 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.}}
Endpunkt weder Mandant noch Rolle - es gibt nichts, woran er eine Berechtigung
festmachen könnte ausser dem, was in der URL steht. Kundenbelege gehören deshalb
über den authentifizierten Weg, nicht hierher.}}


Für eine Android-APK kommt hinzu: Content-Type
Für eine Android-App übergeben Sie als Typ <code>application/vnd.android.package-archive</code>.
<code>application/vnd.android.package-archive</code>, am Gerät muss "Unbekannte
Apps installieren" für den Browser freigegeben sein, und die Signatur sollte über
alle Testversionen konstant bleiben - sonst gibt es beim späteren Wechsel in den
Play Store auf jedem Testgerät einen Installationskonflikt.


== 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"
! Was !! Stand
! Status !! Bedeutung
|-
| HEAD || wird '''nicht''' unterstützt (''405''). Browser brauchen es nicht; relevant nur für <code>wget --continue</code>, <code>curl -C -</code> und Download-Manager, die meist auf GET zurückfallen.
|-
|-
| Mehrere Bereiche je Anfrage || nicht unterstützt (ganze Datei mit 200)
| 200 bzw. Status des Skripts || ganze Datei
|-
|-
| Liegengebliebene Temp-Dateien || Bricht der Server mitten im Senden ab, bleibt eine <code>SendTempFile</code>-Datei stehen. Das temporäre Verzeichnis wird von aussen geleert.
| 206 || angeforderter Bereich
|-
|-
| Idempotenz || Eine Dateiantwort wird '''nicht''' im Idempotenz-Store festgeschrieben - sie liesse sich nicht wiedergeben. Der <code>Idempotency-Key</code> bleibt danach benutzbar.
| 416 || Bereich nicht erfüllbar, JSON-Fehlerantwort statt Datei
|-
|-
| Kompression || Dateiantworten werden '''nicht''' gepackt, auch wenn der Client <code>Accept-Encoding: gzip</code> sendet. Sie sind meist bereits komprimiert (PDF, Bild, ZIP), und ein gepackter Auslauf hätte keine feste Länge mehr - <code>Content-Length</code>, <code>ETag</code>, <code>Accept-Ranges</code> und die Wiederaufnahme hängen daran. Wer einen grossen CSV- oder XML-Export gepackt ausliefern will, packt ihn im Skript und liefert ihn als <code>.gz</code> aus.
| 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
HINWEIS: Datei oder Felder, nicht beides. Schreibt ein Skript Felder und ruft 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.

ACHTUNG: Bilden Sie den Pfad nie ungeprüft aus einem Wert des Clients. Ein Endpunkt /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.

HINWEIS: 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:

  1. Ein Zugang mit API-Key *, ohne Haken JWT-Authentifizierung und mit leerem CORS-Origin.
  2. 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.

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 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

Siehe auch