控制面板 API - Amazon Managed Grafana
创建/更新控制面板通过 uid 获取仪表板通过 uid 删除控制面板获取主页仪表板获取仪表板标签

本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

控制面板 API

使用控制面板 API 在亚马逊托管 Grafana 工作区中创建、更新、删除和使用控制面板。

仪表板的标识符 (id) 是一个自动递增的数值，并且仅在每个工作区中是唯一的。控制面板的唯一标识符 (uid) 可用于在多个 Amazon Managed Grafana 工作空间之间唯一标识控制面板。如果您在创建仪表板时未提供控制面板，则会自动生成。uid 允许在访问仪表板和在多个工作区之间同步仪表板时使用一致的 URL。使用 uid 意味着更改仪表板的标题不会破坏指向该仪表板的任何已添加书签的链接。

uid 的最大长度可以为 40 个字符。

注意

要在亚马逊托管 Grafana 工作空间中使用 Grafana API，您必须拥有有效的 Grafana API 令牌。您可以将其包含在 API 请求的Authorization字段中。有关如何创建令牌来验证您的 API 调用的信息，请参阅使用令牌进行身份验证。

创建/更新控制面板

POST /api/dashboards/db

创建新仪表板或更新现有仪表板。

创建新仪表板的请求示例

POST /api/dashboards/db HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk

{
  "dashboard": {
    "id": null,
    "uid": null,
    "title": "Production Overview",
    "tags": [ "templated" ],
    "timezone": "browser",
    "schemaVersion": 16,
    "version": 0,
    "refresh": "25s"
  },
  "folderId": 0,
  "folderUid": "l3KqBxCMz",
  "message": "Made changes to xyz",
  "overwrite": false
}

JSON 正文架构：

  • 仪表板-完整的仪表板模型。使用 null 创建新的仪表板。

  • d@@ ashboard.id — 使用空值创建新的仪表板。

  • d@@ ashboard.uid — 使用它创建新仪表板时可选的唯一标识符。如果为空，则生成一个新的 uid。

  • folderid — 用于保存仪表板的文件夹的 ID。

  • folderUID — 用于保存仪表板的文件夹的 Uid。覆盖的值 folderid

  • o@@ verwrit e — 指定true使用较新的版本、文件夹中的相同仪表板标题或相同的仪表板 uid 覆盖现有仪表板。

  • 消息-为版本历史记录设置提交消息。

  • 刷新-设置仪表板刷新间隔。如果该值低于最小刷新间隔，则将其忽略并使用最小刷新间隔。

要为仪表板面板添加或更新警报规则，请声明一个dashboard.panels.alert屏蔽。

更新仪表板警报规则的请求示例

HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
Content-Length: 78

{
 "dashboard":  {
        "id": 104,
        "panels": [
            {
                "alert": {
                    "alertRuleTags": {},
                    "conditions": [
                        {
                            "evaluator": {
                                "params": [
                                    25
                                ],
                                "type": "gt"
                            },
                            "operator": {
                                "type": "and"
                            },
                            "query": {
                                "params": [
                                    "A",
                                    "5m",
                                    "now"
                                ]
                            },
                            "reducer": {
                                "params": [],
                                "type": "avg"
                            },
                            "type": "query"
                        }
                    ],
                    "executionErrorState": "alerting",
                    "for": "5m",
                    "frequency": "1m",
                    "handler": 1,
                    "name": "Panel Title alert",
                    "noDataState": "no_data",
                    "notifications": []
                },
                "aliasColors": {},
                "bars": false,
                "dashLength": 10,
                "dashes": false,
                "datasource": null,
                "fieldConfig": {
                    "defaults": {
                        "custom": {}
                    },
                    "overrides": []
                },
                "fill": 1,
                "fillGradient": 0,
                "gridPos": {
                    "h": 9,
                    "w": 12,
                    "x": 0,
                    "y": 0
                },
                "hiddenSeries": false,
                "id": 2,
                "legend": {
                    "avg": false,
                    "current": false,
                    "max": false,
                    "min": false,
                    "show": true,
                    "total": false,
                    "values": false
                },
                "lines": true,
                "linewidth": 1,
                "nullPointMode": "null",
                "options": {
                    "dataLinks": []
                },
                "percentage": false,
                "pointradius": 2,
                "points": false,
                "renderer": "flot",
                "seriesOverrides": [],
                "spaceLength": 10,
                "stack": false,
                "steppedLine": false,
                "targets": [
                    {
                        "refId": "A",
                        "scenarioId": "random_walk"
                    }
                ],
                "thresholds": [
                    {
                        "colorMode": "critical",
                        "fill": true,
                        "line": true,
                        "op": "gt",
                        "value": 50
                    }
                ],
                "timeFrom": null,
                "timeRegions": [],
                "timeShift": null,
                "title": "Panel Title",
                "tooltip": {
                    "shared": true,
                    "sort": 0,
                    "value_type": "individual"
                },
                "type": "graph",
                "xaxis": {
                    "buckets": null,
                    "mode": "time",
                    "name": null,
                    "show": true,
                    "values": []
                },
                "yaxes": [
                    {
                        "format": "short",
                        "label": null,
                        "logBase": 1,
                        "max": null,
                        "min": null,
                        "show": true
                    },
                    {
                        "format": "short",
                        "label": null,
                        "logBase": 1,
                        "max": null,
                        "min": null,
                        "show": true
                    }
                ],
                "yaxis": {
                    "align": false,
                    "alignLevel": null
                }
            }
        ],
        "title": "Update alert rule via API",
        "uid": "dHEquNzGz",
        "version": 1
    }
}

