本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

# 註釋 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** — （選用） Epoch 日期時間，以毫秒為單位。
+ **to**— （選用） Epoch 日期時間，以毫秒為單位。
+ **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`應為毫秒解析度的 epoch 數字。

**範例請求**

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

## 建立圖形格式的註釋
<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"
}
```