grafana-skill

grafana-skill

使用 TypeScript 工具和 HTTP API 工作流以编程方式管理 Grafana 资源。

工作流路由

工作流	触发条件	文件
DashboardCrud	“创建仪表盘”、“更新仪表盘”、“删除仪表盘”、“列出仪表盘”、“导出仪表盘”	Tools/DashboardCrud.ts
GrafanaClient	“grafana API”、“grafana client”、“TypeScript grafana”	Tools/GrafanaClient.ts
ApiReference	“grafana API reference”、“grafana endpoints”	References/

工具

DashboardCrud CLI

# Set environment variables
export GRAFANA_URL="https://grafana.example.com"
export GRAFANA_TOKEN="your-service-account-token"

# List dashboards
bun run Tools/DashboardCrud.ts list
bun run Tools/DashboardCrud.ts list --query production --tag monitoring

# Get dashboard by UID
bun run Tools/DashboardCrud.ts get abc123

# Export dashboard to JSON
bun run Tools/DashboardCrud.ts export abc123 --output dashboard.json

# Create dashboard from JSON file
bun run Tools/DashboardCrud.ts create --file dashboard.json --folder my-folder

# Update dashboard
bun run Tools/DashboardCrud.ts update abc123 --file updated.json --message "Updated panels"

# Clone dashboard
bun run Tools/DashboardCrud.ts clone abc123 --title "Production Copy" --folder prod-folder

# View version history
bun run Tools/DashboardCrud.ts versions abc123

# Restore to previous version
bun run Tools/DashboardCrud.ts restore abc123 --version 5

# Delete dashboard
bun run Tools/DashboardCrud.ts delete abc123

GrafanaClient TypeScript 库

import { GrafanaClient, createGrafanaClient } from './Tools/GrafanaClient';

// Initialize from environment variables
const client = createGrafanaClient();

// Or with explicit config
const client = new GrafanaClient({
  baseUrl: 'https://grafana.example.com',
  token: 'your-service-account-token',
  orgId: 1, // optional
});

// Dashboard operations
const dashboards = await client.searchDashboards({ query: 'production', tag: 'monitoring' });
const dashboard = await client.getDashboardByUid('abc123');
const saved = await client.saveDashboard({ dashboard: myDashboard, folderUid: 'folder-uid' });
await client.deleteDashboard('abc123');

// Version management
const versions = await client.getDashboardVersions('abc123');
await client.restoreDashboardVersion('abc123', 5);

// Folders, Data sources, Alerting, Annotations also available

身份验证

# Service Account Token (Recommended)
export GRAFANA_TOKEN="glsa_xxxxxxxxxxxxxxxxxxxx"

# Multi-Organization Header
curl -H "Authorization: Bearer $GRAFANA_TOKEN" \
     -H "X-Grafana-Org-Id: 2" \
     https://grafana.example.com/api/org

API 快速参考

资源	列表	获取	创建	更新	删除
仪表盘	GET /api/search	GET /api/dashboards/uid/:uid	POST /api/dashboards/db	POST /api/dashboards/db	DELETE /api/dashboards/uid/:uid
文件夹	GET /api/folders	GET /api/folders/:uid	POST /api/folders	PUT /api/folders/:uid	DELETE /api/folders/:uid
数据源	GET /api/datasources	GET /api/datasources/uid/:uid	POST /api/datasources	PUT /api/datasources/uid/:uid	DELETE /api/datasources/uid/:uid
告警规则	GET /api/v1/provisioning/alert-rules	GET /api/v1/provisioning/alert-rules/:uid	POST /api/v1/provisioning/alert-rules	PUT /api/v1/provisioning/alert-rules/:uid	DELETE /api/v1/provisioning/alert-rules/:uid

参考文档

• 仪表盘：完整的仪表盘 CRUD、版本和权限
• 数据源：数据源管理、查询和健康检查
• 告警：告警规则、联系人和通知策略
• 文件夹：文件夹管理和权限
• 注释：创建、查询和更新注释
• 用户与团队：用户管理和团队操作
• 常见模式：错误处理、分页和实用工具

示例

示例 1：列出并导出仪表盘

User: "List all production dashboards and export them"
→ bun run Tools/DashboardCrud.ts list --tag production
→ For each: bun run Tools/DashboardCrud.ts export <uid>
→ Returns list of exported JSON files

示例 2：从 JSON 创建仪表盘

User: "Create a new dashboard from this JSON file"
→ bun run Tools/DashboardCrud.ts create --file dashboard.json --folder monitoring
→ Returns new dashboard UID and URL

示例 3：将仪表盘克隆到另一个文件夹

User: "Clone the CPU dashboard to the production folder"
→ bun run Tools/DashboardCrud.ts clone cpu-uid --title "CPU Prod" --folder prod-folder
→ Returns cloned dashboard details

示例 4：恢复仪表盘版本

User: "Restore dashboard abc123 to version 5"
→ bun run Tools/DashboardCrud.ts versions abc123
→ bun run Tools/DashboardCrud.ts restore abc123 --version 5
→ Dashboard restored, new version created

示例 5：以编程方式批量更新

User: "Write TypeScript to bulk update dashboard tags"
→ Uses GrafanaClient library:
   const client = createGrafanaClient();
   const dashboards = await client.searchDashboards({ tag: 'old-tag' });
   for (const dash of dashboards) {
     const full = await client.getDashboardByUid(dash.uid);
     full.dashboard.tags = full.dashboard.tags.filter(t => t !== 'old-tag');
     full.dashboard.tags.push('new-tag');
     await client.saveDashboard({ dashboard: full.dashboard, message: 'Updated tags' });
   }

错误处理

代码	说明
200	成功
400	错误请求（JSON 无效、缺少必填字段）
401	未经授权（令牌无效或缺失）
403	禁止访问（权限不足）
404	未找到
409	冲突（资源已存在）
412	前置条件失败（版本不匹配）

提示

1. 优先使用 UID 而非 ID：UID 可在不同 Grafana 实例之间移植
2. 更新时包含版本号：防止覆盖并发更改
3. 谨慎使用 overwrite: true：仅在需要强制更新时使用
4. 优先使用服务账号而非 API 密钥：较新版本的 Grafana 已弃用 API 密钥