文档

Grafana 文档

开发者

HTTP API

库元素 HTTP API

Enterprise Open source

库元素 API

Identifier (id) 与 Unique identifier (uid)

库元素的标识符（ID）是按 Grafana 安装自动递增的数字值，在每个安装中是唯一的。

库元素的唯一标识符（UID）用于在多个 Grafana 安装之间唯一标识库元素。除非您在创建库元素时指定，否则 UID 会自动生成。UID 为访问库元素以及在多个 Grafana 安装之间同步库元素提供了统一的 URL。

UID 的最大长度为 40 个字符。

获取所有库元素

GET /api/library-elements

返回经过身份验证的用户有权限查看的所有库元素的列表。使用 perPage 查询参数控制返回的库元素的最大数量；默认限制为 100。您还可以使用 page 查询参数来获取除第一页之外的任何页面中的库元素。

查询参数

searchString：搜索名称或描述的一部分。
kind：要搜索的元素的种类。库面板使用 1，库变量使用 2。
sortDirection：元素的排序顺序。使用 alpha-asc 表示升序，使用 alpha-desc 表示降序。
typeFilter：一个逗号分隔的类型列表，用于过滤元素。
excludeUid：要从搜索结果中排除的元素 UID。
folderFilter：一个逗号分隔的文件夹 ID 列表，用于过滤元素。
perPage：每页的结果数量；默认值为 100。
page：记录集的页码，假设一次只返回 perPage 条记录。页码从 1 开始。

示例请求:

GET /api/library-elements?perPage=10 HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk

示例响应:

HTTP/1.1 200
Content-Type: application/json

{
  "result": {
     "totalCount": 15,
     "page": 1,
     "perPage": 10
     "elements": [
        {
            "id": 25,
            "orgId": 1,
            "folderId": 0,
            "uid": "V--OrYHnz",
            "name": "API docs Example",
            "kind": 1,
            "type": "text",
            "description": "",
            "model": {...},
            "version": 1,
            "meta": {
                "folderName": "General",
                "folderUid": "",
                "connectedDashboards": 1,
                "created": "2021-09-27T09:56:17+02:00",
                "updated": "2021-09-27T09:56:17+02:00",
                "createdBy": {
                    "id": 1,
                    "name": "admin",
                    "avatarUrl": "/avatar/46d229b033af06a191ff2267bca9ae56"
                },
                "updatedBy": {
                    "id": 1,
                    "name": "admin",
                    "avatarUrl": "/avatar/46d229b033af06a191ff2267bca9ae56"
                }
            }
        },
        {...}
        {...}
     ],
  }
}

状态码

200：已找到
401：未授权

按 uid 获取库元素

GET /api/library-elements/:uid

返回具有给定 UID 的库元素。

示例请求:

GET /api/library-elements/V--OrYHnz HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk

示例响应:

HTTP/1.1 200
Content-Type: application/json

{
    "result": {
      "id": 25,
      "orgId": 1,
      "folderId": 0,
      "uid": "V--OrYHnz",
      "name": "API docs Example",
      "kind": 1,
      "type": "text",
      "description": "",
      "model": {...},
      "version": 1,
      "meta": {
          "folderName": "General",
          "folderUid": "",
          "connectedDashboards": 1,
          "created": "2021-09-27T09:56:17+02:00",
          "updated": "2021-09-27T09:56:17+02:00",
          "createdBy": {
              "id": 1,
              "name": "admin",
              "avatarUrl": "/avatar/46d229b033af06a191ff2267bca9ae56"
          },
          "updatedBy": {
              "id": 1,
              "name": "admin",
              "avatarUrl": "/avatar/46d229b033af06a191ff2267bca9ae56"
          }
      }
   }
}

状态码

200：已找到
401：未授权
404：未找到库元素

按名称获取库元素

GET /api/library-elements/name/:name

返回具有给定名称的库元素

示例请求:

GET /api/library-elements/name/API docs Example HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk

示例响应:

HTTP/1.1 200
Content-Type: application/json

{
    "result": [
        {
            "id": 25,
            "orgId": 1,
            "folderId": 0,
            "uid": "V--OrYHnz",
            "name": "API docs Example",
            "kind": 1,
            "type": "text",
            "description": "",
            "model": {...},
            "version": 1,
            "meta": {
                "folderName": "General",
                "folderUid": "",
                "connectedDashboards": 1,
                "created": "2021-09-27T09:56:17+02:00",
                "updated": "2021-09-27T09:56:17+02:00",
                "createdBy": {
                    "id": 1,
                    "name": "admin",
                    "avatarUrl": "/avatar/46d229b033af06a191ff2267bca9ae56"
                },
                "updatedBy": {
                    "id": 1,
                    "name": "admin",
                    "avatarUrl": "/avatar/46d229b033af06a191ff2267bca9ae56"
                }
            }
        }
    ]
}

状态码

200：已找到
401：未授权
404：未找到库元素

获取库元素连接

GET /api/library-elements/:uid/connections

根据指定的 UID 返回库元素的连接列表。

