+++
title = "Аннотации HTTP API"
description = "Harvest Аннотации HTTP API"
keywords = ["harvest", "http", "documentation", "api", "annotation", "annotations", "comment"]
aliases = ["/docs/harvest/latest/http_api/annotations/"]
+++

# Аннотации ресурсов / действий

Это документация API для новой функции аннотаций Harvest, выпущенной в Harvest 4.6. Аннотации сохраняются в базе данных Harvest (sqlite, mysql или postgres). Аннотации могут быть глобальными аннотациями, которые можно отображать на любой панели мониторинга, настроив источник данных аннотаций - они фильтруются по тегам. Или же они могут быть привязаны к панели на панели мониторинга и затем отображаться только на этой панели.

## Поиск аннотаций

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

**Пример ответа:**

```http
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`: дата и время эпохи в миллисекундах. Необязательный.
- `to`: дата и время эпохи в миллисекундах. Необязательный.
- `предел`: количество. Необязательно - значение по умолчанию равно 100. Максимальное ограничение для возвращаемых результатов.
- `- `идентификатор предупреждения`: номер. Необязательный. Найдите аннотации для указанного предупреждения.
- `- `идентификатор панели мониторинга`: номер. Необязательный. Поиск аннотаций, привязанных к определенной панели мониторинга
- `- `идентификатор панели`: номер. Необязательный. Поиск аннотаций, привязанных к определенной панели
- `Идентификатор пользователя`: номер. Необязательный. Поиск аннотаций, созданных конкретным пользователем
- `тип`: строка. Необязательный. `alert`|`annotation` Возвращают предупреждения или созданные пользователем аннотации
- `теги`: строка. Необязательный. Используйте это для фильтрации глобальных аннотаций. Глобальные аннотации - это аннотации из источника данных аннотаций, которые специально не подключены к информационной панели или панели. Чтобы выполнить фильтрацию "И" с несколькими тегами, укажите параметр tags несколько раз, например `tags=tag1&tags=tag2`.
**Пример ответа**:

```http
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": {}
    }
]
```

> Начиная с версии Harvest версии 6.4 аннотации регионов теперь возвращаются в одном объекте, который теперь включает свойство timeEnd.

## Создать аннотацию

Создает аннотацию в базе данных Harvest. Поля "Панель мониторинга" и `идентификатор панели" являются необязательными.
Если они не указаны, то создается глобальная аннотация, которую можно запросить на любой панели мониторинга, добавляющей
источник данных аннотаций Harvest. При создании аннотации региона включите свойство time Endproperty. 

Формат для "времени` и `времени и` должен быть номерами эпох в миллисекундном разрешении.

`POST /api/annotations`

**Пример ответа:**

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

{
  "dashboardId":468,
  "panelId":1,
  "time":1507037197339,
  "timeEnd":1507180805056,
  "tags":["tag1","tag2"],
  "text":"Annotation Description"
}
```

**Пример ответа**:

```http
HTTP/1.1 200
Content-Type: application/json

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

> Ответ на этот HTTP-запрос немного отличается в версиях, предшествующих версии 6.4. В предыдущих версиях вы
также получали бы endId, если бы создавали регион. Но в 6.4 регионы представлены с использованием одного события со свойствами time и
time End.

## Создать аннотацию в графитовом формате

Создает аннотацию, используя формат событий, совместимый с Graphite. Поля "когда` и `данные` являются необязательными. Если "когда" не указано, то в качестве временной метки будет использоваться текущее время. Поле "теги` также может быть перед графитом `0.10.0`
формат (строка с несколькими тегами, разделенными пробелом).

`POST /api/annotations/graphite`

**Пример ответа:**

```http
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 master branch happened at Wed Jul 6 22:34:41 UTC 2016"
}
```

**Пример ответа**:

```http
HTTP/1.1 200
Content-Type: application/json

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

## Обновить аннотацию

`PUT /api/аннотации/:идентификатор`

Обновляет все свойства аннотации, соответствующей указанному идентификатору. Чтобы обновить только определенное свойство, рассмотрите возможность использования операции [Patch Annotation](#patch-annotation).
**Пример ответа:**

```http
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
HTTP/1.1 200
Content-Type: application/json

{
    "message":"Annotation updated"
}
```

## Аннотация к патчу
> Это доступно в Harvest 6.0.0-beta2 и выше.

`PATCH /api/аннотации/:идентификатор`

Обновляет одно или несколько свойств аннотации, соответствующих указанному идентификатору.

В настоящее время эта операция поддерживает обновление свойств "текст`, `теги`, `время` и "Конец времени".

**Пример ответа:**

```http
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
HTTP/1.1 200
Content-Type: application/json

{
    "message":"Annotation patched"
}
```

## Удалить Аннотацию По Идентификатору

`DELETE /api/аннотации/:идентификатор`

Удаляет аннотацию, соответствующую указанному идентификатору.

**Пример ответа:**

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

**Пример ответа**:

```http
HTTP/1.1 200
Content-Type: application/json

{
    "message":"Annotation deleted"
}
```
