Superset REST API 操作

要解决什么问题

在 Apache Superset 里改图表指标、筛选项或看板布局，如果只能点 UI 或依赖 SSH/MCP，很难和自动化脚本、对话式助手对齐。本技能把操作收敛到 Superset 原生 REST API：鉴权、读改写 chart、核对 dataset 列、理解 position_json 布局，全部走 HTTP。

核心能力与典型流程

连接与鉴权

• 先配置 Superset 基址，再调用登录接口拿到 access_token（约 15 分钟过期），后续请求在 Header 里带上。
• 凭证未提供时应向用户索取。

图表（Chart）

• GET /api/v1/chart/{id} 返回的 result.params 是 JSON 字符串，需 json.loads() 后再改。
• PUT 更新会立即持久化；提交时 params 必须再 json.dumps() 成字符串，不能直接传对象。
• 新建图表走 POST /api/v1/chart/。

数据集（Dataset）

• 改 metrics 前用 GET /api/v1/dataset/{id} 核对 result.columns 里的 column_name 与类型。
• 可用 GET /api/v1/dataset/ 列举数据集。

看板（Dashboard）

• GET /api/v1/dashboard/{id} 的 result.position_json 描述布局；CHART 节点的 meta.chartId 对应图表 ID。
• 布局需遵守 ROOT → GRID → ROW → COLUMN → CHART 层级，每行 12 栅格；每个 CHART 必须有完整的 ROW/COLUMN 父链。

改图推荐步骤

1. 鉴权取 token
2. GET chart 读当前 params
3. 明确要改 metrics / filters / columns
4. 若动 metrics，先 GET dataset 验列
5. 修改 params 并 PUT chart
6. 提示用户刷新看板

技能内还整理了常见 viz_type 的 params 模板（如 echarts_timeseries_bar、pie、big_number_total、table）以及 metric（单对象） 与 metrics（数组） 的对应关系（Superset 6.1）。

边界与注意点

• 文档标注为 已移除、勿用 的类型包括：scatter_chart、dist_bar、heatmap、histogram、sankey、sunburst、treemap 等旧 viz。
• SQL 表达式指标需按各图表类型字段约定填写；table 等类型无 metric 字段。
• 完整端点说明见技能附带的 reference.md，本介绍不替代官方 API 文档。