データエクスポートAPIのレスポンスフィールド

各データエクスポートAPIエンドポイントは、オブジェクトのJSON配列を返します。このトピックにあるテーブルを用いて、各回答に含まれる項目を解釈してください。

参照情報で使用されている表記規則

  • すべての所要時間はミリ秒単位で表示されます。
  • すべての日付および時刻の値は、timezoneリクエストパラメータで指定されたタイムゾーンに基づき、YYYY-MM-DDTHH:MM:SS.sss の形式で表示されます。
  • 識別子フィールド（printerId、jobId）はリクエスト間で安定しており、統合アプリケーションによってキャッシュすることができます。printerIdは決して変更されないため、その値を保存し、セッションをまたいで再利用することができます。

GET /printersのレスポンスフィールド

/printersエンドポイントは、アカウント内で識別され、データコレクターによって追跡されているプリンターごとに 1 つのオブジェクトを返します。

フィールド タイプ 概要
printerName ストリング RICOH Predictive Insight でプリンターに割り当てられた表示名です。
printerId ストリング（UUID） そのプリンタ固有の識別子です。/jobs、/printer-states、または/printer-interventionsを呼び出す際は、この値をprinterIdパラメータとしてご使用ください。
engines integer プリンターに搭載されているプリントエンジンの数です。連続給紙プリンターには、1つまたは複数のエンジンが搭載されている場合がありますが、カットシートプリンターでは通常、エンジンが1つと報告されています。各エンジンは、/printer-statesおよび/printer-interventionsのレスポンスにおいて、それぞれ個別の行として報告されます。
manufacturer ストリング プリンターのメーカー、例えばRicohやInfoPrintなどです。
model ストリング デバイスから報告されるプリンターのモデル名（例：RICOH Pro VC80000）。
printerMode ストリング プリンタがsimplexで動作しているか、simplexモードで動作しているか。このフィールドは、カットシート対応のプリンタなど、この値が適用されないプリンタの種類については、存在しない場合があります。
printerType ストリング そのプリンターがcontinuous_feedまたはcut_sheet用紙に対応しているかどうか。
serialNumber ストリング プリンタから報告されたシリアル番号です。マルチエンジンプリンターの場合、このフィールドには、各エンジンのシリアル番号を1つのストリングにまとめて記載することができます。例えば、Printer 1: 10-11111やPrinter 2: 10-11112といった形です。
connectionStatus ストリング RICOH Predictive Insightが現在、そのプリンタに接続できるかどうかを示します。取り得る値はconnectedとnot_connectedです。

GET /jobsのレスポンスフィールド

/jobsエンドポイントは、指定された期間内に指定されたプリンターによって処理されたジョブごとに、1つのオブジェクトを返します。

フィールド タイプ 概要
printerId ストリング（UUID） そのジョブを処理したプリンタの識別子です。/printersのレスポンスに含まれるprinterIdと一致しました。
jobId ストリング そのジョブの固有識別子です。
jobName ストリング プリンタに送信されるジョブの名前。通常はソースファイル名です。
jobPrintingSide ストリング このジョブで印刷される面、例えばsimplexまたはduplexなどです。
jobAction ストリング リクエストが処理された時点でのジョブの状況です。取り得る値：
  • printing：リクエストが発行された時点で、そのジョブは印刷中でした。
  • printed：ジョブが正常に完了しました。
  • aborted：ジョブは印刷が完了する前に終了しました。
  • completed：ジョブが最終状態に達しました。この値は、printedジョブとprintedジョブの両方を含む、それらの集合の超集合となります。結果にかかわらず、アクティブでなくなったすべてのジョブを取得したい場合に、これをご利用ください。
jobStartTime ストリング（日時） ジョブの印刷が開始された時点のローカル日時（リクエストで指定されたタイムゾーンに基づくもの）。
jobEndTime ストリング（日時） ジョブが終了した時点の現地日時（リクエストで指定されたタイムゾーンに基づく）。
jobDuration integer そのジョブの印刷に要した時間（ミリ秒単位）。
printedCopies integer そのジョブで出力された部数です。
printedPages integer そのジョブで印刷された論理ページの総数（すべての部数を含みます）。
printedImpressions integer 印刷された総部数です。1印とは1枚の用紙の片面を指します。したがって、両面印刷では1枚の用紙につき2印が印刷されます。
printedSheets integer そのジョブで使用された物理シートの総数です。
printedRollFeet number 連続給紙プリンターの場合、そのジョブで消費されたメディアの長さ（フィート単位）です。
printedRollMeters number 連続給紙式プリンターの場合、そのジョブで消費されるメディアの長さ（メートル単位）です。
inkC, inkM, inkY, inkK number そのジョブで消費されたシアン、マゼンタ、イエロー、およびブラックのインク量で、各カラーチャンネルごとに立方センチメートル（cc）単位で報告されます。
flushingC, flushingM, flushingY, flushingK number そのジョブに関連するプリントヘッドのフラッシング操作中に消費されたシアン、マゼンタ、イエロー、およびブラックのインク量で、色チャンネルごとに立方センチメートル（cc）単位で報告されます。フラッシングの消費量は、inkC/M/Y/Kとは別に追跡されるため、生産用途でのインク使用量とメンテナンス用途での使用量を区別することができます。

