kibana-dashboards

Kibana ダッシュボードと Lens のビジュアライゼーション

Kibana 9.4 以降の Dashboards API と Visualizations API を使用して、Kibana ダッシュボードとスタンドアロンの Lens ビジュアライゼーションを作成、更新、削除します。差分を確認しやすい最小限の JSON 本文を作成し、ライブラリ参照よりインラインのパネル定義を優先します。また、メトリックやチャートレイヤーを作成する前に、正しいデータセットタイプ（データビューと ES|QL のどちらか）を選択します。

環境設定

このスキルは、elastic CLI を介して Elasticsearch の操作を実行します。 elastic CLI がインストールされていない場合は、何に使用するかをユーザーに伝えてください。認証情報を推測したり、HTTP API を直接呼び出したり、ほかの回避策を試みたりしないでください。

このスキルでは、HTTP 短縮形式（例：GET /、GET /_cat/indices、GET /{index}/_mapping、 GET /{index}/_settings/index.mode、POST /_query）で操作を記載しています。このドキュメントの末尾にある 操作の表で、各短縮形式に対応する elastic CLI コマンドを示しています。HTTP API を直接呼び出すのではなく、必ず CLI を使用してください。

前提条件

バージョン要件： Kibana 9.4 以降（Dashboards API と Visualizations API）。

ES|QL の配置：

• スタンドアロンのライブラリチャート：data_source.type: "esql" を指定して PUT kbn:/api/visualizations/{id} を実行します。
• ダッシュボードに埋め込む ES|QL パネル：PUT kbn:/api/dashboards/{id} を介して、data_source.type: "esql" を指定したインライン vis パネルの config を使用します。
• ユーザーが ES|QL を明示的に要求している場合は、data_source.type: "data_view_reference" やインデックスパターンの集計を使用しないでください。永続化された Lens の状態では、データビューの件数操作ではなく、テキストベースの ES|QL データソース（textBased / esql）を使用する必要があります。

プロセス

1. Kibana への接続を確認します。 GET kbn:/api/status を呼び出します。呼び出しに失敗した場合は処理を停止し、エラーを提示してください。エンドポイントや認証情報を推測しないでください。version.number を読み取り、クラスターが 9.4 以降の要件を満たしていることを確認します。

2. タスクを分類します。 ユーザーが必要としているのが、パネルのコレクションと任意の時間範囲を含むダッシュボード、ライブラリ項目として ID で参照するか単独で使用するスタンドアロンの Lens ビジュアライゼーション、またはその両方のどれかを判断します。決定的な保存オブジェクト ID が指定されているか確認します。指定されている場合は、ID を自動生成する POST ではなく、その ID を指定した upsert（PUT）を使用します。

3. メトリックやレイヤーを作成する前に、データセットタイプを選択します。

   ユーザーの意図	データセット	メトリック／軸のパターン
   保存済みデータビューでの単純な件数または集計	ref_id を指定した data_source.type: "data_view_reference"	metrics: [{ type: "primary", operation: "count" }]（またはその他の集計操作）
   アドホックなインデックスパターン	index_pattern と time_field を指定した data_source.type: "data_view_spec"	同じ集計の operation フィールド
   ES	QL クエリ（明示的な要求または複雑なロジック）	query を指定した data_source.type: "esql"

   集計は ES|QL クエリ内（STATS count = COUNT()）に記述し、結果の列を名前で参照してください。

4. ダッシュボードの作成時または更新時に、ダッシュボードの本文を作成します。 リクエスト本文はフラットで、ルートに title、panels、任意の time_range を指定します。書き込み時に { data: ... } でラップしないでください。必須フィールドは次のとおりです。

   • title — ユーザーが指定した文字列をそのまま指定します。
   • panels — 配列です。ユーザーが空のダッシュボードを求めた場合は [] を使用します（キーを省略したり、パネルを勝手に追加したりしないでください）。
   • time_range — ユーザーがデフォルトの時間フィルターを指定した場合は、{ "from": "<expr>", "to": "<expr>" } を設定します（例：{ "from": "now-7d", "to": "now" }）。time_range を指定すると、ダッシュボードを開いたときに時間フィルターが保持されます（UI で時間の復元を有効にするのと同等です）。

   決定的な ID で Upsert する場合：

   {
     "title": "Sales Overview",
     "panels": [],
     "time_range": { "from": "now-7d", "to": "now" }
   }
   

   ユーザーがその ID を指定した場合は、上記の本文を使用して PUT kbn:/api/dashboards/eval-sales-overview を呼び出します。

   インライン ES|QL メトリックパネルの例（panels 内）：

   {
     "type": "vis",
     "id": "total-requests",
     "grid": { "x": 0, "y": 0, "w": 12, "h": 6 },
     "config": {
       "title": "Total Requests",
       "type": "metric",
       "data_source": {
         "type": "esql",
         "query": "FROM logs* | STATS count = COUNT()"
       },
       "metrics": [{ "type": "primary", "column": "count" }]
     }
   }
   

   移植可能なダッシュボードでは、config.ref_id よりもインラインの config プロパティを優先してください。パネルの種類、グリッドレイアウト、コピーのワークフローについては、Dashboard API Reference を参照してください。

