ダッシュボード

このページでは2018年11月のリニューアル後のカスタムダッシュボードのAPIについて説明します。リニューアル以前のカスタムダッシュボードを操作するAPIについてはこちらをご覧ください。

ダッシュボードの作成

ダッシュボードを作成します。

POST /api/v0/dashboards

APIキーに必要な権限

  • Read
  • Write

入力

以下のキーをもつオブジェクト。

KEY TYPE DESCRIPTION
title string ダッシュボード名
memo string ダッシュボードのメモ
urlPath string ダッシュボードのURLのパス *1
widgets array[object] ウィジェットを表すオブジェクトのリスト

*1 urlPath のフォーマットは以下の通りです:

^([A-Za-z0-9_][-A-Za-z0-9_]*)(/[A-Za-z0-9_][-A-Za-z0-9_]*)*$

応答

成功時

作成されたダッシュボードを返します。

KEY TYPE DESCRIPTION
id string ダッシュボードのID *1
title string ダッシュボード名
memo string ダッシュボードのメモ
urlPath string ダッシュボードのURLのパス
widgets array[object] ウィジェットを表すオブジェクトのリスト
createdAt number 作成時刻(エポック秒)
updatedAt number 最終更新時刻(エポック秒)

*1 id は新しく作成されたダッシュボードに割り当てられたIDです。以降のリクエストではこのIDを用いてダッシュボードを識別します。

失敗時

STATUS CODE DESCRIPTION
400 入力が不正だったとき
403 作成できるダッシュボード数の上限に達しているとき / APIキーに書き込み権限がないとき / 許可されたIPアドレス範囲外からのアクセスの場合
409 urlPath に指定したURLのパスに既に他のダッシュボードが存在しているとき

ダッシュボードの取得

GET /api/v0/dashboards/<dashboardId>

APIキーに必要な権限

  • Read

応答

成功時

ダッシュボードの作成と同様の形式です。

失敗時

STATUS CODE DESCRIPTION
404 指定されたIDのダッシュボードがみつからないとき

ダッシュボードの更新

PUT /api/v0/dashboards/<dashboardId>

APIキーに必要な権限

  • Read
  • Write

入力

ダッシュボードの作成と同様の形式です。

応答

成功時

更新後のダッシュボードをダッシュボードの作成と同様の形式で返します。

失敗時

STATUS CODE DESCRIPTION
400 入力が不正だったとき
403 APIキーに書き込み権限がないとき / 許可されたIPアドレス範囲外からのアクセスの場合
404 指定されたIDのダッシュボードがみつからないとき
409 urlPath に指定したURLのパスに既に他のダッシュボードが存在しているとき

ダッシュボードの削除

指定されたIDのダッシュボードを削除します。

DELETE /api/v0/dashboards/<dashboardId>

APIキーに必要な権限

  • Read
  • Write

応答

成功時

削除する直前のダッシュボードをダッシュボードの作成と同様の形式で返します。

失敗時

STATUS CODE DESCRIPTION
403 APIキーに書き込み権限がないとき / 許可されたIPアドレス範囲外からのアクセスの場合
404 指定されたIDのダッシュボードがみつからないとき

ダッシュボードの一覧

GET /api/v0/dashboards

APIキーに必要な権限

  • Read

応答

KEY TYPE DESCRIPTION
dashboards array[object] ダッシュボードのリスト

dashboards にはカスタムダッシュボードとレガシーカスタムダッシュボードの両方が含まれます。それぞれの形式は以下の通りです:

カスタムダッシュボードの場合

KEY TYPE DESCRIPTION
id string ダッシュボードのID
title string ダッシュボード名
memo string ダッシュボードのメモ
urlPath string ダッシュボードのURLのパス
createdAt number 作成時刻(エポック秒)
updatedAt number 最終更新時刻(エポック秒)

レガシーカスタムダッシュボードの場合

KEY TYPE DESCRIPTION
id string ダッシュボードのID
title string ダッシュボード名
urlPath string ダッシュボードのURLのパス
bodyMarkdown string Markdown形式の文字列
createdAt number 作成時刻(エポック秒)
updatedAt number 最終更新時刻(エポック秒)
isLegacy boolean 固定値 true

