本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。
# 文件夹 API
使用文件夹 API 在 Amazon Managed Grafana 工作区中处理文件夹。
文件夹的标识符（id）是一个自动递增的数值，并且对于每个工作区是唯一的。文件夹的唯一标识符（uid）可用于在多个工作区之间唯一地标识文件夹。如果您在创建文件夹时未提供 uid，则会自动生成一个。uid 允许在访问文件夹和在多个 Amazon Managed Grafana URLs 工作空间之间同步文件夹时保持一致。使用 uid 意味着更改文件夹的标题不会破坏指向该文件夹的任何已添加书签的链接。
Uid 最多可包含 40 个字符。
文件夹不能嵌套。
**注意**
要对 Amazon Managed Grafana 工作区使用 Grafana API，您必须拥有有效的 Grafana API 令牌。您可以将其包含在 API 请求的 `Authorization` 字段中。有关如何创建令牌对 API 调用进行身份验证的信息，请参阅 [使用令牌进行身份验证](authenticating-grafana-apis.md)。
`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**：可选的唯一标识符。如果为空，则生成一个新的 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
}
```
JSON 正文架构：
+ **uid**：更改唯一标识符（如果提供）。
+ **标题**：文件夹的标题。
+ **版本**：提供当前版本以便能够覆盖文件夹。如果为 `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**：未找到