本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

# 注释 API
<a name="Grafana-API-Annotations"></a>

使用注释 API 在 Amazon Managed Grafana 工作区中创建、更新、删除和处理注释。

注释保存在工作区的 Grafana 数据库（sqlite、mysql 或 postgres）中。注释可以是全局注释，可以通过配置注释数据来源将其显示在任何控制面板上。注释按标签进行筛选。或者，它们可以绑定到控制面板上的面板，并且仅显示在该面板上。

**注意**  
要对 Amazon Managed Grafana 工作区使用 Grafana API，您必须拥有有效的 Grafana API 令牌。您可以将其包含在 API 请求的 `Authorization` 字段中。有关如何创建令牌对 API 调用进行身份验证的信息，请参阅 [使用令牌进行身份验证](authenticating-grafana-apis.md)。

## 查找注释
<a name="Grafana-API-Annotations-Find"></a>

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

**示例请求**

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

查询参数：
+ **from**：（可选）以毫秒为单位的纪元日期时间。
+ **to**：（可选）以毫秒为单位的纪元日期时间。
+ **limit**：（可选）返回的最大结果数。默认值为 100。
+ **alertid —（可选）指定警报**的 FInd注释。
+ **dashboardId**：（可选）查找范围限于指定控制面板的注释。
+ **panelId**：（可选）查找范围限于指定面板的注释。
+ **userId**：（可选）查找由指定用户创建的注释。
+ **type**：（可选）指定返回警报或用户创建的注释。有效值为 `alert` 和 `annotation`。
+ **tags**：（可选）使用该参数来筛选全局注释。全局注释是来自注释数据来源的注释，这些注释没有专门连接到控制面板或面板。要对多个标签进行 "AND" 筛选，请多次指定标签参数。例如 `tags=tag1&tags=tag2`。这些是 Grafana 标签，而不是标签。 AWS 

**响应示例**

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

## 创建注释
<a name="Grafana-API-Annotations-create"></a>

```
POST /api/annotations
```

在工作区的 Grafana 数据库中创建注解。`dashboardId` 和 `panelId` 字段是可选的。如果未指定这两个字段，则会创建一个全局注释，并且可以在任何添加了 Grafana 注释数据来源的控制面板中进行查询。创建区域注释时，请务必包含 `timeEnd` 属性。

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

**示例请求**

```
POST /api/annotations HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk

{
  "dashboardId":468,
  "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,
}
```

## 以 graphite 格式创建注释
<a name="Grafana-API-Annotations-create-graphite"></a>

```
POST /api/annotations/graphite
```

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

**示例请求**

```
POST /api/annotations/graphite HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk

{
  "what": "Event - deploy",
  "tags": ["deploy", "production"],
  "when": 1467844481,
  "data": "deploy of master 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
}
```

## 更新注释
<a name="Grafana-API-Annotations-update"></a>

```
PUT /api/annotations/:id
```

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

**示例请求**

```
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"
}
```

## 补丁注释
<a name="Grafana-API-Annotations-patch"></a>

```
PATCH /api/annotations/:id
```

更新与指定 id 匹配的注释的一个或多个属性。此操作目前支持更新 `text`、`tags`、`time` 和 `timeEnd` 属性。

**请求示例：**

```
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 删除注释
<a name="Grafana-API-Annotations-deteebyId"></a>

```
DELETE /api/annotations/:id
```

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

**示例请求**

```
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"
}
```