ウィジェット

ウィジェットを表すオブジェクトは、各ウィジェットの種類ごとに、以下の形式となっています。

グラフウィジェット

KEY TYPE DESCRIPTION
type string 固定文字列 "graph"
title string ウィジェットのタイトル
graph object グラフを表すオブジェクト
range object [optional] グラフの表示期間を表すオブジェクト
layout object レイアウトを表すオブジェクト

数値ウィジェット

KEY TYPE DESCRIPTION
type string 固定文字列 "value"
title string ウィジェットのタイトル
metric object メトリックを表すオブジェクト
layout object レイアウトを表すオブジェクト

Markdownウィジェット

KEY TYPE DESCRIPTION
type string 固定文字列 "markdown"
title string ウィジェットのタイトル
markdown string Mardkwon形式の文字列
layout object レイアウトを表すオブジェクト

グラフ

ホストグラフ

KEY TYPE DESCRIPTION
type string 固定文字列 "host"
hostId string ホストのID
name string グラフ名("loadavg" など)

ロールグラフ

KEY TYPE DESCRIPTION
type string 固定文字列 "role"
roleFullname string サービス名とロール名を:で連結したもの
name string グラフ名("loadavg5" など)
isStacked boolean [optional] グラフが積み重ねグラフかどうか

サービスグラフ

KEY TYPE DESCRIPTION
type string 固定文字列 "service"
serviceName string サービス名
name string グラフ名

式グラフ

KEY TYPE DESCRIPTION
type string 固定文字列 "expression"
expression string グラフを表す式

これらに加えて、ダッシュボード取得時に関連するロール・サービス・グラフ定義が削除されていた場合、次の結果が返却されることがあります。

KEY TYPE DESCRIPTION
type string 固定文字列 "unknown"

グラフの表示期間

未指定の場合は可変となり、ダッシュボード上部に表示されるコントローラーから表示期間を変更できるようになります。

相対

KEY TYPE DESCRIPTION
type string 固定文字列 "relative"
period number 期間の長さ(秒)
offset number 現在時刻からの差(秒)

(現在時刻 + offset - period)から(現在時刻 + offset)までの期間が表示されます。 offset に負の値を指定することで、過去の指定期間のグラフを表示することができます。

絶対

KEY TYPE DESCRIPTION
type string 固定文字列 "absolute"
start number 開始時刻(エポック秒)
end number 終了時刻(エポック秒)

start から end までの期間が表示されます。

メトリック

ホストメトリック

KEY TYPE DESCRIPTION
type string 固定文字列 "host"
hostId string ホストのID
name string メトリック名("loadavg5" など)

サービスメトリック

KEY TYPE DESCRIPTION
type string 固定文字列 "service"
serviceName string サービス名
name string メトリック名

KEY TYPE DESCRIPTION
type string 固定文字列 "expression"
expression string メトリックを表す式

式によるメトリック指定を使用して数値を正しく表示するためには、式の結果が単一の系列を表すようにする必要があります。

これらに加えて、ダッシュボード取得時に関連するサービスが削除されていた場合、次の結果が返却されることがあります。

KEY TYPE DESCRIPTION
type string 固定文字列 "unknown"

レイアウト

KEY TYPE DESCRIPTION
x number ウィジェットのx座標
y number ウィジェットのy座標
width number ウィジェットの幅
height number ウィジェットの高さ

座標はウィジェット表示領域の左上を原点(x = 0, y = 0)として、右方向をx軸、下方向をy軸の正の方向として指定します。また、各数値は以下の条件に従う必要があります。条件に従っていない場合、ウィジェットが期待した位置に表示されないことがあります。

  • 各数値が0または正の整数であること
  • ウィジェット表示領域 (幅24) からウィジェットがはみ出さないこと
  • 他のウィジェットと重ならないこと
  • 各ウィジェットの種類ごとに、以下の最小サイズ以上であること
ウィジェット width の最小値 height の最小値
グラフ 6 6
数値 4 4
Markdown 4 2