Back to Details

grafana-skill

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

grafana-skill

Grafana管理技能

Programmatically manage Grafana resources using TypeScript tools and HTTP API workflows.
使用TypeScript工具和HTTP API工作流以编程方式管理Grafana资源。

Workflow Routing

工作流路由

WorkflowTriggerFile
DashboardCrud"create dashboard", "update dashboard", "delete dashboard", "list dashboards", "export dashboard"
Tools/DashboardCrud.ts
GrafanaClient"grafana API", "grafana client", "TypeScript grafana"
Tools/GrafanaClient.ts
ApiReference"grafana API reference", "grafana endpoints"
References/
工作流触发词文件
DashboardCrud"创建仪表板", "更新仪表板", "删除仪表板", "列出仪表板", "导出仪表板"
Tools/DashboardCrud.ts
GrafanaClient"Grafana API", "Grafana客户端", "TypeScript Grafana"
Tools/GrafanaClient.ts
ApiReference"Grafana API参考", "Grafana端点"
References/

Tools

工具

DashboardCrud CLI

DashboardCrud 命令行工具

bash
undefined
bash
undefined

Set environment variables

设置环境变量

export GRAFANA_URL="https://grafana.example.com" export GRAFANA_TOKEN="your-service-account-token"
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
bun run Tools/DashboardCrud.ts list bun run Tools/DashboardCrud.ts list --query production --tag monitoring

Get dashboard by UID

通过UID获取仪表板

bun run Tools/DashboardCrud.ts get abc123
bun run Tools/DashboardCrud.ts get abc123

Export dashboard to JSON

将仪表板导出为JSON

bun run Tools/DashboardCrud.ts export abc123 --output dashboard.json
bun run Tools/DashboardCrud.ts export abc123 --output dashboard.json

Create dashboard from JSON file

从JSON文件创建仪表板

bun run Tools/DashboardCrud.ts create --file dashboard.json --folder my-folder
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"
bun run Tools/DashboardCrud.ts update abc123 --file updated.json --message "更新面板"

Clone dashboard

克隆仪表板

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

View version history

查看版本历史

bun run Tools/DashboardCrud.ts versions abc123
bun run Tools/DashboardCrud.ts versions abc123

Restore to previous version

恢复到历史版本

bun run Tools/DashboardCrud.ts restore abc123 --version 5
bun run Tools/DashboardCrud.ts restore abc123 --version 5

Delete dashboard

删除仪表板

bun run Tools/DashboardCrud.ts delete abc123
undefined
bun run Tools/DashboardCrud.ts delete abc123
undefined

GrafanaClient TypeScript Library

GrafanaClient TypeScript库

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
typescript
import { GrafanaClient, createGrafanaClient } from './Tools/GrafanaClient';

// 从环境变量初始化
const client = createGrafanaClient();

// 或者使用显式配置
const client = new GrafanaClient({
  baseUrl: 'https://grafana.example.com',
  token: 'your-service-account-token',
  orgId: 1, // 可选
});

// 仪表板操作
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');

// 版本管理
const versions = await client.getDashboardVersions('abc123');
await client.restoreDashboardVersion('abc123', 5);

// 文件夹、数据源、告警、注释操作同样可用

Authentication

身份验证

bash
undefined
bash
undefined

Service Account Token (Recommended)

服务账户令牌（推荐）

export GRAFANA_TOKEN="glsa_xxxxxxxxxxxxxxxxxxxx"
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
undefined
curl -H "Authorization: Bearer $GRAFANA_TOKEN"
-H "X-Grafana-Org-Id: 2"
https://grafana.example.com/api/org
undefined

Quick API Reference

快速API参考

ResourceListGetCreateUpdateDelete
Dashboards
GET /api/search
GET /api/dashboards/uid/:uid
POST /api/dashboards/db
POST /api/dashboards/db
DELETE /api/dashboards/uid/:uid
Folders
GET /api/folders
GET /api/folders/:uid
POST /api/folders
PUT /api/folders/:uid
DELETE /api/folders/:uid
Data Sources
GET /api/datasources
GET /api/datasources/uid/:uid
POST /api/datasources
PUT /api/datasources/uid/:uid
DELETE /api/datasources/uid/:uid
Alert Rules
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
资源列出获取创建更新删除
仪表板
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

Reference Documentation

参考文档

  • Dashboards: Complete dashboard CRUD, versions, permissions
  • DataSources: Data source management, queries, health checks
  • Alerting: Alert rules, contact points, notification policies
  • Folders: Folder management and permissions
  • Annotations: Create, query, update annotations
  • UsersTeams: User management, team operations
  • CommonPatterns: Error handling, pagination, utilities
  • 仪表板: 完整的仪表板增删改查、版本、权限管理
  • 数据源: 数据源管理、查询、健康检查
  • 告警: 告警规则、联系点、通知策略
  • 文件夹: 文件夹管理与权限
  • 注释: 创建、查询、更新注释
  • 用户与团队: 用户管理、团队操作
  • 通用模式: 错误处理、分页、工具函数

Examples

示例

Example 1: List and export dashboards
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
Example 2: Create dashboard from 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
Example 3: Clone dashboard to another folder
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
Example 4: Restore dashboard version
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
Example 5: Programmatic bulk update
typescript
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' });
   }
示例1：列出并导出仪表板
用户: "列出所有生产环境仪表板并导出"
→ bun run Tools/DashboardCrud.ts list --tag production
→ 对每个仪表板执行: bun run Tools/DashboardCrud.ts export <uid>
→ 返回导出的JSON文件列表
示例2：从JSON文件创建仪表板
用户: "从这个JSON文件创建一个新仪表板"
→ bun run Tools/DashboardCrud.ts create --file dashboard.json --folder monitoring
→ 返回新仪表板的UID和URL
示例3：克隆仪表板到其他文件夹
用户: "将CPU仪表板克隆到生产环境文件夹"
→ bun run Tools/DashboardCrud.ts clone cpu-uid --title "CPU Prod" --folder prod-folder
→ 返回克隆后的仪表板详情
示例4：恢复仪表板版本
用户: "将仪表板abc123恢复到版本5"
→ bun run Tools/DashboardCrud.ts versions abc123
→ bun run Tools/DashboardCrud.ts restore abc123 --version 5
→ 仪表板已恢复，创建了新版本
示例5：程序化批量更新
typescript
用户: "编写TypeScript代码批量更新仪表板标签"
→ 使用GrafanaClient库:
   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' });
   }

Error Handling

错误处理

CodeDescription
200Success
400Bad request (invalid JSON, missing required fields)
401Unauthorized (invalid/missing token)
403Forbidden (insufficient permissions)
404Not found
409Conflict (resource already exists)
412Precondition failed (version mismatch)
状态码描述
200成功
400错误请求（无效JSON、缺少必填字段）
401未授权（令牌无效/缺失）
403禁止访问（权限不足）
404未找到资源
409冲突（资源已存在）
412前置条件失败（版本不匹配）

Tips

提示

  1. Use UIDs over IDs: UIDs are portable across Grafana instances
  2. Include version for updates: Prevents overwriting concurrent changes
  3. Use 
    overwrite: true
    carefully    : Only when you want to force-update
  4. Service accounts over API keys: API keys are deprecated in newer Grafana versions
  1. 使用UID而非ID: UID可在不同Grafana实例间移植
  2. 更新时包含版本信息: 防止覆盖并发修改
  3. 谨慎使用
    overwrite: true
    : 仅在需要强制更新时使用
  4. 使用服务账户而非API密钥: 在新版Grafana中API密钥已被弃用