本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# 資料夾 API
使用資料夾 API 來處理 Amazon Managed Grafana 工作區中的資料夾。
資料夾的識別符 (id) 是自動遞增的數值，而且每個工作區都是唯一的。資料夾的唯一識別符 (uid) 可用來唯一識別多個工作區之間的資料夾。如果您在建立資料夾時未提供，則會自動產生。uid 允許在多個 Amazon Managed Grafana 工作區之間同步資料夾時，使用一致的 URLs 來存取資料夾。使用 uid 表示變更資料夾的標題不會破壞該資料夾的任何書籤連結。
uid 的長度上限為 40 個字元。
資料夾無法巢狀化。
**注意**
若要搭配 Amazon Managed Grafana 工作區使用 Grafana API，您必須擁有有效的服務帳戶字符。您可以在 API 請求的 `Authorization` 欄位中包含此項目。
**一般**資料夾的 `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"
}
```
JSON 內文結構描述：
+ **uid** — 選用的唯一識別符。如果為 null，會產生新的 uid。
+ **title** — 資料夾的標題。
**回應範例**
```
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
}
```
JSON 內文結構描述：
+ **uid** — 如果提供，則變更唯一識別符。
+ title ****— 資料夾的標題。
+ **版本** — 提供目前版本，以便能夠覆寫資料夾。如果為 ，則不需要`overwrite=true`。
+ **覆寫** — 設定為 `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`查詢參數控制傳回的資料夾數量上限。預設為 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
}
```
狀態碼：
+ **200** — 找到
+ **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
}
```
狀態碼：
+ **200** — 找到
+ **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
}
```
狀態碼：
+ **200** — 已刪除
+ **401** — 未授權
+ **403** — 存取遭拒
+ **404** — 找不到