文档

Grafana 文档

开发者

HTTP API

Annotations HTTP API

企业版开源

注释 API

注释保存在 Grafana 数据库（sqlite, mysql 或 postgres）中。注释可以是组织注释，通过配置注释数据源可以在任何仪表盘中显示它们 - 它们通过标签过滤。或者它们可以与仪表盘上的面板绑定，然后仅在该面板上显示。

如果您运行的是 Grafana Enterprise，则对于某些端点，您需要具有特定权限。有关详细信息，请参阅基于角色的访问控制权限。

查找注释

GET /api/annotations?from=1506676478816&to=1507281278816&tags=tag1&tags=tag2&limit=100

所需权限

有关说明，请参阅简介中的注意事项。

操作	范围
`annotations:read`	`annotations:` `annotations:type:` `dashboards:` `dashboards:uid:` `folders:` `folders:uid:`

请求示例:

GET /api/annotations?from=1506676478816&to=1507281278816&tags=tag1&tags=tag2&limit=100 HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Basic YWRtaW46YWRtaW4=

查询参数

from: epoch datetime in milliseconds. 可选。
to: epoch datetime in milliseconds. 可选。
limit: 数字。可选 - 默认值为 100。返回结果的最大限制。
alertId: 数字。可选。查找指定警报的注释。
dashboardId: 数字。可选。查找范围限定到特定仪表盘的注释
dashboardUID: 字符串。可选。查找范围限定到特定仪表盘的注释，如果 dashboardUID 存在，dashboardId 将被忽略。
panelId: 数字。可选。查找范围限定到特定面板的注释
userId: 数字。可选。查找特定用户创建的注释
type: 字符串。可选。alert|annotation 返回警报或用户创建的注释
tags: 字符串。可选。使用此参数过滤组织注释。组织注释是来自注释数据源的注释，未特定连接到仪表盘或面板。要使用多个标签进行“AND”过滤，请多次指定 tags 参数，例如 tags=tag1&tags=tag2。

响应示例:

HTTP/1.1 200
Content-Type: application/json
[
    {
        "id": 1124,
        "alertId": 0,
        "dashboardId": 468,
        "dashboardUID": "uGlb_lG7z",
        "panelId": 2,
        "userId": 1,
        "userName": "",
        "newState": "",
        "prevState": "",
        "time": 1507266395000,
        "timeEnd": 1507266395000,
        "text": "test",
        "metric": "",
        "tags": [
            "tag1",
            "tag2"
        ],
        "data": {}
    },
    {
        "id": 1123,
        "alertId": 0,
        "dashboardId": 468,
        "dashboardUID": "jcIIG-07z",
        "panelId": 2,
        "userId": 1,
        "userName": "",
        "newState": "",
        "prevState": "",
        "time": 1507265111000,
        "text": "test",
        "metric": "",
        "tags": [
            "tag1",
            "tag2"
        ],
        "data": {}
    }
]

从 Grafana v6.4 开始，区域注释现在作为一个包含 timeEnd 属性的实体返回。

创建注释

在 Grafana 数据库中创建注释。dashboardId 和 panelId 字段是可选的。如果未指定，则创建组织注释，可以在任何添加 Grafana 注释数据源的仪表盘中查询。创建区域注释时，请包含 timeEnd 属性。

time 和 timeEnd 的格式应为毫秒分辨率的 epoch 数字。

POST /api/annotations

所需权限

有关说明，请参阅简介中的注意事项。

操作	范围
`annotations:create`	`annotations:` `annotations:type:` `dashboards:` `dashboards:uid:` `folders:` `folders:uid:`

所需的 JSON 请求体字段

text: 注释的描述。

请求示例:

POST /api/annotations HTTP/1.1
Accept: application/json
Content-Type: application/json

{
  "dashboardUID":"jcIIG-07z",
  "panelId":1,
  "time":1507037197339,
  "timeEnd":1507180805056,
  "tags":["tag1","tag2"],
  "text":"Annotation Description"
}

