データエクスポートAPIのレスポンス制限への対応
データエクスポートAPIでは、レスポンスにページネーションは行われません。リクエストの結果として返されるデータ量が、APIが1回のレスポンスで許可する上限を超える場合、部分的な結果が返されるのではなく、エラーが発生してリクエストは失敗します。制限内に収まるよう、日付範囲を絞り込んだり、1回のリクエストあたりのプリンター数を減らしたり、あるいはその両方を組み合わせたりして、連携の設定を計画してください。
その限界とは何か
日付範囲を含むリクエストには、2種類の制限が適用されます：
- 最大の日付範囲
startDateTimeとendDateTimeの間の期間が 7 日を超える場合、API はエラーコードERR_DATE_RANGE_EXCEEDEDを伴う 400 レスポンスを返します。指定した時間枠を短縮して、再度リクエストを送信してください。- 応答の最大サイズ
- レスポンスファイルの最大サポートサイズは6MBで、これは約10,000件のジョブのデータを格納するのに十分な容量です。リクエストに一致したデータが最大レスポンスサイズを超える場合、APIはエラーコード
ERR_RESPONSE_LIMIT_EXCEEDEDを含む413レスポンスを返します。レスポンス本文には、適用されている制限を示すmaxJobs値が含まれています。問題を解決するには、日付の範囲を狭めるか、プリンターの数を減らすか、あるいはその両方を行い、リクエストを再度送信してください。
制限の範囲内に収まるよう計画を立てるようお願いします
応答制限を確実に守れるような統合を設計するには、以下の要素を考慮してください：
- プリンター1台あたりのジョブ数。高スループットの連続給紙プリンターは、少量のカットシートプリンターに比べて、1時間あたりのジョブの処理能力がはるかに高くなります。両方を導入して混在させる場合、印刷量が多いプリンターによって、作業の時間枠をどれだけ短く設定しなければならないかが決まります。
- リクエストあたりのプリンター数。各リクエストには、複数の
printerId値を含めることができます。複数のプリンターを1つのリクエストにまとめるのは便利ですが、プリンターが1台増えるごとに、レスポンスのサイズが大きくなり、制限を超える可能性も高まります。 - 時間帯。シフト制で業務を行っている場合、ジョブや状態の変化は特定の時間帯に集中します。24時間の期間については、その開始時刻と終了時刻によって、集計されるデータ量が大きく異なる場合があります。
- 再試行の許容回数。リクエストが
ERR_RESPONSE_LIMIT_EXCEEDEDのエラーで失敗した場合は、統合システムでリクエストを分割し、再試行する必要があります。最初から小さなウィンドウを想定して設計する方が、動的な分割を実装するよりも、通常は複雑さが少なくなります。
おすすめのパターン
一般的な統合シナリオでは、以下のパターンが効果的です：
- レポート作成用の夜間抽出データ
- 1日1回、スケジュールされたジョブを実行し、過去24時間のデータをプリンター1台ずつ順に取得するようにしてください。このパターンは実装が簡単で、失敗時の再試行も容易であり、各レスポンスのサイズを小さく抑えることができます。下流のプロセスにおいて、プリンターごとの応答を統合してください。
- ほぼリアルタイムのダッシュボード向け時間単位のデータ抽出
- 1時間ごとに1回、スケジュールされたジョブを実行し、1回の呼び出しで全プリンターの直前の1時間分のデータを取得するようにします。1時間ごとの処理枠を設けることで、印刷量が多いプリンターであっても、レスポンスのサイズを小さく抑えることができます。導入台数が多ければ、プリンターは一度にまとめてではなく、グループごとに申請してください。
- 過去データの遡及入力
- データウェアハウスに履歴データを格納するには、一定サイズのウィンドウ（たとえば、1回のリクエストにつき6時間）単位で時間範囲を順に処理し、プリンターも少人数のグループごとに処理してください。ウィンドウを1つずつ処理し、移動先となる次のウィンドウに進む前に結果を保存してください。ウィンドウで
ERR_RESPONSE_LIMIT_EXCEEDEDが発生した場合は、そのウィンドウを2つに分割し、それぞれの半分について再試行してください。 - 監視用の現在のプリンターの状態
- 履歴を取得せずに、管理対象のすべてのプリンターの現在の状態を確認するには、
/printer-statesにcurrentState=trueを指定して呼び出してください。この応答にはエンジンごとに1行が含まれており、日付範囲の影響を受けないため、1回のリクエストで全機体を網羅することができます。
統合におけるレスポンス制限エラーの処理
ERR_RESPONSE_LIMIT_EXCEEDED を含む 413 レスポンスを受け取った場合は、リクエストを再試行する前に、以下の対処法のいずれか、または複数を行ってください：
- 時間枠を短縮してください。ウィンドウを半分に分割するのは確実な戦略です。分割したリクエストがそれでも失敗する場合は、さらに分割してください。
- リクエスト内の
printerIdの値を減らしてください。ある1台のプリンターが印刷量の大部分を占めている場合は、そのプリンターを別途ご依頼ください。 - 履歴ではなく現在のスナップショットを取得したい場合は、
/printer-statesに対してcurrentState=trueを指定することで、日付範囲に基づく処理を完全に回避できます。
パラメータを変更せずに、同じリクエストを再送信しないでください。このAPIは部分的な結果を返さないため、変更を加えずに再試行しても、再び失敗してしまいます。