本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# 儀表板 API
使用 Dashboard API 在 Amazon Managed Grafana 工作區中建立、更新、刪除和使用儀表板。
儀表板的識別符 (id) 是自動遞增的數值，而且每個工作區都是唯一的。儀表板的唯一識別符 (uid) 可用於唯一識別多個 Amazon Managed Grafana 工作區之間的儀表板。如果您在建立儀表板時未提供，則會自動產生。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 內文結構描述：
+ **儀表板** — 完整的儀表板模型。使用 null 建立新的儀表板。
+ **dashboard.id** — 使用 null 建立新的儀表板。
+ **dashboard.uid** — 當您使用此項目建立新的儀表板時，選用的唯一識別符。如果為 null，會產生新的 uid。
+ **資料夾 ID** — 要儲存儀表板的資料夾 ID。
+ **folderUid** — 要儲存儀表板的資料夾的 Uid。覆寫 的值 `folderid`
+ **覆寫** — 指定 `true` 以較新版本、資料夾中相同儀表板標題或相同儀表板 uid 覆寫現有儀表板。
+ **訊息** — 設定版本歷史記錄的遞交訊息。
+ **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
}
]
```