示例请求:

GET /api/library-elements/V--OrYHnz/connections HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk

示例响应:

HTTP/1.1 200
Content-Type: application/json

{
    "result": [
        {
            "id": 148,
            "kind": 1,
            "elementId": 25,
            "connectionId": 527,
            "connectionUid": "dHEquNzGz",
            "created": "2021-09-27T10:00:07+02:00",
            "createdBy": {
                "id": 1,
                "name": "admin",
                "avatarUrl": "/avatar/46d229b033af06a191ff2267bca9ae56"
            }
        }
    ]
}

状态码

200：已找到
401：未授权
404：未找到库元素

创建库元素

POST /api/library-elements

创建一个新的库元素。

JSON Body schema

folderId：存储库元素的文件夹 ID。自 Grafana v9 起已弃用。
folderUid：可选，存储库元素的文件夹 UID，在根级别时为空字符串。
name：可选，库元素的名称。
model：库元素的 JSON 模型。
kind：要创建的元素的种类，库面板使用 1，库变量使用 2。
uid：可选，唯一标识符。

示例请求:

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

{
  "uid": "nErXDvCkzz",
  "folderUid": "",
  "name": "Example library panel",
  "model": {...},
  "kind": 1
}

示例响应:

HTTP/1.1 200
Content-Type: application/json

{
    "result": {
        "id": 28,
        "orgId": 1,
        "folderId": 0,
        "folderUid": "",
        "uid": "nErXDvCkzz",
        "name": "Example library panel",
        "kind": 1,
        "type": "",
        "description": "",
        "model": {...},
        "version": 1,
        "meta": {
            "folderName": "General",
            "folderUid": "",
            "connectedDashboards": 0,
            "created": "2021-09-30T09:14:22.378307+02:00",
            "updated": "2021-09-30T09:14:22.378307+02:00",
            "createdBy": {
                "id": 1,
                "name": "admin",
                "avatarUrl": "/avatar/46d229b033af06a191ff2267bca9ae56"
            },
            "updatedBy": {
                "id": 1,
                "name": "admin",
                "avatarUrl": "/avatar/46d229b033af06a191ff2267bca9ae56"
            }
        }
    }
}

状态码

200：已创建
400：错误（例如，名称或 UID 已存在、无效 JSON、字段缺失或无效等）。
401：未授权
403：访问被拒绝

更新库元素

PATCH /api/library-elements/:uid

更新由 uid 标识的现有库元素。

JSON Body schema

folderId：存储库元素的文件夹 ID。自 Grafana v9 起已弃用。
folderUid：存储库元素的文件夹 UID，在根级别时为空字符串。
name：库元素的名称。
model：库元素的 JSON 模型。
kind：要创建的元素的种类。库面板使用 1，库变量使用 2。
version：您正在更新的库元素的版本。
uid：可选，唯一标识符。

示例请求:

PATCH /api/library-elements/nErXDvCkzz HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk

{
  "name": "Renamed library panel",
  "kind": 1,
  "version": 1
}

示例响应:

HTTP/1.1 200
Content-Type: application/json

{
    "result": {
        "id": 28,
        "orgId": 1,
        "folderId": 0,
        "folderUid": "",
        "uid": "nErXDvCkzz",
        "name": "Renamed library panel",
        "kind": 1,
        "type": "",
        "description": "",
        "model": {
            "description": "",
            "type": ""
        },
        "version": 2,
        "meta": {
            "folderName": "General",
            "folderUid": "",
            "connectedDashboards": 0,
            "created": "2021-09-30T09:14:22+02:00",
            "updated": "2021-09-30T09:25:57.697214+02:00",
            "createdBy": {
                "id": 1,
                "name": "admin",
                "avatarUrl": "/avatar/46d229b033af06a191ff2267bca9ae56"
            },
            "updatedBy": {
                "id": 1,
                "name": "admin",
                "avatarUrl": "/avatar/46d229b033af06a191ff2267bca9ae56"
            }
        }
    }
}

状态码

200：已更新
400：错误（例如，名称或 UID 已存在、无效 JSON、字段缺失或无效等）。
401：未授权
403：访问被拒绝
404：未找到库元素
412：版本不匹配

删除库元素

DELETE /api/library-elements/:uid

删除由 UID 指定的现有库元素。此操作不可撤销。

注意
您不能删除已连接的库元素。此操作不可撤销。

示例请求:

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

示例响应:

HTTP/1.1 200
Content-Type: application/json

{
    "message": "Library element deleted",
    "id": 28
}

状态码

200：已删除
401：未授权
400：错误请求
403：访问被拒绝
404：未找到库元素

此页面是否有帮助？

在 GitHub 中提出修改建议

创建 GitHub issue

发送邮件至 docs@grafana.com

帮助与支持

社区

库元素 API

Identifier (id) 与 Unique identifier (uid)

获取所有库元素

按 uid 获取库元素

按名称获取库元素

获取库元素连接

创建库元素

更新库元素

删除库元素

此页面是否有帮助？

Grafana Labs 的相关资源