レポートの使用

Reports API の目的 は、プロジェクトのすべての装置によって生成されたすべての関連イベントデータを収集して分析することです。 このガイドでは、適切なイベント履歴が存在することを前提としています。

前提条件

レポートを生成できるようにするには、ユーザーが少なくとも次のものを準備しておく必要があります。

• トラッキング デバイス
• 次のいずれかのルールが作成され、デバイスに関連付けられています。
  • 滞留ルール
  • 使用率ルール
  • 留置ルール
• 滞留ルールの場合、 少なくとも 1 つのジオフェンス をデバイスに関連付ける必要があります
• ルールに関連するイベント履歴

レポートの作成を開始

ルールと時間範囲を定義して、レポートの作成を開始。 この例では、単純化のために、このルールが滞留ルールであると仮定します。 特に記述がない限り、同じロジックが他のルールタイプにも適用されます。

一部のレポートでは、メトリックは 1 つのインターバル（日、週、または月）でグループ化されています。 開始パラメータでは、曜日とその日の最初の時間を追加で定義します。

注 : start および end パラメータの形式は、 UTC タイムゾーンの日時文字列です。

たとえば、ユーザーが 2021 年の 1 週目から 2021 年 2 月の深夜までのレポートを取得し、 UTC+01 のタイムゾーンにいる場合、 start および end のパラメータは次のように定義されます。

curl -X POST \
  https://tracking.api.here.com/reports/v4 \
  -H 'authorization: Bearer {userToken}' \
  -H 'content-type: application/json' \
  -d '{
  "start": "2021-01-03T23:00:00.000Z",
  "end": "2021-02-27T23:00:00.000Z",
  "ruleId": {ruleId}
}'

レポートが正常に作成されると、reportId が返されます。 reportId 指定した時間範囲内および指定したルールについて、さまざまなレポートクエリーにも同じものを使用できます。 レポートは 1 週間使用できますが、その後で再作成する必要があります。

複数のプロジェクトのメンバーの場合 projectId は、クエリ パラメーター でプロジェクト ID を指定してください。

レポート作成のステータスを確認

レポートは非同期で作成されます。 レポートの作成ステータスを取得するには reportId 、追加のパラメータを指定せずに、次のリクエストを作成します。

curl -X GET \
  https://tracking.api.here.com/reports/v4/{reportId} \
  -H 'authorization: Bearer {userToken}' \
  -H 'content-type: application/json'

レポート作成のステータスが返されます。 ステータスが pending またはの場合 startedは、後でもう一度確認してください。 ステータスがの場合にのみ 、実際のレポートcompletedを取得できます。

デバイスの簡単なインターバルレポートを取得

interval、 trackingId およびmeasureクエリーの各パラメータを指定して、 get リクエストを作成します。 後者は、計算対象のメトリックです。 以下の例では、指定したデバイスが毎週どのくらいの期間滞留状態にあったかについてのレポートを取得します。

curl -X GET \
  https://tracking.api.here.com/reports/v4/{reportId}?measure=duration&interval=week&trackingId={trackingId} \
  -H 'authorization: Bearer {userToken}' \
  -H 'content-type: application/json'

レスポンス本文には、ペアの配列 timestamp- valueが含まれます。timestampは各インターバルの開始を定義 し、value はこのインターバルで計算されたメトリックです。 valueの単位 は、メトリックによって異なります。 メトリックがdurationの場合、値は秒単位になります。

すべてのデバイスについて、統合されたインターバルレポートを取得

interval、 measure、 groupBy およびmethodのクエリーパラメータを指定して、 get リクエストを作成します。 以下の例では、 1 週間のデバイスの平均使用時間に関するレポートを取得します。

curl -X GET \
  https://tracking.api.here.com/reports/v4/{reportId}?measure=duration&interval=week&groupBy=asset&method=average \
  -H 'authorization: Bearer {userToken}' \
  -H 'content-type: application/json'

すべてのジオフェンスの総合的なインターバルレポートを取得

interval、 measure、 groupBy およびmethodのクエリーパラメータを指定して、 get リクエストを作成します。 次の例では、ジオフェンスでデバイスが平均的に滞留している時間について、週ごとにレポートを取得します。

curl -X GET \
  https://tracking.api.here.com/reports/v4/{reportId}?measure=duration&interval=week&groupBy=geofence&method=cumulative \
  -H 'authorization: Bearer {userToken}' \
  -H 'content-type: application/json'

注 : ジオフェンス固有のレポートを取得できるのは 、滞留ルールを使用して作成されたreportIdに限られます。

デバイスのトップリストを取得

measure および groupBy クエリーのパラメータを指定して、 get 要求を作成します。 次の例では、レポート期間全体のデバイスの一覧表と、それぞれの累積滞留時間のレポートを取得します。

curl -X GET \
  https://tracking.api.here.com/reports/v4/{reportId}?measure=duration&groupBy=asset \
  -H 'authorization: Bearer {userToken}' \
  -H 'content-type: application/json'

レスポンス本文には trackingId、値のペアの配列が含まれ、降順で並べ替えられます。 並べ替えを変更する場合 sort=value:ascは、追加のクエリ パラメーターを定義できます。