/api/annotation

Эти конечные точки предоставляют средство добавления, редактирования или удаления аннотаций, хранящихся в бэкенде OpenTSDB. Аннотации — это очень простые объекты, используемые для записи заметки об произвольном событии в определенный момент времени, при необходимости связанные с временным рядом. Аннотации не предназначены для использования в качестве системы отслеживания или событий, а скорее они полезны для предоставления ссылок на такие системы путем отображения уведомления на графиках или с помощью вызовов API.

При создании, изменении или удалении аннотаций все изменения будут переданы в плагин поиска, если он настроен.

Конечные точки API аннотаций

/api/annotation/bulk

По умолчанию конечная точка /annotation обрабатывает одну аннотацию за раз. Конечная точка /annotation/bulk позволяет добавлять или обновлять несколько аннотаций одновременно.

Глаголы

GET - Получить одну аннотацию
POST - Создать или изменить аннотацию
PUT - Создать или заменить аннотацию
DELETE - Удалить аннотацию

Запросы

Все аннотации идентифицируются по полю startTime и, по желанию, по полю tsuid. Каждая заметка может быть глобальной, то есть связана со всеми временными рядами, или локальной, то есть связанной с определенным tsuid. Если tsuid не указан или имеет пустое значение, аннотация считается глобальной заметкой.

Имя	Тип данных	Обязательно	Описание	По умолчанию	QS	Чтение/Запись	Пример
startTime	Целое число	Обязательно	Маркер временной метки Unix, в секундах, обозначающий время, когда событие аннотации должно быть записано		start_time	Чтение/Запись	1369141261
endTime	Целое число	Необязательно	Необязательное конечное время события, если оно завершено или разрешено	0	end_time	Чтение/Запись	1369141262
tsuid	Строка	Необязательно	TSUID, если аннотация связана с временным рядом. Может быть null или пустым, если заметка была для глобального события		tsuid	Чтение/Запись	000001000001000001
description	Строка	Необязательно	Краткое описание события. Поскольку это может отображаться на графиках GnuPlot, описание должно быть очень коротким, в идеале менее 25 символов.		description	Чтение/Запись	Отключение сети
notes	Строка	Необязательно	Подробные заметки о событии		notes	Чтение/Запись	Вышел из строя и был заменён коммутатор #5
custom	Карта	Необязательно	Ключевое/знаковое отображение для хранения пользовательских полей и значений	null		Чтение/Запись	См. ниже

Примечание

Пользовательские поля не могут быть переданы через строку запроса. Вы должны использовать глаголы POST или PUT.

Предупреждение

Если ваш запрос использует PUT, любые поля, которые вы не предоставите в запросе, будут перезаписаны их значениями по умолчанию. Например, поле description будет установлено в пустую строку, а поле custom будет сброшено до null.

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

http://localhost:4242/api/annotation?start_time=1369141261&tsuid=000001000001000001

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

{
  "startTime":"1369141261",
  "tsuid":"000001000001000001",
  "description": "Testing Annotations",
  "notes": "These would be details about the event, the description is just a summary",
  "custom": {
    "owner": "jdoe",
    "dept": "ops"
  }
}

Ответ

Успешный ответ на запрос GET, POST или PUT вернет полный объект с запрошенными изменениями. Успешные вызовы DELETE вернут код состояния 204 и пустое содержимое тела. При изменении данных, если изменений не было, т.е. вызов не предоставил данных для сохранения, ответом будет 304 без содержимого тела. Если запрошенная аннотация не существовала в системе, будет возвращён 404 с сообщением об ошибке. Если были предоставлены неверные данные, будет возвращена ошибка 400.

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

{
  "tsuid": "000001000001000001",
  "description": "Testing Annotations",
  "notes": "These would be details about the event, the description is just a summary",
  "custom": {
    "owner": "jdoe",
    "dept": "ops"
  },
  "endTime": 0,
  "startTime": 1369141261
}

© 2010–2016 The OpenTSDB Authors
Licensed under the GNU LGPLv2.1+ and GPLv3+ licenses.
http://opentsdb.net/docs/build/html/api_http/annotation/index.html