資料夾 API

使用資料夾 API 來處理 Amazon 受管的 Grafana 工作區中的資料夾。

資料夾的識別碼 (id) 是自動遞增的數值，且每個工作區僅具唯一性。資料夾的唯一識別碼 (uid) 可用來唯一識別多個工作區之間的資料夾。如果您在建立資料夾時未提供資料夾，系統會自動產生該資料夾。uid 允許使用一致的 URL 來存取資料夾，以及在多個 Amazon 受管的 Grafana 工作區之間同步資料夾時使用。使用 uid 意味著更改文件夾的標題不會破壞指向該文件夾的任何書籤鏈接。

uid 的長度上限為 40 個字元。

資料夾無法嵌套。

注意

若要將 Grafana API 與您的 Amazon 受管理工作區搭配使用，您必須擁有有效的 Grafana API 權杖。您可以在 API 要求的Authorization欄位中包含此項目。如需如何建立權杖以驗證 API 呼叫的相關資訊，請參閱使用令牌進行身。

「一般」資料夾id的值為 0，不屬於「資料夾 API」的一部分。您無法使用資料夾 API 擷取一般資料夾的相關資訊。

建立資料夾

POST /api/folders

建立新資料夾。

範例請求

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

{
  "uid": "nErXDvCkzz",
  "title": "Department ABC"
}

主體結構定義：

• uid — 可選的唯一標識符。如果為空，則會產生一個新的 uid。

• 標題 — 資料夾的標題。

回應範例

HTTP/1.1 200
Content-Type: application/json

{
  "id":1,
  "uid": "nErXDvCkzz",
  "title": "Department ABC",
  "url": "/dashboards/f/nErXDvCkzz/department-abc",
  "hasAcl": false,
  "canSave": true,
  "canEdit": true,
  "canAdmin": true,
  "createdBy": "admin",
  "created": "2018-01-31T17:43:12+01:00",
  "updatedBy": "admin",
  "updated": "2018-01-31T17:43:12+01:00",
  "version": 1
}

狀態碼：

• 200 — 已建立

• 400 — 錯誤，例如無效的 JSON、無效或遺失的欄位

• 401 — 未經授權

• 403 — 訪問被拒絕

更新資料夾

PUT /api/folders/:uid

更新符合 uid 的現有資料夾。

範例請求

PUT /api/folders/nErXDvCkzz HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk

{
  "title":"Department DEF",
  "version": 1
}

主體結構定義：

• uid — 變更唯一識別碼 (若有提供)。

• 標題 — 資料夾的標題。

• 版本 — 提供目前版本，以便能夠覆寫資料夾。如果不需要overwrite=true。

• overwrite — 設定為可true使用較新版本覆寫現有資料夾。

回應範例

HTTP/1.1 200
Content-Type: application/json

{
  "id":1,
  "uid": "nErXDvCkzz",
  "title": "Department DEF",
  "url": "/dashboards/f/nErXDvCkzz/department-def",
  "hasAcl": false,
  "canSave": true,
  "canEdit": true,
  "canAdmin": true,
  "createdBy": "admin",
  "created": "2018-01-31T17:43:12+01:00",
  "updatedBy": "admin",
  "updated": "2018-01-31T17:43:12+01:00",
  "version": 1
}

狀態碼：

• 200 — 已建立

• 400 — 錯誤，例如無效的 JSON、無效或遺失的欄位

• 401 — 未經授權

• 403 — 訪問被拒絕

• 404 — 找不到資料夾

• 412 — 先決條件失敗

412 狀態碼用於解釋資料夾無法更新的原因。

• 資料夾已被其他人變更 status=version-mismatch

響應主體具有以下屬性：

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

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

取得所有資料夾

GET /api/folders

傳回您有權檢視的所有資料夾。您可以控制使用 limit query 參數傳回的資料夾數目上限。預設為 1000。

範例請求

GET /api/folders?limit=10 HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk

回應範例

HTTP/1.1 200
Content-Type: application/json

[
  {
    "id":1,
    "uid": "nErXDvCkzz",
    "title": "Department ABC"
  },
  {
    "id":2,
    "uid": "k3S1cklGk",
    "title": "Department RND"
  }
]

通過 uid 獲取文件夾

GET /api/folders/:uid

返回與給定 uid 匹配的所有文件夾。

範例請求

GET /api/folders/nErXDvCkzzh HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk

回應範例

HTTP/1.1 200
Content-Type: application/json

{
  "id":1,
  "uid": "nErXDvCkzz",
  "title": "Department ABC",
  "url": "/dashboards/f/nErXDvCkzz/department-abc",
  "hasAcl": false,
  "canSave": true,
  "canEdit": true,
  "canAdmin": true,
  "createdBy": "admin",
  "created": "2018-01-31T17:43:12+01:00",
  "updatedBy": "admin",
  "updated": "2018-01-31T17:43:12+01:00",
  "version": 1
}

狀態碼：

• 二百 — 找到

• 401 — 未經授權

• 403 — 訪問被拒絕

• 404 — 未找到

通過 ID 獲取文件夾

GET /api/folders/id/:id

返回與給定 ID 匹配的文件夾。

範例請求

GET /api/folders/id/1 HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk

回應範例

HTTP/1.1 200
Content-Type: application/json

{
  "id":1,
  "uid": "nErXDvCkzz",
  "title": "Department ABC",
  "url": "/dashboards/f/nErXDvCkzz/department-abc",
  "hasAcl": false,
  "canSave": true,
  "canEdit": true,
  "canAdmin": true,
  "createdBy": "admin",
  "created": "2018-01-31T17:43:12+01:00",
  "updatedBy": "admin",
  "updated": "2018-01-31T17:43:12+01:00",
  "version": 1
}

狀態碼：

• 二百 — 找到

• 401 — 未經授權

• 403 — 訪問被拒絕

• 404 — 未找到

通過 uid 刪除文件夾

DELETE /api/folders/:uid

刪除與 uid 相符的資料夾，並刪除資料夾中儲存的所有儀表板。這種過度無法恢復。

範例請求

DELETE /api/folders/nErXDvCkzz HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk

回應範例

HTTP/1.1 200
Content-Type: application/json

{
  "message":"Folder deleted",
  "id": 2
}

狀態碼：

• 二百 — 已刪除

• 401 — 未經授權

• 403 — 訪問被拒絕

• 404 — 未找到