Data Export API における日付と時刻の処理

日付と時刻のモデル

API が日付と時刻をどのように扱うかについては、以下の 3 つのルールが定められています：

1. /jobs、/printer-states、および/printer-interventionsへのすべてのリクエストには、有効な IANA タイムゾーン識別子（例：America/DenverやEurope/Bucharest）を含むtimezoneパラメータを必ず含める必要があります。
2. リクエストで指定されたstartDateTimeまたはendDateTimeの値は、指定されたタイムゾーンにおける現地時間として解釈されます。これらの値にはUTCオフセットは含まれていません。
3. レスポンス内のすべての日付および時刻の値は、YYYY-MM-DDTHH:MM:SS.sss という形式を用いて、同じタイムゾーンの現地時間として表示されます。

timezoneパラメータは、リクエストの意味とレスポンスの書式を決定します。同じ基となるデータに対する2つのリクエストが、異なるタイムゾーンで送信された場合、同じイベントを表しているにもかかわらず、応答に含まれるタイムスタンプストリングが異なってしまいます。

日付と時刻の形式

このAPIでは、リクエストとレスポンスの双方において、すべての日付および時刻の値に同一の形式を使用しています：

YYYY-MM-DDTHH:MM:SS.sss

たとえば、2026-03-15T14:30:00.000 は、2026年3月15日の午後2時30分00秒であり、リクエストで指定されたタイムゾーンに基づいて解釈されます。

リクエストにおいて、ミリ秒単位の部分（.sss）は省略可能です。反応においては、常にそれが存在しています。

デフォルトの時間範囲

startDateTime、endDateTime、あるいはその両方を省略することができます。これら2つのデフォルト設定は、それぞれ独立して適用されます：

• startDateTime を省略した場合、API は現在の時刻から 24 時間前の時刻を範囲の開始時刻として使用します。
• endDateTime を指定しない場合、API は現在の時刻を範囲の終了時刻として使用します。

デフォルト設定は、予想通りの組み合わせになります：

• 両方の値を省略した場合、APIは過去24時間分のデータを返します。
• startDateTimeに1時間前を指定し、endDateTime を省略した場合、API は過去1時間分のデータを返します。
• endDateTime を指定し、startDateTime を省略した場合、API はリクエストの 24 時間前からendDateTime までの範囲のデータを返します。

デフォルト値は、リクエストで指定されたタイムゾーンに基づいて計算されます。

データの保存期間：過去7日間

データエクスポートAPIは、リアルタイムの運用データを提供します。ジョブ記録、プリンタの状態履歴、および介入イベントは、過去7日間分のみ確認可能です。7日以上経過したデータの取得をリクエストすると、エラーが発生します。

データが有効期限切れになる前にすべてのデータを取得できるよう、スケジュールされたデータ抽出が十分に頻繁に実行されるように、統合計画を策定してください：

• 毎晩の抽出については、少なくとも1～2日分の余裕を見ておいてください。スケジュールされた実行が失敗した場合、データが利用できなくなる前に、原因を調査して再実行する時間的余裕があります。
• バックフィルや1回限りのデータ抽出については、7日以上前のデータはリクエストしないでください。

指定された範囲に関するルール

• startDateTime はendDateTime より前である必要があります。このルールに違反するリクエストは、ERR_INVALID_DATE_RANGE エラーで失敗します。
• どちらの値も、日付と時刻の形式 に記載されている形式に従う必要があります。値の形式が不正なリクエストは、ERR_INVALID_DATE_FORMAT エラーで失敗します。
• startDateTimeとendDateTimeの間の期間は、許可されている最大範囲を超えてはなりません。最大値を超えるリクエストは、ERR_DATE_RANGE_EXCEEDED エラーで失敗します。

タイムゾーンの設定

timezoneパラメータには、America/Denver、America/New_York、Europe/Bucharest、Asia/Tokyo、UTC などの IANA タイムゾーン識別子を指定できます。インタラクティブなドキュメントページには、APIが受け付けるすべての値のリストが記載されています。

無効な識別子または認識されない識別子を使用すると、ERR_INVALID_TIMEZONE エラーが発生します。MSTやESTといった 3 文字の略語は IANA 識別子ではなく、使用は認められません。代わりに、対応する地域ベースの識別子（例：America/DenverやAmerica/New_York）を使用してください。

