/app/output geschrieben – binden Sie dort also ein Volume ein, sonst gehen sie zusammen mit dem Container verloren. Siehe Konfiguration.
Ablauf eines Parsing-Vorgangs
Das Parsing erfolgt asynchron. Sie übermitteln ein Document und erhalten sofort eine Job-ID zurück, fragen den Job ab, bis er einen Endzustand erreicht hat, und laden anschließend das Ergebnis herunter. Die Erkennung läuft auf einem einzelnen Worker innerhalb des Containers, und zwar immer nur ein Document gleichzeitig, sodass die HTTP-Verbindung nie über die gesamte Dauer einer Erkennung offen gehalten wird.1
Übermitteln
POST /parse mit dem Dokument und einem Ausgabetyp. Die Antwort lautet 202 Accepted und enthält die Job-ID.2
Abfragen
GET /jobs/{id}, bis status den Wert successful, failed oder cancelled hat.3
Herunterladen
GET /jobs/{file}, wobei file der in der Statusantwort angegebene Pfad ist. Das Ergebnis wird als Attachment zurückgestreamt.Endpunkte
Jede Fehlerantwort ist ein JSON-Objekt mit einem Felderror, das das Problem beschreibt. Einige enthalten zusätzlich ein Feld code oder status, wie unten angegeben.
POST /parse
Übermitteln Sie ein Document. Senden Sie es alsmultipart/form-data mit einem Feld file, das das Document enthält, und einem Feld outputType mit dem Wert doclang, json oder txt. Siehe Ausgabeformate.
Bei erfolgreicher Übermittlung werden 202 Accepted, ein Location-Header, der auf den Job verweist, sowie ein Body mit der Job-ID und dem von FineParser erfassten Dateinamen zurückgegeben.
Die Lizenzprüfung erfolgt, bevor der Upload überhaupt eingelesen wird. Ein nicht lizenzierter Container weist die Anfrage daher ab, ohne dafür Bandbreite oder Festplattenspeicher zu verbrauchen.
GET /jobs/
Gibt den Status eines Jobs zurück.file ist der Pfad des Ergebnisses in der Form {jobId}/{name}. Stellen Sie /jobs/ voran, um die Download-URL zu erhalten. Der Name entspricht dem hochgeladenen Dateinamen mit angehängtem Ausgabetyp: Aus document.pdf, zu DocLang geparst, wird also document.pdf.doclang. Das Feld fehlt, bis der Job erfolgreich war, und verschwindet wieder, wenn das Ergebnis von der Festplatte entfernt wird.
Ein Job kann auch nach der Annahme aus Lizenzgründen fehlschlagen, da die Seitenzahl erst bekannt ist, sobald das Document geladen wurde. In diesem Fall lautet status failed und error weist darauf hin. Für einen fehlgeschlagenen Job wird nichts berechnet.
Gibt 404 zurück, wenn kein solcher Job existiert.
GET /jobs//
Ein Ergebnis herunterladen. Verwenden Sie den Wertfile aus der Status-Antwort als Pfad.
Das Ergebnis wird mit einem zum Ausgabeformat passenden Content-Type und einem Content-Disposition-Header vom Typ attachment zurückgestreamt, der den Dateinamen angibt, sodass curl -OJ die Datei unter dem richtigen Namen speichert. Bereichsanfragen werden nicht unterstützt.
DELETE /jobs/
Entfernt einen Job und dessen Ergebnis von der Festplatte.GET /healthz
Gibt an, ob der Container lizenziert und bereit ist, Documents entgegenzunehmen. Verwenden Sie diesen Endpunkt als Readiness-Probe in Kubernetes oder in Ihrem Orchestrator. Das Container-Image führt ihn außerdem als eigenen Docker-HEALTHCHECK aus.
200 zurück. Ein nicht betriebsbereiter Container gibt 503 zurück – mit ready: false, einem code, der den Grund angibt, und in der Regel einer detail-Meldung. Die Bereitschaft richtet sich ausschließlich nach der Lizenzierung. Telemetriedaten werden zwar mitgemeldet, haben darauf aber keinerlei Einfluss. Siehe Lizenz bestätigen.
Ergebnisse auf der Festplatte
Jedes Ergebnis wird unter/app/output als {jobId}/{name} abgelegt, direkt neben einer kleinen Job-Datenbank. Das Layout ist stabil, sodass Sie Ergebnisse auch direkt vom eingebundenen Volume abholen können, statt sie über HTTP herunterzuladen.
Standardmäßig bleibt ein Ergebnis erhalten, bis Sie den Job per DELETE entfernen oder ihn selbst vom Volume löschen. Nichts verfällt aufgrund seines Alters. Wenn stattdessen FineParser aufräumen soll, starten Sie den Container mit DELETE_ON_DOWNLOAD=true; dann wird jedes Ergebnis samt zugehörigem Job-Datensatz gelöscht, sobald es vollständig heruntergeladen wurde. Danach geben sowohl der Status als auch der Download 404 zurück. Bei einem abgebrochenen Download bleibt das Ergebnis für einen erneuten Versuch erhalten.
Uploads werden in einem separaten temporären Verzeichnis abgelegt und gelöscht, sobald die Recognition abgeschlossen ist – unabhängig vom Ausgang.
Neustarts und Herunterfahren
Jobs werden in der Job-Datenbank auf dem Ausgabe-Volume erfasst und überstehen daher einen Neustart, solange das Volume erhalten bleibt. Ausstehende Jobs werden erneut aufgenommen. Ein Job, der zum Zeitpunkt des Prozessabbruchs gerade ausgeführt wurde, wird alsfailed gekennzeichnet, da der Prozess nicht wissen kann, wie viel des Ergebnisses bereits geschrieben wurde.
Bei einem sauberen Stopp nimmt FineParser keine Anfragen mehr an, lässt laufende Anfragen zu Ende laufen und beendet sich, ohne auf das Dokument zu warten, das gerade erkannt wird. Die Erkennung kann nicht unterbrochen werden, und das Warten darauf könnte das Herunterfahren um Minuten hinauszögern. Dieser Job wird als cancelled gekennzeichnet und sein Teilergebnis wird entfernt. Reichen Sie ihn erneut ein, wenn Sie ihn weiterhin benötigen.
Legen Sie für den Container ein Stopp-Timeout von 60 Sekunden fest – mit --stop-timeout 60 in Docker oder terminationGracePeriodSeconds: 60 in Kubernetes. Der Docker-Standardwert von 10 Sekunden bricht das Auslaufen vorzeitig ab, wodurch die Nutzungstelemetrie seit dem letzten Export verloren geht.
Ein Ausgabeverzeichnis kann immer nur von einem Container verwendet werden. Die Job-Datenbank ist im geöffneten Zustand gesperrt, sodass ein zweiter Container auf demselben Volume den Start verweigert. Zwei Container benötigen zwei Volumes.