响应示例

HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
Content-Length: 78

{
  "id":      1,
  "uid":     "cIBgcSjkk",
  "url":     "/d/cIBgcSjkk/production-overview",
  "status":  "success",
  "version": 1,
  "slug":    "production-overview" //deprecated in Grafana v5.0
}

状态码：

  • 200 — 已创建

  • 400 — 错误，例如 JSON 无效、字段无效或缺失

  • 401 — 未经授权

  • 403-访问被拒绝

  • 412-前提条件失败

412 状态码用于解释无法创建仪表板的原因。

  • 其他人更改了控制面板 status=version-mismatch

  • 该文件夹中已存在同名仪表板 status=name-exists

  • 已存在具有相同 uid 的仪表板 status=name-exists

  • 仪表板属于插件 plugin title status=plugin-dashboard

响应正文具有以下属性。如果另一个仪表板具有相同的标题，则status值为name-exists。

HTTP/1.1 412 Precondition Failed
Content-Type: application/json; charset=UTF-8
Content-Length: 97

{
  "message": "The dashboard has been changed by someone else",
  "status": "version-mismatch"
}

通过 uid 获取仪表板

GET /api/dashboards/uid/:uid

返回与 uid 匹配的仪表板。返回的元数据可能包含有关包含仪表板的文件夹的 UID 的信息。

示例请求

GET /api/dashboards/uid/cIBgcSjkk HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk

响应示例

HTTP/1.1 200
Content-Type: application/json

{
  "dashboard": {
    "id": 1,
    "uid": "cIBgcSjkk",
    "title": "Production Overview",
    "tags": [ "templated" ],
    "timezone": "browser",
    "schemaVersion": 16,
    "version": 0
  },
  "meta": {
    "isStarred": false,
    "url": "/d/cIBgcSjkk/production-overview",
    "folderId": 2,
    "folderUid": "l3KqBxCMz",
    "slug": "production-overview" //deprecated in Grafana v5.0
  }
}

状态码：

  • 200 — 已找到

  • 401 — 未经授权

  • 403-访问被拒绝

  • 404 — 未找到

通过 uid 删除控制面板

DELETE /api/dashboards/uid/:uid

删除与 uid 匹配的仪表板。

示例请求

DELETE /api/dashboards/uid/cIBgcSjkk HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk

响应示例

HTTP/1.1 200
Content-Type: application/json

{
  "title": "Production Overview",
  "message": "Dashboard Production Overview deleted",
  "id": 2
}

状态码：

  • 200 — 已删除

  • 401 — 未经授权

  • 403-访问被拒绝

  • 404 — 未找到

获取主页仪表板

GET /api/dashboards/home

返回主页仪表板。

示例请求

GET /api/dashboards/home HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk

响应示例

HTTP/1.1 200
Content-Type: application/json

{
  "dashboard": {
    "editable":false,
    "hideControls":true,
    "nav":[
      {
        "enable":false,
        "type":"timepicker"
      }
    ],
    "style":"dark",
    "tags":[],
    "templating":{
      "list":[
      ]
    },
    "time":{
    },
    "timezone":"browser",
    "title":"Home",
    "version":5
  },
  "meta":	{
    "isHome":true,
    "canSave":false,
    "canEdit":false,
    "canStar":false,
    "url":"",
    "expires":"0001-01-01T00:00:00Z",
    "created":"0001-01-01T00:00:00Z"
  }
}

获取仪表板标签

GET /api/dashboards/tags

返回仪表板的所有标签。

示例请求

GET /api/dashboards/tags HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk

响应示例

HTTP/1.1 200
Content-Type: application/json

[
  {
    "term":"tag1",
    "count":1
  },
  {
    "term":"tag2",
    "count":4
  }
]