ドキュメント生成

テンプレートとレコードからドキュメントができます。生成はキューに入り、状態をポーリングし、ダウンロードは回収できない短命の署名付き URL です。

ここのすべてのエンドポイントは documents モジュールを必要とします。生成は非同期です。この API で書き込みが作業を完了させない唯一のモジュールです。

先にストレージの設定が必要

まず前提として、ドキュメントのストレージが設定されていないワークスペースは生成を document_storage_unconfigured で拒否します。これは管理者の設定でクライアントが整えられるものではないため、一時的な失敗ではなく前提条件として扱ってください。

テンプレートはオブジェクトに紐づく

POST /document-templates は name、ドキュメントの出力元となる objectId、layout、version を取ります。

テンプレートはそのオブジェクトが持つフィールドしか指定できません。 存在しないフィールドを参照するレイアウトは、出力時ではなく作成時に template_field_unavailable を返します。壊れたテンプレートが保存されて後で見つかることはありません。

生成はキューであり、レスポンスではない

POST /documents は templateId、recordId、レコードの revision を取ります。作業をキューに入れ、すぐに応答します。

revision はどのバージョンのレコードを出力するかを固定します。承認が承認者の読む内容を固定するのと同じです。つまりドキュメントは、ファイルを開いた時点ではなく生成を依頼した時点のレコードを示します。

template_revision_mismatch は、テンプレートを読んでからドキュメントを依頼するまでの間にテンプレートが変わったことを意味します。テンプレートを読み直して再度依頼してください。

結果のポーリング

GET /documents/{id} は pending・ready・failed のいずれかの status を、inputHash と（出力がある場合は）outputHash とともに返します。

ready か failed になるまでポーリングしてください。 コールバックもストリーミングもありません。pending は待ち続けることを意味します。2 つのハッシュは、同じ入力からの再出力と新しい出力をクライアントが区別する手段です。

再試行とダウンロード

POST /documents/{id}/retry は failed のドキュメント専用です。pending や ready のものは document_not_failed で拒否されるため、再試行が進行中の作業を巻き戻したり完成したファイルを捨てたりすることはありません。

POST /documents/{id}/download は短命の署名付き URL を返します。そこから 2 つのことが導かれます。

• ready でないドキュメントには署名する対象がなく、document_not_ready を返します。
• リンクは回収できません。 一度発行されると、誰が持っていても有効期限まで使えます。そのファイル 1 つに対するベアラー資格情報として扱ってください。ログに出さず、第三者が読めるリダイレクトに入れず、事前にではなく利用者が求めた瞬間に発行してください。

GET ではなく POST なのは、資格情報の発行が読み取りではなく操作だからです。

1 つのスコープが 4 つのエンドポイントを覆う

documents.read はテンプレートの一覧、documents.manage はその作成ですが、生成・状態の読み取り・再試行・ダウンロードはすべて documents.generate を必要とします。 完成したファイルを取得するためのより狭いスコープはないため、ダウンロードできるトークンは生成もできます。