Документация Grafana Документация GlaberGraph Ресурсы для разработчиков API Grafana Справочное руководство по HTTP API Grafana Устаревший HTTP API Grafana API аннотаций

API аннотаций

Аннотации сохраняются в базе данных Grafana (sqlite, mysql или postgres). Аннотации могут быть аннотациями организации, которые можно показывать на любом дашборде, настроив источник данных аннотаций — они фильтруются по меткам. Либо они могут быть привязаны к панели на дашборде и тогда показываются только на этой панели.

Требования

Если вы используете Grafana Enterprise, для некоторых конечных точек потребуются определённые права. Дополнительные сведения см. в разделе Права управления доступом на основе ролей.

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

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

Требуемые права

Пояснения см. в примечании во введении.

Пример запроса:

http Copy

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 в миллисекундах. Необязательно.
• to: дата и время в epoch в миллисекундах. Необязательно.
• limit: число. Необязательно — по умолчанию 100. Максимальный предел возвращаемых результатов.
• alertId: число. Необязательно. Находит аннотации для указанного алерта.
• dashboardId: устарел. Используйте вместо него dashboardUID.
• dashboardUID: строка. Необязательно. Находит аннотации, относящиеся к конкретному дашборду; когда указан dashboardUID, dashboardId игнорируется.
• panelId: число. Необязательно. Находит аннотации, относящиеся к конкретной панели
• userId: число. Необязательно. Находит аннотации, созданные конкретным пользователем
• type: строка. Необязательно. alert|annotation. Возвращает алерты или созданные пользователем аннотации
• tags: строка. Необязательно. Используйте это для фильтрации аннотаций организации. Аннотации организации — это аннотации из источника данных аннотаций, не привязанные конкретно к дашборду или панели. Чтобы выполнить фильтрацию по принципу «И» с несколькими метками, укажите параметр tags несколько раз, например tags=tag1&tags=tag2.

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

http Copy

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

Начиная с Grafana v6.4, аннотации регионов возвращаются в одной сущности, которая теперь включает свойство timeEnd.

Создание аннотации

Создаёт аннотацию в базе данных Grafana. Поля dashboardUid и panelId необязательны. Если они не указаны, создаётся аннотация организации, которую можно запросить на любом дашборде, к которому добавлен источник данных аннотаций Grafana. При создании аннотации региона указывайте свойство timeEnd.

Формат time и timeEnd должен быть числами epoch с миллисекундной точностью.

POST /api/annotations

Требуемые права

Пояснения см. в примечании во введении.

Обязательные поля тела JSON

• text: описание аннотации.

Пример запроса:

http Copy

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

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

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

http Copy

HTTP/1.1 200
Content-Type: application/json

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

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

Создание аннотации в формате Graphite

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

POST /api/annotations/graphite

Требуемые права

Пояснения см. в примечании во введении.

Пример запроса:

http Copy

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 Copy

HTTP/1.1 200
Content-Type: application/json

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

Обновление аннотации

PUT /api/annotations/:id

Обновляет все свойства аннотации, соответствующей указанному id. Чтобы обновить только определённое свойство, рассмотрите операцию Частичное обновление аннотации.

Требуемые права

Пояснения см. в примечании во введении.

Пример запроса:

http Copy

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

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

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

http Copy

HTTP/1.1 200
Content-Type: application/json

{
    "message":"Annotation updated"
}

Частичное обновление аннотации

PATCH /api/annotations/:id

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

В настоящее время эта операция поддерживает обновление свойств text, tags, time и timeEnd.

Требуемые права

Пояснения см. в примечании во введении.

Пример запроса:

http Copy

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

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

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

http Copy

HTTP/1.1 200
Content-Type: application/json

{
    "message":"Annotation patched"
}

Удаление аннотации по Id

DELETE /api/annotations/:id

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

Требуемые права

Пояснения см. в примечании во введении.

Пример запроса:

http Copy

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

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

http Copy

HTTP/1.1 200
Content-Type: application/json

{
    "message":"Annotation deleted"
}

Поиск меток аннотаций

GET /api/annotations/tags

Находит все метки событий, созданные в аннотациях.

Требуемые права

Пояснения см. в примечании во введении.

Пример запроса:

http Copy

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

Параметры запроса:

• tag: необязательно. Строка, которую можно использовать для фильтрации меток.
• limit: необязательно. Число, по умолчанию 100. Максимальный предел возвращаемых результатов.

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

http Copy

HTTP/1.1 200
Content-Type: application/json

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