リポートとダッシュボード

定義がレコードを集計し、プレビューは保存せず実行し、ダッシュボードは保存済みリポートを 12 カラムのグリッド上のウィジェットとして配置します。

ここのすべてのエンドポイントは reports モジュールを必要とします。定義は 4 つの要素で、ダッシュボードは保存済みリポートの上に載るレイアウトです。

定義は 4 つの要素

measure は 2 つの形のいずれかです。

• { "operation": "count" } — フィールドは不要です。行を数えるのにフィールドは要りません。
• { "operation": "sum" | "average" | "min" | "max", "field": "…" } — フィールドキーを取り、そのフィールドは数値でなければなりません。それ以外は measure_not_numeric で拒否されます。

リポートのフィルターは等価比較で、ビューのフィルターではありません。 各条件は { field, value } で、値は文字列か真偽値です。レコードビューが提供する 33 個の演算子はここでは使えません。フィールドに合わない値は filter_value_invalid で拒否されます。

2 つのフィールド種類はまったく使えません。 multi_select と address をグループ・測定・フィルターに指定すると report_field_unavailable が返ります。並び替えできないのと同じ理由で、扱える単一の値がないからです。

プレビューと保存

POST /reports/preview は定義を実行し、何も保存せずに行を返します。利用者が定義を組み立てている間に結果を表示するのはこれです。

POST /reports は定義を保存します。GET /reports/{id}/results は保存済みの定義を現時点の状態で実行します。保存済みリポートは保存された答えではなく保存された問いなので、レコードが変われば数値も変わります。

保存には reports.manage が必要で、プレビューと実行には reports.read だけで足ります。リポートを表示するが作成はさせないクライアントは読み取りスコープだけで済みます。

ダッシュボード

ダッシュボードは名前と最大 20 個のウィジェットです。各ウィジェットは保存済みリポートを指し、visualization を number・table・bar から選び、12 カラムのグリッド上に自分の layout を持ちます。x は 0〜11、width と height は 1〜12、y は 0〜100 です。

GET /dashboards/{id}/widgets は呼び出し元が読めるリポートのウィジェットだけを返します。つまりダッシュボードはリポートの権限を回避する手段ではありません。2 人が同じダッシュボードを開いて違う数のウィジェットを見ることがあり、それは回避すべきエラーではなく意図された挙動です。

ここにないもの

ドリルダウン、配信スケジュール、グラフの作成体験は Web アプリケーションのもので、別のトランスポートを使います。この API は定義とその行です。