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

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

## 定義は 4 つの要素

| 要素       | 何か                                 |
| ---------- | ------------------------------------ |
| `objectId` | どのオブジェクトのレコードを数えるか |
| `groupBy`  | 行をグループ化するフィールドキー     |
| `measure`  | グループごとに計算するもの。下記参照 |
| `filters`  | 対象を絞る条件。最大 10 件           |
| `limit`    | 返す行数。1〜100、既定 50            |

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

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

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

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

## プレビューと保存

[`POST /reports/preview`](/ja/reference/reports/post-api-v1-reports-preview) は定義を実行し、何も保存せずに行を返します。利用者が定義を組み立てている間に結果を表示するのはこれです。

[`POST /reports`](/ja/reference/reports/post-api-v1-reports) は定義を保存します。[`GET /reports/{id}/results`](/ja/reference/reports/get-api-v1-reports-by-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`](/ja/reference/reports/get-api-v1-dashboards-by-id-widgets) は**呼び出し元が読めるリポートのウィジェットだけ**を返します。つまりダッシュボードはリポートの権限を回避する手段ではありません。2 人が同じダッシュボードを開いて違う数のウィジェットを見ることがあり、それは回避すべきエラーではなく意図された挙動です。

## ここにないもの

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