Assembly Execution Progress
この機能はまだ実験段階です。開発を進める中で、具体的な動作、API、料金が変更される場合があります。不具合や予期しない動作が見つかった場合は、お問い合わせください。
Assembly Execution Progress は、Assembly の実行がどこまで進んだかをリアルタイムで推定します。Assembly 全体と、アップロードされた各ファイル(および original_id を含むインポート)について、進捗率を計算します。そのため、ファイル形式の違いなどにより、同じ
Assembly 内でファイルごとに処理が異なる場合でも、ファイル単位で個別の推定値を取得できます。
この進捗率を計算するために、Assembly エンジンは、Assembly の残りの処理で実行される見込みの
Step を予測します。この予測と完了済みの Step を比較して、進捗を推定します。さらに、実行中の Step の進捗情報を取り入れ、推定の精度を高めます。たとえば、/video/encode の
Step では、現時点で動画のエンコードがどこまで完了しているかという情報を取り入れます。
Assembly Execution Progress は、ファイルの処理状況をユーザーに伝え、ユーザーインターフェースをよりよいものにします。ユーザーのファイルを当社のサーバーに転送する状況を示す通常のアップロード進捗と組み合わせると、Assembly Execution Progress により、ファイルが適切に処理され、バックグラウンドで処理が進んでいることをユーザーに伝えられます。
対応する Assembly
すべての Assembly で Execution Progress を提供できるようにしていますが、あらゆるケースで確実に提供できるわけではありません。Assembly に結果数を予測できない Step が含まれる場合、その Step が完了するまで進捗を推定できません。ただし、該当するすべての Step が完了すると、Execution Progress を計算できます。
結果数を予測できない Step は次のとおりです。
/s3/import、/azure/importなどによるディレクトリのインポート。ファイル数が固定されたインポートは含みません。/file/decompress:アーカイブから、個数が可変のファイルを展開する処理/document/thumbs:ページ番号を指定せずにドキュメントのサムネイルを生成する処理
URL Transform Assembly では
Execution Progress を利用できません(emit_execution_progress フラグは無視されます)。マルチパートアップロードでは、アップロード完了後にメタデータが抽出されるまで、進捗の通知を開始できません。
Assembly Execution Progress の有効化
Execution Progress を受信するには、対象の Assembly ごとに明示的に有効化する必要があります。Assembly の作成時に、"emit_execution_progress": true プロパティを
Assembly Instructions に含めて設定します。例を示します。
{
"steps": {
"resized": {
"robot": "/image/resize",
"use": ":original",
"width": 100,
"height": 100,
"resize_strategy": "fillcrop",
},
// ...
},
// ...
// Enable execution progress
"emit_execution_progress": true,
}
クイックスタート
- Assembly Instructions に
"emit_execution_progress": trueを追加します。 - Assembly 更新ストリームを開きます。
assembly_execution_progressイベントをリッスンし、UI を更新します。
Execution Progress の受信
Assembly Execution Progress は、Assembly 更新ストリームで取得できます。概要としては、Assembly を作成すると、Assembly Status に URL が含まれます。この URL から、Assembly の状態に関するメッセージやイベントをリアルタイムで取得できます。詳しくは、ドキュメントを参照してください。
Assembly の更新ストリームを開き、Execution Progress が有効になっていると、約 2 秒ごとに定期的な進捗更新を受信します。更新は assembly_execution_progress イベントで送信されます。このイベントには、Assembly 全体と、各元ファイル(アップロード、および original_id を含むインポート)の進捗を示す JSON ペイロードが含まれます。例を示します。
{
"progress_combined": 75,
"progress_per_original_file": [
{
"original_id": "6bb16f6cd49a44b4ae431f576e016c6d",
"progress": 50
},
{
"original_id": "56921a2dd46246d3b4d3a98b9f8ed4e1",
"progress": 100
}
]
}
上の例では、Assembly 全体の処理が 75% 完了しています。original_id が 56921a2dd46246d3b4d3a98b9f8ed4e1 のファイルは処理が完了しており、そのファイルのすべての Step を通過しています。original_id が 6bb16f6cd49a44b4ae431f576e016c6d のファイルはまだ完了しておらず、現時点での進捗は 50% です。
進捗を予測できない間は、イベントは送信されません。条件については、対応する Assemblyを参照してください。
公開されている進捗スキーマでは、null を
progress_combined の値として使用することも認められています。この値はゼロや完了として扱わず、進捗不明の UI 状態として安全に処理してください。ただし、予測できない Step の完了を待つ間に、ストリームが
null の更新を送信するという意味ではありません。その間の更新はスキップされます。