Dashboard API

共通仕様

認証・エラー形式・レート制限・共通ヘッダーは API 概要・認証を参照してください。

カスタム Dashboard と可視化の管理を行う API です。

Dashboard

一覧取得

GET /api/user/<user_id>/dashboard/

クエリパラメータ:

パラメータ	必須	説明
`search`	任意	Dashboard 名の部分一致（大文字小文字を区別しない）で絞り込みます

結果は更新日時の降順で返ります。

レスポンス例:

[
  {
    "key": "org-uuid-Security-Overview",
    "name": "Security Overview",
    "managed": false,
    "created_at": "2025-01-01T00:00:00Z",
    "updated_at": "2025-01-15T10:30:00Z"
  }
]

managed が true の Dashboard は Integration により管理されており、編集できません。

Dashboard 作成

POST /api/user/<user_id>/dashboard/

リクエストボディ:

{
  "name": "Firewall Dashboard",
  "globalTimeRange": ["last15minutes"],
  "visualizations": [
    {
      "attributes": {
        "title": "Firewall Deny Events",
        "query": "from `firewall_logs` filter action == \"DENY\"",
        "chartType": "timeline",
        "timerange": ["last15minutes"],
        "showTitle": true
      },
      "layout": {
        "positions": { "x": 0, "y": 0 },
        "size": { "width": 4, "height": 2 }
      },
      "metadata": { "id": "viz-001", "type": "chart", "version": "1" }
    }
  ]
}

attributes には可視化の内容をオブジェクトで指定します。title と組織で既存の可視化を検索し、存在すれば更新、なければ新規作成されます。metadata.version は必須です。

フィールド	型	説明
`globalTimeRange`	array of string	Dashboard 全体に適用する共通の時間範囲（例: `["last15minutes"]`）。取得時のレスポンスにも含まれます

レスポンス例:

{ "status": "success", "key": "<org-uuid>-<name>" }

Dashboard 取得

GET /api/user/<user_id>/dashboard/<dashboard_id>/

Dashboard 更新

作成と同じ POST /api/user/<user_id>/dashboard/ に既存と同じ name を指定して送信すると、上書き保存されます。

名前の変更

PATCH /api/user/<user_id>/dashboard/<dashboard_id>/

ボディに {"name": "新しい名前"} を送信します。key は <組織UUID>-<名前> 形式のため、名前変更で key も変わります。同名の Dashboard が存在する場合は 400 が返ります。

Managed Dashboard

Integration によって配布された Dashboard は managed: true として返され、更新・名前変更を行うと 403 エラーになります。閲覧とデータ表示のみ可能です。

可視化 (Visualization)

一覧取得

GET /api/user/<user_id>/visualize/

レスポンス例:

[
  {
    "id": "665f0c...",
    "title": "Firewall Deny Events",
    "chartType": "timeline"
  }
]

一覧では id / title / chartType のみが返ります。query や timerange を含むすべての設定は単一取得 API で取得してください。

可視化作成

POST /api/user/<user_id>/visualize/

リクエストボディ:

{
  "title": "Top Blocked IPs",
  "query": "from `firewall_logs` filter action == \"DENY\" group {src_ip} (aggregate {cnt = count this}) sort {-cnt} take 10",
  "chartType": "bar",
  "timerange": ["last15minutes"],
  "xAxisField": "src_ip",
  "yAxisField": "count",
  "xAxisLabel": "Source IP",
  "yAxisLabel": "Block Count",
  "showTitle": true
}

フィールド説明:

フィールド	型	説明
`title`	string	可視化のタイトル
`query`	string	PRQL クエリ
`chartType`	string	チャートタイプ（line / bar / pie / datatable 等）
`timerange`	array of string	時間範囲（プリセット 1 要素、またはカスタム範囲の開始/終了 2 要素）
`xAxisField`	string	X 軸のフィールド名
`yAxisField`	string	Y 軸のフィールド名
`xAxisLabel`	string	X 軸のラベル
`yAxisLabel`	string	Y 軸のラベル
`showTitle`	boolean	タイトル表示の有無
`searchFilter`	array of string	追加のフィルタ条件の配列
`pdfOnly`	boolean	PDF 生成時のみ表示するかどうか（既定: false）
`isStretch`	boolean	表示の引き伸ばし（既定: false）
`caseViewId`	string	Case パネルが参照する Case View の ID
`chartConfig`	object	チャート固有設定（KPI の countField・prevField、Gauge の gaugeStyle、系列色 seriesColors など）

可視化取得

GET /api/user/<user_id>/visualize/<viz_id>/

可視化更新

作成と同じ POST /api/user/<user_id>/visualize/ に既存と同じ title を指定して送信すると、上書き更新されます（200 で {"message": "Updated"} が返ります）。

タイトルの変更

PATCH /api/user/<user_id>/visualize/<viz_id>/

ボディに {"title": "新しいタイトル"} を送信します。

可視化削除

DELETE /api/user/<user_id>/visualize/<viz_id>/

viz_id を指定しない場合は 400 エラーになります。成功時は次のレスポンスが返ります。

{
  "message": "Successfully deleted",
  "deleted_item": { "id": "...", "title": "..." }
}

レイアウト構造

Dashboard 内のウィジェット配置はグリッドレイアウトで定義します。

{
  "x": 0, // 左からの位置 (列)
  "y": 0, // 上からの位置 (行)
  "w": 6, // 幅 (列数、最大 12)
  "h": 4 // 高さ (行数)
}

グリッドは 12 列 のレイアウトです。

レイアウト例

+------+------+
| viz1 | viz2 |  y=0, h=4
| w=6  | w=6  |
+------+------+
|    viz3     |  y=4, h=3
|    w=12     |
+-------------+

チャートタイプ一覧

chartType	説明
`timeline`	時系列ヒストグラム
`bar`	棒グラフ
`line`	折れ線グラフ
`pie`	円グラフ
`doughnut`	ドーナツグラフ
`polarArea`	極座標グラフ
`radar`	レーダーチャート
`markdown`	Markdown テキスト
`table`	テーブル