Skip to main content
位置引数を指定せずにコンテナーを起動すると、FineParser はポート 8080 で HTTP サーバーとして動作し、明示的に停止するまで稼働し続けます。アプリケーションやその他のサービスからネットワーク経由で FineParser にDocumentを送信する必要がある場合は、このモードを使用します。
Recognition mode、languages、License はいずれもコンテナーの起動時に設定されるため、requests に認証情報や recognition settings を含める必要はありません。結果 は /app/output に書き込まれるので、その場所にボリュームをマウントしてください。マウントしないと、コンテナーの終了とともに消えてしまいます。Configuration を参照してください。

解析の仕組み

解析は非同期で行われます。Documentを送信するとジョブ ID がすぐに返されるので、ジョブが完了状態になるまでポーリングし、その後に結果をダウンロードします。認識処理はコンテナー内の単一の worker で 1 Documentずつ実行されるため、認識処理が終わるまで HTTP 接続が開いたままになることはありません。
1

送信

Documentと出力タイプを指定して POST /parse を実行します。レスポンスは 202 Accepted で、ジョブ ID が返されます。
2

ポーリング

statussuccessfulfailedcancelled のいずれかになるまで GET /jobs/{id} を実行します。
3

ダウンロード

GET /jobs/{file} を実行します。file にはステータスのレスポンスで返されたパスを指定します。結果は添付ファイルとしてストリーミングで返されます。

エンドポイント

すべてのエラーレスポンスは JSON 形式で、問題の内容を示す error field を含みます。一部のレスポンスには code または status field も含まれます (以下を参照) 。

POST /parse

Document を 1 件送信します。multipart/form-data 形式で送信し、document を格納した file field と、doclangjsontxt のいずれかを指定した outputType field を含めてください。出力形式を参照してください。 送信に成功すると、202 Accepted、ジョブ を指す Location header、および ジョブ の ID と FineParser が記録したファイル名を含む body が返されます。
licensing のチェックはアップロードの読み取りが始まる前に行われるため、License のないコンテナーは帯域や disk を消費することなく request を拒否します。

GET /jobs/

ジョブの状態を返します。
file{jobId}/{name} という形式の結果のパスです。先頭に /jobs/ を付けるとダウンロード URL になります。name はアップロードしたファイル名に出力の型を付加したもので、document.pdf を DocLang に解析した場合は document.pdf.doclang となります。この field はジョブが成功するまで存在せず、結果がディスクから削除されると再び消えます。 page count は Document がロードされて初めて判明するため、ジョブが受理された後で licensing 上の理由により失敗することがあります。その場合、statusfailed となり、error にその旨が記載されます。失敗したジョブに対して課金は発生しません。 該当するジョブが存在しない場合は 404 を返します。

GET /jobs//

結果をダウンロードします。パスにはステータスレスポンスの file の値を使用します。 結果は、出力形式に応じた Content-Type と、ファイル名を示す Content-Disposition の attachment ヘッダーを付けてストリーミング返却されるため、curl -OJ を使えば適切な名前で保存されます。範囲指定のリクエストには対応していません。

DELETE /jobs/

ジョブとその結果をディスクから削除します。

GET /healthz

コンテナーがライセンス認証済みで、Documentを受け付ける準備ができているかどうかを返します。Kubernetes やお使いのオーケストレーターの Readiness プローブとして使用してください。コンテナーイメージ側でも、これを Docker の HEALTHCHECK として実行します。
準備完了のコンテナーは 200 を返します。準備が完了していないコンテナーは 503 を返し、そのレスポンスには ready: false、理由を示す code、通常は detail メッセージが含まれます。準備状態に反映されるのは licensing のみです。テレメトリーは併せて報告されますが、準備状態に影響することはありません。ライセンスの確認を参照してください。

ディスク上の結果

すべての結果は /app/output 配下に {jobId}/{name} として書き込まれ、同じ場所に小さなジョブデータベースが配置されます。このレイアウトは変わらないため、HTTP 経由でダウンロードする代わりに、マウントしたボリュームから直接結果を取得することもできます。 既定では、ジョブを DELETE するか、ボリュームから手動で削除するまで結果は保持されます。経過時間による期限切れはありません。FineParser 側でクリーンアップさせたい場合は、DELETE_ON_DOWNLOAD=true を指定してコンテナーを起動してください。各結果は、完全にダウンロードされた時点でジョブレコードとともに削除されます。それ以降は、ステータスもダウンロードも 404 を返します。ダウンロードが中断された場合は、再試行できるように結果がそのまま残ります。 アップロードされたファイルは別の一時ディレクトリに保持され、認識が終了した時点で (成否にかかわらず) 削除されます。

再起動とシャットダウン

ジョブは出力ボリューム上のジョブデータベースに記録されるため、ボリュームが残っている限り再起動後も保持されます。保留中のジョブは再度取得されて処理されます。プロセスが停止した時点で処理中だったジョブは failed としてマークされます。これは、結果がどこまで書き込まれたかをプロセス側で判断できないためです。 正常な停止時には、FineParser は新しい requests の受け付けを停止し、処理中の requests を完了させたうえで、認識処理中の Document を待たずに終了します。Recognition は中断できないため、その完了を待つとシャットダウンが数分間止まってしまうおそれがあります。該当のジョブは cancelled としてマークされ、部分的な結果は削除されます。引き続き処理が必要な場合は、改めて送信してください。 コンテナーには 60 秒の停止タイムアウトを設定してください。Docker では --stop-timeout 60、Kubernetes では terminationGracePeriodSeconds: 60 を指定します。Docker の既定値である 10 秒ではドレイン処理が途中で打ち切られ、前回のエクスポート以降の使用状況テレメトリがすべて失われます。 1 つの出力ディレクトリを同時に使用できるコンテナーは 1 つだけです。ジョブデータベースは開いている間ロックされるため、同じボリューム上で 2 つ目のコンテナーを起動しようとしても失敗します。2 つのコンテナーを動かすには、ボリュームも 2 つ必要です。