本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。
# 控制面板 API
使用控制面板 API 在 Amazon Managed Grafana 工作区中创建、更新、删除和处理控制面板。
控制面板的标识符（id）是一个自动递增的数值，并且对于每个工作区是唯一的。控制面板的唯一标识符（uid）可用于在多个 Amazon Managed Grafana 工作区之间唯一标识控制面板。如果您在创建控制面板时未提供 uid，则会自动生成一个。uid 允许在访问仪表板和在多个 URLs 工作区之间同步仪表板时保持一致。使用 uid 意味着更改控制面板的标题不会破坏指向该控制面板的任何已添加书签的链接。
uid 最多可包含 40 个字符。
**注意**
要对 Amazon Managed Grafana 工作区使用 Grafana API，您必须拥有有效的 Grafana API 令牌。您可以将其包含在 API 请求的 `Authorization` 字段中。有关如何创建令牌对 API 调用进行身份验证的信息，请参阅 [使用令牌进行身份验证](authenticating-grafana-apis.md)。
## 创建/更新控制面板
```
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 正文架构：
+ **dashboard**：完整的控制面板模型。使用空值创建新的控制面板。
+ **dashboard.id**：使用空值创建新的控制面板。
+ **dashboard.uid**：使用它创建新控制面板时可选的唯一标识符。如果为空，则生成一个新的 uid。
+ **folderid**：用于保存控制面板的文件夹的 ID。
+ **folderUID**：用于保存控制面板的文件夹的 Uid。覆盖 `folderid` 的值
+ **overwrite**：指定 `true` 以使用较新的版本、文件夹中的相同控制面板标题或相同的控制面板 uid 覆盖现有控制面板。
+ **message**：为版本历史记录设置提交消息。
+ **refresh**：设置控制面板刷新间隔。如果值低于最小刷新间隔，则将忽略该值并使用最小刷新间隔。
要为控制面板的面板添加或更新警报规则，请声明一个 `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
}
]
```