Skip to main content

​
概要

システム内のすべてのデータは UTC で保存されていますが、処理は EST(米国東部標準時)のスケジュールで実行されます。ユースケースに応じて正しいデータをクエリするには、日付範囲の仕組みを理解することが重要です。
タイムゾーンの誤った扱いは、API レスポンスでデータが欠落したり、予期しないデータが含まれたりする最も一般的な原因です。このガイドをよくお読みください。

​
システムの動作

​
データ処理のスケジュール

システムは EST タイムゾーンに従ってデータを処理します。
  • EST の 1 月 1 日の「1 日」は 00:00 EST(05:00 UTC)に始まります
  • EST の 1 月 1 日の「1 日」は 23:59 EST(翌日の 04:59 UTC)に終わります
すべてのデータは、UTC タイムスタンプでデータベースに保存されます。

​
サポートされる日付形式

API は複数の形式の日付を受け付けます。
  1. 日付のみ(日単位のクエリに推奨): 2025-01-01
  2. タイムゾーンなしの日付と時刻: 2025-01-01T00:00:00
  3. UTC タイムゾーン付きの日付と時刻: 2025-01-01T05:00:00Z

​
日付の解釈方法

​
タイムゾーンを指定しない場合

タイムゾーンなし(Z サフィックスなし)で日付を指定すると、API はそれを EST として解釈します。
処理内容:
  • 2025-01-01 → 2025-01-01T00:00:00 EST として解釈 → 2025-01-01T05:00:00Z UTC に変換
  • 2025-01-31 → 2025-01-31T00:00:00 EST として解釈 → 2025-01-31T05:00:00Z UTC に変換
これはシステムにおける「日」の定義と一致しており、ほとんどのユースケースで推奨される方法です。

​
UTC タイムゾーン(Z サフィックス)を指定する場合

Z サフィックス付きで日付を指定すると、API はそれを文字どおりの UTC として解釈します。
処理内容:
  • 2025-01-01T00:00:00Z → UTC のままそのまま使用
  • 2025-02-01T00:00:00Z → UTC のままそのまま使用
UTC タイムスタンプ(Z 付き)を使用する場合は、EST から UTC への変換を手動で行う必要があります。この方法は後方互換性のために残されていますが、新しいインテグレーションには推奨されません。

​
例

​
正しい例: 2025 年 1 月のデータをクエリする(EST の日)

これにより、次の範囲のすべてのデータが返されます。
  • 開始: 1 月 1 日 00:00 EST(1 月 1 日 05:00 UTC)
  • 終了: 2 月 1 日 00:00 EST(2 月 1 日 05:00 UTC)
範囲は終端を含みます(<=)が、通常データのタイムスタンプがちょうど 00:00 になることはないため、実質的に 1 月全体を取得できます。

​
誤った例: UTC の午前 0 時で 2025 年 1 月をクエリする

これにより、次の範囲のデータが返されます。
  • 開始: 12 月 31 日 19:00 EST(1 月 1 日 00:00 UTC)
  • 終了: 1 月 31 日 19:00 EST(2 月 1 日 00:00 UTC)
問題点: 開始時に 5 時間分が欠落し、終了時に不要な 5 時間分が含まれてしまいます。

​
正しい例: UTC で 2025 年 1 月をクエリする(手動変換)

UTC タイムスタンプを使用する必要がある場合は、EST のオフセットを考慮する必要があります。
これで 1 月全体(EST の日)を正しく取得できますが、タイムゾーンの計算を手動で行う必要があります。

​
時間範囲

​
日付のみの形式では午前 0 時がデフォルト

日付のみの形式を使用する場合、時刻はデフォルトで 00:00:00 になります。

​
正確な時刻を指定する

より細かいクエリを行うために、正確な時刻を指定できます。
これにより、1 月 1 日の午前 8 時から午後 5 時(EST)までのデータをクエリします。

​
日付範囲の動作

日付範囲は両端を含みます (start <= x <= end)。
これには次が含まれます。
  • 1 月 1 日全体(00:00 EST 以降)
  • 1 月 2 日のちょうど 00:00 EST
  • データには 1 日を通してタイムスタンプが付与されるため、通常ちょうど 00:00 のデータは存在せず、実際には 1 月 1 日全体を取得することになります