言語の提供

APIがレスポンスの形式をどのように設定するかを制御するパラメータは、timezoneパラメータだけではありません。/printer-interventionsエンドポイントでは、オプションのlanguageパラメータも指定可能です。このパラメータにより、レスポンス内のdescriptionフィールドの言語が決まります。

有効な値は、en（英語）、de（ドイツ語）、ja（日本語）、it（イタリア語）、fr（フランス語）、およびes（スペイン語）です。このリストに含まれていない値を指定すると、ERR_INVALID_LANGUAGE エラーが発生します。

このパラメータに関しては、以下の2つの点について事前に計画を立てておく価値があります：

• パラメータを省略した場合、またはご指定の言語で説明文が利用できない場合は、説明文は英語で返されます。どちらの場合でもリクエストは成功するため、統合システムでは、説明文の言語がリクエストされた言語と一致すると仮定することはできません。
• このパラメータは、descriptionフィールドにのみ影響します。これに付随するinterventionCodeフィールドは言語に依存しないため、リクエストされた言語に関係なく、イベントを一貫してグループ化、比較、または保存する必要がある場合は、このフィールドをご利用ください。

夏時間と曖昧な時刻

リクエストとレスポンスは現地時間で式として表されるため、夏時間の切り替えに伴い、注意すべき2つの状況が生じます：

春の時刻変更に伴い、現地時間が省略されました

時計の針を1時間進めると、現地時間の1時間が存在しなくなります。たとえば、America/Denverでは、春時間の切り替え当日、02:30:00は有効な現地時刻ではありません。スキップされた時間の範囲内の時刻を、startDateTimeやendDateTime として使用しないでください。

秋の移り変わりにおける繰り返される現地時間

時計の針を戻すと、現地時間の1時間が2回訪れます。秋への時刻変更当日の01:30:00といった値は、曖昧です。どのインスタンスをリクエストしているのかが不明確になるのを避けるため、繰り返し発生する時刻以外の時間帯をお選びください。

統合が無人実行され、開始時刻または終了時刻が遷移期間内に含まれるリクエストを送信する可能性がある場合は、そのリクエストの実行を、遷移期間から数時間ずらしてスケジュールするか、明らかにその期間外となる時刻を設定してください。

応答タイムスタンプの保存および比較に関する推奨事項

応答のタイムスタンプは、オフセットを含まない現地時間です。下流のシステムにおける曖昧さを避けるため、以下のいずれかのアプローチをご検討ください：

• レスポンスのタイムスタンプを、リクエストで指定したタイムゾーンとともに保存してください。この2つを合わせて見ると、ある唯一無二の瞬間が浮かび上がります。
• 統合処理において、各レスポンスのタイムスタンプを保存する前に、リクエストで指定されたタイムゾーンを使用してUTCに変換してください。UTC値を保存することで、異なるタイムゾーンで抽出されたデータ間の比較が簡単になります。
• 保存されたすべてのタイムスタンプを直接比較できるように、リクエストは常に同じタイムゾーン（例：UTC）で送信してください。

例

以下の例では、タイムゾーン、開始時刻、終了時刻がどのように連携して機能するかを説明しています。

マウンテンタイムのデフォルトウィンドウ

2026年3月15日午前9時に、 America/Denverタイムゾーンで送信され、開始時刻および終了時刻が指定されていない場合、2026-03-14T09:00:00から2026-03-15T09:00:00 までのデータが返されます。これらはいずれもマウンテンタイムで解釈されます。

東ヨーロッパ時間の特定の時間帯

timezone=Europe/Bucharest、startDateTime=2026-03-15T08:00:00、endDateTime=2026-03-15T16:00:00を指定したリクエストは、ブカレスト現地時間での8時間の営業日に関するデータを返します。レスポンスのタイムスタンプも、ブカレストの現地時間で表示されます。

2つのタイムゾーンから見た同じ窓

同じ基となるデータを、2つの対象者向けにフォーマットして2回取得するには、異なるtimezoneの値を指定した2つのリクエストを送信し、各タイムゾーンにおいて同じ時点を表すようにstartDateTimeとendDateTimeを調整してください。レスポンスのペイロードは、同じイベントを表していますが、異なるタイムスタンプストリングが使用されています。