Zum Inhalt springen

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

Aus OBS Wiki
MINERVA-Rademacker (Diskussion | Beiträge)
Fehlerfälle 500 und Status des Skripts ergänzt, If-Range nur ETag, 416 bei leerer Datei, Statistik 206/416, Zugang über Maskenfelder, Header statt Kopfzeile [Volltext ersetzt]
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]
 
(Eine dazwischenliegende Version desselben Benutzers wird nicht angezeigt)
Zeile 5: Zeile 5:
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.
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/RESTServer/Datei-Upload|Datei-Upload]] braucht der Endpunkt dafür keine Freischaltung. Ein Download entsteht, weil das Skript ihn erzeugt.
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.


== Aufruf ==
== Aufruf ==
Zeile 92: Zeile 92:
{{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>.}}
{{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>.}}


In der Statistik steht der tatsächlich gesendete Status, also auch '''206''' und '''416''', siehe [[OBS/Kostenpflichtige Module/RESTServer/Betrieb und Fehlersuche|Betrieb und Fehlersuche]].
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/RESTServer/Zugaenge|Zugänge]]:
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'''.
# 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 diesen Zugang die Berechtigung '''nur''' für diesen einen Endpunkt.
Zeile 165: Zeile 165:


== Siehe auch ==
== Siehe auch ==
* [[OBS/Kostenpflichtige Module/RESTServer/Scripting|Scripting]]
* [[OBS/Kostenpflichtige Module/REST-Server/Scripting|Scripting]]
* [[OBS/Kostenpflichtige Module/RESTServer/Datei-Upload|Datei-Upload]]
* [[OBS/Kostenpflichtige Module/REST-Server/Datei-Upload|Datei-Upload]]
* [[OBS/Kostenpflichtige Module/RESTServer/HTTP-Schnittstelle|HTTP-Schnittstelle]]
* [[OBS/Kostenpflichtige Module/REST-Server/HTTP-Schnittstelle|HTTP-Schnittstelle]]
* [[OBS/Kostenpflichtige Module/RESTServer/Zugaenge|Zugänge]]
* [[OBS/Kostenpflichtige Module/REST-Server/Zugänge|Zugänge]]
* [[OBS/Kostenpflichtige Module/RESTServer/Betrieb und Fehlersuche|Betrieb und Fehlersuche]]
* [[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