1 日分をクエリするには、end_date を翌日の 00:00 に設定します。

​
ベストプラクティス

推奨: 日単位のクエリには、タイムゾーンなしの日付のみの形式を使用する
推奨: 日中のクエリには、タイムゾーンなしの日時を使用する
推奨: 時間単位のレポートクエリ(Agent Analytics の V2 (hourly) タブを参照)には、タイムゾーンなしの日時を使用する
端数オフセットのタイムゾーンのユーザー: /v2/reports/* で時間単位の粒度でクエリする場合、ローカルの 1 時間分の完全なデータを取得するには、連続する 2 時間分をクエリしてください。詳細は 端数オフセットのタイムゾーン を参照してください。
避けるべき方法: UTC オフセットの影響を理解していない限り、Z サフィックスは使用しないでください

​
夏時間

EST は夏時間(DST)を採用しています。
  • 標準時(EST): UTC-5(通常 11 月〜3 月)
  • 夏時間(EDT): UTC-4(通常 3 月〜11 月)
API は DST の切り替えを自動的に処理します。タイムゾーンなしで日付を指定すると、UTC への変換時に、その日付で DST が有効だったかどうかが考慮されます。 DST 期間中の例:
→ 2025-07-01T04:00:00Z UTC に変換されます(DST のため 05:00 ではありません)

​
端数オフセットのタイムゾーン

一部のタイムゾーンでは、1 時間単位ではなく端数の UTC オフセットが使用されています。 時間単位のバケットは UTC の 1 時間単位の境界に揃えられているため、これらのタイムゾーンにおけるローカルの 1 時間は、常に 2 つの時間バケットにまたがります。任意のローカルの 1 時間分の完全なデータを取得するには、連続する 2 時間分をクエリする必要があります。

​
例: IST の午後 2 時をクエリする

IST は UTC+5:30 のため、IST の午後 2 時 = 08:30 UTC です。IST の午後 2 時から午後 3 時まで(08:30〜09:30 UTC)の 1 時間は、2 つの UTC 時間バケットにまたがります。
  • 08:00〜08:59 UTC(最初の 30 分: IST の午後 2 時〜午後 2 時 30 分を含む)
  • 09:00〜09:59 UTC(最後の 30 分: IST の午後 2 時 30 分〜午後 3 時を含む)
1 時間分すべてを取得するには、両方のバケットをクエリします。
これは、/v2/reports/* で時間単位の粒度でクエリする場合に該当します。端数オフセットのタイムゾーンにいて時間単位でデータをリクエストする場合は、隣接するバケットに含まれるデータの欠落を防ぐため、必ず連続する 2 時間分をリクエストしてください。

​
トラブルシューティング

​
日の境界でデータが欠落する

問題: 1 月 1 日をクエリしているのに、最初または最後の数時間分が欠落している。 解決策: Z サフィックスを使用していないことを確認してください。"start_date": "2025-01-01T00:00:00Z" ではなく "start_date": "2025-01-01" を使用します。

​
前日/翌日のデータが含まれる

問題: 日単位のクエリに、隣接する日のデータが含まれている。 解決策: UTC の午前 0 時に Z サフィックスを付けて使用している可能性があります。これは EST の日と一致しません。タイムゾーンサフィックスを削除してください。

​
予期しない DST の動作

問題: DST の切り替え時に、クエリに 1 時間のずれが生じる。 解決策: タイムゾーンなしの日付を使用し、API に DST を自動的に処理させてください。UTC を使用する必要がある場合は、EST(-5)と EDT(-4)でオフセットが変わることに注意してください。

​
今後の変更

今後の API バージョンでは、複数のタイムゾーンでのクエリを可能にするため、完全な ISO 8601 タイムゾーンオフセット(例: -05:00、+09:00)のサポートを予定しています。その時点で、タイムゾーン指定のない日付は非推奨となります。
現時点では、タイムゾーンなしの日付を使用し、EST への変換を API に任せる方法を推奨します。