- トランザクション ID.
- Skill ID とバージョン.
- 手順ごとの処理パス:
- Step の種類
- 名前
- Step の開始および終了の日時
- 所要時間 (秒)
- 手動確認オペレーター (手動確認オペレーター) の名前とメールアドレス.
- documents およびトランザクションの登録パラメータ.
Warehouse は、設定により一度も実行されないアクティビティ内の documents 処理イベントに関する情報は保存しません。たとえば、Assemble by files の設定は Vantage のデフォルト動作に対応しているため、このアクティビティでの documents 処理はワークフロー内でスキップされます。
v1 と v2 の動作の違い
移行前に、v1 と v2 では API の形式だけでなく、設計上、報告期間の定義も異なることを理解しておくことが重要です。2 つのバージョンを比較すると、リクエスト／レスポンスの形式だけでなく、合計値も異なることが想定されます。 v1 はトランザクション単位でフィルタリングし、該当するトランザクションのすべての Step を返します。 トランザクション内のいずれかの Step がstartDate/endDate のフィルタ期間と少しでも重複している場合、startDate の数週間前や endDate の後に完了したものを含め、そのトランザクションのすべての Step が返されます。
v2 は Step 単位でフィルタリングします。 CompletedUtc タイムスタンプが startDate/endDate の期間内にある Step のみが返されます。同じトランザクション内の他の Step が期間内にあっても、それ以外の Step は除外されます。
同期リクエストと非同期リクエスト
v1 は単一の同期呼び出しです。クエリパラメーターを含む GET リクエストを送信すると、レスポンスでレポートデータを直接受け取ります。一方、v2 では非同期モデルを使用します。リクエストを送信し、ステータスをポーリングして、レポートの準備が整ったら結果をダウンロードします。この変更により、v2 ではタイムアウトすることなく、はるかに大規模なデータリクエストを処理できます。 v1 は非推奨ですが、顧客は引き続き使用できます。現時点で削除予定日はありません。報告期間の範囲
v2 では各 Step 固有のCompletedUtc に基づいてフィルタリングされるため、範囲をどのように分割しても、各 Step は必ず 1 つの期間範囲にのみ属します。日次レポートを合計した値は、同じ複数日範囲を対象とする 1 つのレポートの合計値と一致します。これは v1 と比べて大きな改善です。v1 では、Step が含まれるかどうかは Step 自体の完了時刻ではなく、そのトランザクションが期間中にアクティブだったかどうかによって決まるため、範囲の分割方法が異なっても v1 の合計値が同じになる保証はありません。
v2 で留意すべき点は、Step が日付の境界をまたぐトランザクションでは、それらの Step はいずれか一方の日次レポートにまとめて表示されるのではなく、各日に対応する 2 つの異なる日次レポートに表示されることです。
日付フィルタリングは completedUtc に基づきます
v2 エンドポイントでは、startDate と endDate のいずれも、トランザクションレベルの開始時刻や終了時刻ではなく、各 Step 固有の CompletedUtc タイムスタンプに基づいてフィルタリングされます。
トランザクション内の各 Step (たとえば Input、Classification、Extraction、手動確認、Output) には、それぞれ固有の CompletedUtc 値があります。そのため、1 つのトランザクション内の Step が異なる日付にまたがることがあります。各 Step は自身の完了時刻のみに基づいて個別に評価され、含めるか除外するかが決定されます。
トランザクションの Step が再処理、修正、手動確認での再実行、または何らかの理由で再試行された場合、その CompletedUtc は新しい完了時刻に更新されます。v2 では、リクエストの endDate が未来で、対象期間がまだ開いている場合にのみ、これが結果に影響します。リクエストの endDate が過去になると、結果は確定します。再処理では Step に現在時刻が記録されますが、これは定義上、すでに終了した期間より後の時刻です。そのため、そのレポートに遡って含まれたり除外されたりすることはありません。
処理中の Step が結果に含まれる場合があります
エクスポートには、まだ完了していない Step が含まれることがあります。レポート生成時にトランザクション内に処理中の Step (たとえば、ステータスがProcessing または WaitingForManualReview) がある場合、トランザクションの別の部分が指定期間内に該当していれば、その Step も処理中のステータスで、CompletedUtc 値なしのまま結果に表示されることがあります。
つまり、1 つのエクスポートに、確定済みの Step (期間内の CompletedUtc を持つ) と保留中の Step (完了タイムスタンプがまったくない) が混在することがあります。返されたすべての Step が完了したイベントを表すと考えず、各行の Status 列を確認してください。
日次レポートで推奨される方法
一般的な用途として、前日のトランザクションをレポートすることが挙げられます。この場合は v2 を使用し、startDate と endDate を前日の UTC 00:00:00～23:59:59 の時間範囲に設定します。v2 は各 Step 固有の CompletedUtc に基づいてフィルタリングするため、その日に完了した Step だけが正確に返され、日ごとに明確で一貫性のある合計値を取得できます。
この用途に v1 を使用することは避けてください。v1 は、指定期間中にアクティブだったトランザクションのすべての Step を返すため、対象日の数週間前または後に完了した Step を含むトランザクションであっても、全体が返されます。その結果、本来は1日分であるべき数値に、関連のない Step が含まれてしまいます。
v2 を使用する際の留意点として、Step が深夜をまたぐトランザクションでは、すべての Step がどちらか一方の日次レポートに含まれるのではなく、各日のレポートに分割されます。これは想定どおりの動作です。上記の「報告期間の範囲」を参照してください。
endDate がすでに完全に過去の日付であれば、レポートは安定しており、再現可能です。同じリクエストを後で再実行しても、同じ結果が返されます。一方、まだ進行中の当日を含む範囲をリクエストした場合は、さらに多くの Step が完了するにつれて、実行ごとに結果が変わる可能性があります (上記の「日付フィルタリングは CompletedUtc に基づく」を参照) 。
v1 から v2 への移行
新機能
リクエスト (/api/reporting/v2/exports/transaction-steps) では、次の変更があります。
- フィルタがクエリパラメーターからリクエストボディ (
filtersJSON オブジェクト) に移動しました。 filtersオブジェクト内で指定するstartDateが必須になりました。- 新しい field:
sendEmailNotification(true/false) - レポートのダウンロード準備が整ったときに、レポートをリクエストしたユーザーにメール通知を送信します。
/api/reporting/v2/exports/transaction-steps/{{requestId}}/result/{fileIndex}) としてダウンロードされる CSV ファイルには、新たに 2 つの列が追加されました。
DocumentsCount: トランザクション内で処理された Document の数。PagesCount: トランザクション内で処理されたページの数。
API の使用方法の違い
v1 では、クエリパラメーターを使用した 1 回の GET リクエストでレポートを直接取得します。v2 では、フィルタを POST リクエストのリクエストボディに移し、レポートのリクエスト、ステータスのポーリング、準備完了後の結果のダウンロードという 3 つの呼び出しに処理を分割します。 以下で v2 エンドポイントの動作の詳細を確認してください。データレポートのダウンロード
Warehouse からデータレポートをダウンロードできるのは、Tenant Administrator および Processing Supervisor のロールを持つユーザーのみです。詳細については、ロールベースアクセス制御 (RBAC) を参照してください。
filters オブジェクト内に次のプロパティを含める必要があります。
- skillId. ダウンロード対象とするトランザクションが属する Skill の ID。任意。
- transactionId. フィルタ対象とするトランザクションの ID。任意。
- startDate. トランザクションをダウンロードする期間の開始日 (形式の例: 2022-01-07T13:03:38、時刻は UTC) 。各 Step の
CompletedUtcタイムスタンプに対してフィルタリングします。必須。 - endDate. トランザクションをダウンロードする期間の終了日 (形式の例: 2022-09-07T13:03:38、時刻は UTC) 。各 Step の
CompletedUtcタイムスタンプに対してフィルタリングします。任意。 - sendEmailNotification. レポートリクエストを作成したユーザーに、レポートをダウンロードできる状態になったことを通知するメールを送信します。任意。
requestId が返されます。
結果：
requestId を指定します。
status が Succeeded、Failed、または Cancelled になるまで、このエンドポイントをポーリングします。status は次のいずれかの値になります。
Vantage は、テナントごとに一度に 1 件のエクスポートリクエストのみを処理します。複数のリクエストを送信すると、各リクエストは先行するリクエストが完了するまで
New のまま待機するため、Processing に移行するまでに時間がかかる場合があります。複数のレポートが必要な場合は、前のリクエストが完了してから次のリクエストを送信してください。
Vantage は、同じステータスに次の制限時間を超えて留まっているリクエストをキャンセルします。
status が Failed または Cancelled の場合は、しばらくしてから新しいリクエストを送信してください。ステータスのレスポンスには correlationId も含まれます。失敗またはキャンセルされたリクエストについて ABBYY サポートに問い合わせる際は、この値をお伝えください。
status が Succeeded になると、totalFileCount にダウンロード可能なファイル数が表示されます。
requestId を指定し、さらにファイルのインデックス (0 から始まる) である fileIndex を追加します。たとえば、"totalFileCount": 3 の場合、指定できるファイルインデックスは 0、1、2 です。
CSV レスポンスの例を以下に示します。
レスポンス構造
CSV ファイルの各行は、トランザクションに対して実行された 1 つの操作を表します。たとえば、documents のインポート、認識、または手動確認などです。Warehouse では各操作について、その詳細が次の列として保存されます。
Vantage は、リクエストの完了後 14 日間、結果ファイルを保持します。その後、ファイルとリクエストは削除されるため、そのリクエストはレポートリクエストの一覧に表示されなくなります。CSV 形式で取得したデータは、任意の BI ツールでさらに分析できます。
レポート要求の一覧を取得する
指定した期間内に作成されたレポート要求の一覧を取得するには、次のエンドポイントに対してGET リクエストを送信します。このとき、createdFrom と createdTo は日付範囲を表し、statusFilter には次のいずれかの値を指定します: New、Queued、Processing、Succeeded、Failed、Cancelled。これは、リクエスト ID をどこかに紛失してしまった場合などに役立ちます。
レスポンスにはレポート要求の配列が含まれます。