GET /printer-statesのレスポンスフィールド

/printer-statesエンドポイントは、プリンターエンジンごと、状態間隔ごとに 1 つのオブジェクトを返します。どのフィールドが存在するかは、リクエストモードによって異なります：

  • 集計履歴（デフォルト）：すべてのフィールドが返されます。
  • 現在の状態のみ（currentState=true）：printerStateDuration、historyStartTime、およびhistoryEndTimeは省略されます。
  • 状態カテゴリのみ（stateCategoryOnly=true）：printerState は省略されます。
フィールド タイプ 概要
printerId ストリング（UUID） この行で記述されているプリンタの識別子です。/printersのレスポンスに含まれるprinterIdと一致しました。
engine ストリング この行で記述されているプリンタ内のエンジン、例えばengine_1、engine_2、またはengine_3 などです。複数のエンジンを搭載したプリンターは、各状態間隔ごとに、エンジンごとに1行ずつ出力します。
stateCategory ストリング エンジン状態が属する上位のカテゴリです。取り得る値は、up、down、idle、unknownです。このフィールドは、プリンターモデル間で一貫したカテゴリが必要なダッシュボードやレポート作成にご利用ください。
printerState ストリング プリンターエンジンから報告される生の状態（印刷中、準備中、メンテナンス中、スリープ中など）。生の状態の値は、プリンターの機種によって異なります。stateCategoryOnly=true の場合、これは省略されます。
注意: 各州とその対応関係の完全なリストについては、プリンターの状態と状態のカテゴリーをご覧ください。
printerStateDuration integer エンジンがこの状態にあった時間の長さ（ミリ秒単位）。currentState=trueの場合は省略されます。
historyStartTime ストリング（日時） エンジンがこの状態になった時点の現地日時（リクエストで指定されたタイムゾーンに基づく）。currentState=trueの場合は省略されます。
historyEndTime ストリング（日時） エンジンがこの状態を離れた際の現地日時（リクエストで指定されたタイムゾーンに基づく）。集計された応答における最新の区間については、この値は要求された時間範囲の終了時点と一致する場合があります。currentState=trueの場合は省略されます。

GET /printer-interventionsのレスポンスフィールド

/printer-interventionsエンドポイントは、指定された時間範囲内で、リクエストされた各プリンターの各エンジンについて、介入イベントごとに 1 つのオブジェクトを返します。

フィールド タイプ 概要
printerId ストリング（UUID） この行で記述されているプリンタの識別子です。/printersのレスポンスに含まれるprinterIdと一致しました。
interventionStartDate ストリング（日時） イベントが開始された現地の日時（リクエストで指定されたタイムゾーンに基づく）。
interventionEndDate ストリング（日時） イベントが解決された時点のローカル日時（リクエストで指定されたタイムゾーンに基づく）。
duration integer イベントの継続時間（ミリ秒単位）。
説明 ストリング 警告やエラーの原因となった条件の簡単な説明です。例えば、メディアがありませんや紙詰まりなどです。このフィールドは言語に依存します。languageパラメータで指定された言語で返されますが、そのパラメータが省略されている場合や、指定された言語で説明文が利用できない場合は、英語で返されます。
engine ストリング この行で記述されているプリンタ内のエンジン、例えばengine_1、engine_2、またはengine_3 などです。複数のエンジンを搭載したプリンターは、イベントごとにエンジン1台につき1行を出力します。
jobName ストリング イベントが発生した時点で印刷中だったジョブの名前です。そのイベントにジョブが関与していなかった場合、この値は空のストリングとなります。
interventionCode ストリング その条件を特定するためのコードです。descriptionとは異なり、この値は言語に依存しないため、言語をまたいでイベントをグループ化したり比較したりする必要がある場合に、この値をご利用ください。コードの形式はプリンターによって異なります。単葉印刷用プリンターではcoverOpenなどの説明的なストリングが報告され、連続給紙式プリンターではCA00や40000006などの値が報告されます。

In this section:

  1. プリンターの状態と状態のカテゴリー
    /printer-statesエンドポイントは、プリンタの生の状態と、高レベルの状態カテゴリの両方を報告します。このトピックのテーブルを参考にして、どの生の状態がどのカテゴリーに分類されるかをご確認ください。
  2. データエクスポートAPIのレスポンス制限への対応
    データエクスポートAPIでは、レスポンスにページネーションは行われません。リクエストの結果として返されるデータ量が、APIが1回のレスポンスで許可する上限を超える場合、部分的な結果が返されるのではなく、エラーが発生してリクエストは失敗します。制限内に収まるよう、日付範囲を絞り込んだり、1回のリクエストあたりのプリンター数を減らしたり、あるいはその両方を組み合わせたりして、連携の設定を計画してください。
上位層のトピック： データエクスポートAPIの活用