响应示例:

HTTP/1.1 200
Content-Type: application/json

{
    "message":"Annotation added",
    "id": 1,
}

此 HTTP 请求的响应在 v6.4 之前的版本中略有不同。在之前的版本中，如果您创建区域，还会获得 endId。但在 v6.4 中，区域由一个包含 time 和 timeEnd 属性的单一事件表示。

以 Graphite 格式创建注释

使用 Graphite 兼容的事件格式创建注释。when 和 data 字段是可选的。如果未指定 when，则当前时间将用作注释的时间戳。tags 字段也可以采用 Graphite 0.10.0 之前的格式（包含多个标签用空格分隔的字符串）。

POST /api/annotations/graphite

所需权限

有关说明，请参阅简介中的注意事项。

操作	范围
`annotations:create`	`annotations:type:organization`

请求示例:

POST /api/annotations/graphite HTTP/1.1
Accept: application/json
Content-Type: application/json

{
  "what": "Event - deploy",
  "tags": ["deploy", "production"],
  "when": 1467844481,
  "data": "deploy of main branch happened at Wed Jul 6 22:34:41 UTC 2016"
}

响应示例:

HTTP/1.1 200
Content-Type: application/json

{
    "message":"Graphite annotation added",
    "id": 1
}

更新注释

PUT /api/annotations/:id

更新与指定 id 匹配的注释的所有属性。要仅更新某些属性，请考虑使用部分更新注释操作。

所需权限

有关说明，请参阅简介中的注意事项。

操作	范围
`annotations:write`	`annotations:` `annotations:type:` `dashboards:` `dashboards:uid:` `folders:` `folders:uid:`

请求示例:

PUT /api/annotations/1141 HTTP/1.1
Accept: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
Content-Type: application/json

{
  "time":1507037197339,
  "timeEnd":1507180805056,
  "text":"Annotation Description",
  "tags":["tag3","tag4","tag5"]
}

响应示例:

HTTP/1.1 200
Content-Type: application/json

{
    "message":"Annotation updated"
}

部分更新注释

PATCH /api/annotations/:id

更新与指定 id 匹配的注释的一个或多个属性。

此操作目前支持更新 text, tags, time 和 timeEnd 属性。

所需权限

有关说明，请参阅简介中的注意事项。

操作	范围
`annotations:write`	`annotations:` `annotations:type:` `dashboards:` `dashboards:uid:` `folders:` `folders:uid:`

请求示例:

PATCH /api/annotations/1145 HTTP/1.1
Accept: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
Content-Type: application/json

{
  "text":"New Annotation Description",
  "tags":["tag6","tag7","tag8"]
}

响应示例:

HTTP/1.1 200
Content-Type: application/json

{
    "message":"Annotation patched"
}

按 Id 删除注释

DELETE /api/annotations/:id

删除与指定 id 匹配的注释。

所需权限

有关说明，请参阅简介中的注意事项。

操作	范围
`annotations:delete`	`annotations:` `annotations:type:` `dashboards:` `dashboards:uid:` `folders:` `folders:uid:`

请求示例:

DELETE /api/annotations/1 HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk

响应示例:

HTTP/1.1 200
Content-Type: application/json

{
    "message":"Annotation deleted"
}

查找注释标签

GET /api/annotations/tags

查找注释中创建的所有事件标签。

所需权限

有关说明，请参阅简介中的注意事项。

操作	范围
`annotations:read`	不适用

请求示例:

GET /api/annotations/tags?tag=out HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Basic YWRtaW46YWRtaW4=

查询参数

tag: 可选。用于过滤标签的字符串。
limit: 可选。数字，默认值为 100。返回结果的最大限制。

响应示例:

HTTP/1.1 200
Content-Type: application/json

{
    "result": {
        "tags": [
            {
                "tag": "outage",
                "count": 1
            }
        ]
    }
}