5. ライブラリのグラフを求められた場合は、スタンドアロンの Lens ビジュアライゼーションを作成します。 Visualizations API を使用します。ID が指定されている場合は PUT kbn:/api/visualizations/{id} で Upsert し、指定されていない場合は POST kbn:/api/visualizations を呼び出して、レスポンスから生成された ID を報告します。

   ES|QL メトリック（ログの合計件数）：

   {
     "type": "metric",
     "title": "Total Requests",
     "data_source": {
       "type": "esql",
       "query": "FROM logs* | STATS count = COUNT()"
     },
     "metrics": [{ "type": "primary", "column": "count" }]
   }
   

   その ID が必要な場合は、PUT kbn:/api/visualizations/eval-total-requests を呼び出します。この API は、データソースの状態にインデックスパターンの集計ではなく ES|QL（textBased / esql）を使用する Lens の保存オブジェクトを永続化します。

   xy、ゲージ、ヒートマップ、その他のグラフスキーマについては、Lens API Reference とChart Types Reference を参照してください。

6. 実行して確認します。 PUT kbn:/api/dashboards/{id} または PUT kbn:/api/visualizations/{id} で書き込みを実行します（ID が指定されていない場合は POST を使用します）。GET kbn:/api/dashboards/{id} または GET kbn:/api/visualizations/{id} で確認します。ユーザーに ID とタイトルを報告してください。読み取りによる確認が成功する前に、成功したと伝えないでください。

7. 要求に応じて一覧表示、エクスポート、削除を行います。 既存のオブジェクトを検索するには、GET kbn:/api/dashboards または GET kbn:/api/visualizations を呼び出します。オブジェクトを削除するには、DELETE kbn:/api/dashboards/{id} または DELETE kbn:/api/visualizations/{id} を呼び出します。保存オブジェクトを一括エクスポートまたはインポートするには、POST kbn:/api/saved_objects/_export または POST kbn:/api/saved_objects/_import を呼び出します。

ダッシュボードのグリッド

ダッシュボードでは 48 列のグリッドを使用します。16:9 画面では、折り返し位置より上におよそ 20～24 行が収まります。この範囲には 8～12 個のパネルを目安に配置します。

幅	列数	高さ（行）	用途
全幅	48	14～16	幅広の時系列、テーブル
半分	24	10～12	主要なグラフ
4 分の 1	12	5～6	KPI メトリック
6 分の 1	8	4～5	高密度のメトリック行

グリッドへの配置： 行を積み重ねる場合、次のパネルの y は前のパネルの y + h に設定します。同じ行を共有するパネルには、同じ h を設定します。ダッシュボードのタイトルとして Markdown パネルを追加しないでください。代わりに、内容が分かるグラフタイトルを使用してください。

ES|QL のパターン

時系列バケット（ダッシュボードの時間ピッカーが ?_tstart / ?_tend を挿入します）：

FROM logs*
| WHERE @timestamp <= ?_tend AND @timestamp > ?_tstart
| STATS count = COUNT() BY BUCKET(@timestamp, 75, ?_tstart, ?_tend)

時系列 xy グラフでは、x 軸に "scale": "temporal" を設定します。軸やレイヤーの詳細については、Chart Types Reference を参照してください。

静的な参照値 — クエリで EVAL を使用し、その列を参照します。

FROM logs* | STATS count = COUNT() | EVAL goal = 15000

例

