文件夹 API

使用文件夹 API 处理亚马逊托管 Grafana 工作空间中的文件夹。

文件夹的标识符 (id) 是一个自动递增的数值，并且仅在每个工作空间中是唯一的。文件夹的唯一标识符 (uid) 可用于在多个工作区之间唯一标识文件夹。如果您在创建文件夹时未提供该文件夹，则会自动生成。uid 允许在访问文件夹和在多个 Amazon Managed Grafana 工作空间之间同步文件夹时使用一致的 URL。使用 uid 意味着更改文件夹的标题不会破坏该文件夹的任何已添加书签的链接。

uid 的最大长度可以为 40 个字符。

文件夹不能嵌套。

注意

要在亚马逊托管 Grafana 工作空间中使用 Grafana API，您必须拥有有效的 Grafana API 令牌。您可以将其包含在 API 请求的Authorization字段中。有关如何创建令牌来验证您的 API 调用的信息，请参阅使用令牌进行身份验证。

为 0 的 “常规” 文件夹不是文件夹 API 的一部分。id您无法使用文件夹 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。

• o@@ verwrit e — 设置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 — 未找到