JSON 定義の例は assets/ の下にあります：demo-dashboard.json、dashboard-with-visualizations.json、metric-esql.json、bar-chart-esql.json、line-chart-timeseries.json。

ガイドライン

1. ユーザーから ID とタイトルが指定された場合は、そのまま一致させてください。自動生成された ID に置き換えないでください。
2. 空のパネルを尊重してください。ユーザーが panels: [] を指定した場合は、空の配列を送信してください。プレースホルダーのパネルを追加しないでください。
3. 指定された場合は ES|QL を使用してください。data_source.type: "esql" とカラム参照を使ってください。データビューに対する operation: "count" で ES|QL の要求を満たそうとしないでください。
4. ペイロードは最小限にしてください。導出可能なデフォルト値は省略し、スタイルとメタデータは API に設定させてください。
5. 書き込みを確認してください。作成または更新の後は、必ず GET で読み戻してください。
6. 複雑なチャートを作成する前にリファレンスを確認してください。メトリックと XY のスキーマはデータビューと ES|QL で異なります。分割チャートまたはテーブルチャートを生成する前に、チャートタイプのリファレンスを参照してください。

よくある問題

エラー	考えられる原因	対処
PUT 後の GET が 404	ID またはスペースが違う	ID を確認して GET kbn:/api/dashboards/{id} を再試行してください
400 バリデーションエラー	ES|QL のカラムが一致しない	metrics[].column ／レイヤーの column をクエリ内の STATS エイリアスに合わせてください
ES|QL パネルがデータビューとして保存される	データセットタイプが違う	data_view_reference ではなく、data_source.type: "esql" を使用してください
空のダッシュボードに時間フィルターがない	time_range が省略されている	デフォルトの範囲が必要な場合は { "from": "now-7d", "to": "now" } を含めてください
XY チャートの作成に失敗	レイヤーの data_source がない	data_source はルートだけでなく、各レイヤー内に配置してください

操作

CLI v0.3.0 以降では、ダッシュボードとビジュアライゼーションの API に専用の elastic kb dashboards コマンドと elastic kb visualizations コマンドが用意されており、ID を指定してオブジェクトの一覧表示、読み取り、更新、削除ができます。create-*-redirect コマンドはまだリクエストボディを受け付けないため、新しいオブジェクトを書き込むには、ID を指定して update-*-redirect（PUT） コマンドを使用してください。JSON ボディは --input-file で渡します。複数のオブジェクトを一度に作成するには、保存オブジェクトの NDJSON を作成して post-saved-objects-import でインポートします（post-saved-objects-export で読み戻せます）。

HTTP API（省略形）	elastic CLI コマンド
GET kbn:/api/status	elastic kb system get-status
POST kbn:/api/saved_objects/_import	elastic kb saved-objects post-saved-objects-import --file '<path.ndjson>' --overwrite
POST kbn:/api/saved_objects/_export	elastic kb saved-objects post-saved-objects-export --objects '[{"type":"<type>","id":"<id>"}]'
GET kbn:/api/dashboards	elastic kb dashboards get-dashboards-redirect
GET kbn:/api/dashboards/{id}	elastic kb dashboards get-dashboard-redirect --id '<id>'
PUT kbn:/api/dashboards/{id}	elastic kb dashboards update-dashboard-redirect --id '<id>' --input-file '<path.json>'
DELETE kbn:/api/dashboards/{id}	elastic kb dashboards delete-dashboard-redirect --id '<id>'
POST kbn:/api/dashboards（ID なし）	create-dashboard-redirect はまだボディを受け付けません — ID を指定して update-dashboard-redirect を使用するか、post-saved-objects-import（タイプ dashboard）で作成してください
GET kbn:/api/visualizations	elastic kb visualizations get-visualizations-redirect
GET kbn:/api/visualizations/{id}	elastic kb visualizations get-visualization-redirect --id '<id>'
PUT kbn:/api/visualizations/{id}	elastic kb visualizations update-visualization-redirect --id '<id>' --input-file '<path.json>'
DELETE kbn:/api/visualizations/{id}	elastic kb visualizations delete-visualization-redirect --id '<id>'
POST kbn:/api/visualizations（ID なし）	create-visualization-redirect はまだボディを受け付けません — ID を指定して update-visualization-redirect を使用するか、post-saved-objects-import（タイプ lens）で作成してください