/api/tree

Деревья представляют метаданные, используемые для организации временных рядов в иерархической структуре для просмотра, подобно типичной файловой системе. Ряд конечных точек в корне /tree позволяют работать с различными данными, связанными с деревом:

Конечные точки API дерева

Конечная точка /tree позволяет создавать или изменять определение дерева. Определения деревьев включают конфигурацию и метаданные, доступные через эту конечную точку, а также набор правил, доступный через /tree/rule или /tree/rules.

Примечание

При создании дерева поле enabled будет установлено по умолчанию в значение false. После создания дерева необходимо добавить правила, а затем использовать конечную точку tree/test с несколькими TSUID, чтобы убедиться, что полученное дерево соответствует ожиданиям. После проверки результатов вы можете установить поле enabled в значение true, и новые объекты TSMeta или синхронизация дерева начнут заполнять ветви.

Глаголы

GET - Получить одно или несколько определений деревьев
POST - Изменить поля дерева
PUT - Заменить поля дерева
DELETE - Удалить результаты дерева и/или определение дерева

Запросы

Следующие поля могут быть использованы для всех запросов к конечным точкам дерева:

Имя	Тип данных	Обязательно	Описание	По умолчанию	QS	RW	Пример
treeId	Целое число	Обязательно*	Используется для извлечения или изменения конкретного дерева. *При создании нового дерева значение `tree` не должно присутствовать.		treeid	RO	1
name	Строка	Обязательно*	Краткое, описательное имя дерева. *Требуется только при создании дерева.		name	RW	Инфраструктура сети
description	Строка	Необязательно	Более подробное описание содержимого дерева		description	RW	Дерево, содержащее все сетевое оборудование
notes	Строка	Необязательно	Подробные заметки о дереве		notes	RW
strictMatch	Булево	Необязательно	Указывает, должны ли временные ряды включаться в дерево, если они не соответствуют одному или нескольким уровням правил.	false	strict_match	RW	true
enabled	Булево	Необязательно	Указывает, следует ли обрабатывать TSMeta через дерево. По умолчанию это установлено в `false`, чтобы вы могли настроить правила и протестировать некоторые объекты перед созданием ветвей.	false	enabled	RW	true
storeFailures	Булево	Необязательно	Указывает, следует ли записывать коллизии и TSUID, которые не соответствуют правилам. Это может привести к очень широким записям.	false	store_failures	RW	true
definition	Булево	Необязательно	Используется только при `DELETE` дерева. Если этот флаг установлен в true, то всё определение дерева будет удалено вместе со всеми ветвями, столкновениями и записями несоответствий.	false	definition		true

Ответ

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

Все поля Запроса будут присутствовать в ответе, а также другие:

Имя	Тип данных	Описание	Пример
rules	Карта	Карта или словарь с правилами, определенными для дерева, организованными по `level` и `order`. Если правила еще не определены, значением будет `null`	См. примеры
created	Целое число	Отметка времени Unix Epoch в секундах, когда дерево было первоначально создано.	1350425579

GET

Запрос GET к /api/tree без идентификатора дерева вернёт список всех деревьев, сконфигурированных в системе. Результаты будут включать настроенные правила для каждого дерева. Если деревья еще не настроены, список будет пустым.

Пример запроса GET для получения всех деревьев

http://localhost:4242/api/tree

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

[
  {
    "name": "Test Tree",
    "description": "My Description",
    "notes": "Details",
    "rules": {
      "0": {
        "0": {
          "type": "TAGK",
          "field": "host",
          "regex": "",
          "separator": "",
          "description": "Hostname rule",
          "notes": "",
          "level": 0,
          "order": 0,
          "treeId": 1,
          "customField": "",
          "regexGroupIdx": 0,
          "displayFormat": ""
        }
      },
      "1": {
        "0": {
          "type": "METRIC",
          "field": "",
          "regex": "",
          "separator": "",
          "description": "",
          "notes": "Metric rule",
          "level": 1,
          "order": 0,
          "treeId": 1,
          "customField": "",
          "regexGroupIdx": 0,
          "displayFormat": ""
        }
      }
    },
    "created": 1356998400,
    "treeId": 1,
    "strictMatch": false,
    "storeFailures": false,
    "enabled": true
  },
  {
    "name": "2nd Tree",
    "description": "Other Tree",
    "notes": "",
    "rules": {
      "0": {
        "0": {
          "type": "TAGK",
          "field": "host",
          "regex": "",
          "separator": "",
          "description": "",
          "notes": "",
          "level": 0,
          "order": 0,
          "treeId": 2,
          "customField": "",
          "regexGroupIdx": 0,
          "displayFormat": ""
        }
      },
      "1": {
        "0": {
          "type": "METRIC",
          "field": "",
          "regex": "",
          "separator": "",
          "description": "",
          "notes": "",
          "level": 1,
          "order": 0,
          "treeId": 2,
          "customField": "",
          "regexGroupIdx": 0,
          "displayFormat": ""
        }
      }
    },
    "created": 1368964815,
    "treeId": 2,
    "strictMatch": false,
    "storeFailures": false,
    "enabled": false
  }
]

Чтобы получить конкретное дерево, укажите значение ``treeId'`. Ответ будет содержать объект дерева, если он найден. Если запрошенного дерева не существует, будет возвращена ошибка 404.

Пример запроса GET для получения одного дерева

http://localhost:4242/api/treeId?tree=1

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

{
  "name": "2nd Tree",
  "description": "Other Tree",
  "notes": "",
  "rules": {
    "0": {
      "0": {
        "type": "TAGK",
        "field": "host",
        "regex": "",
        "separator": "",
        "description": "",
        "notes": "",
        "level": 0,
        "order": 0,
        "treeId": 2,
        "customField": "",
        "regexGroupIdx": 0,
        "displayFormat": ""
      }
    },
    "1": {
      "0": {
        "type": "METRIC",
        "field": "",
        "regex": "",
        "separator": "",
        "description": "",
        "notes": "",
        "level": 1,
        "order": 0,
        "treeId": 2,
        "customField": "",
        "regexGroupIdx": 0,
        "displayFormat": ""
      }
    }
  },
  "created": 1368964815,
  "treeId": 2,
  "strictMatch": false,
  "storeFailures": false,
  "enabled": false
}

POST/PUT

Используя методы POST или PUT, вы можете создать новое дерево или изменить большинство полей существующего дерева. Для новых деревьев требуется значение name, а для существующих — ID дерева и любые поля, которые требуют изменения. Успешный запрос вернёт изменённый объект дерева.

Примечание

У нового дерева не будет правил. Следующий вызов, вероятно, должен быть к /tree/rule или /tree/rules.

Пример запроса POST для создания

http://localhost:4242/api/tree?name=Network%20Tree&method_override=post

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

{
  "name": "Network",
  "description": "",
  "notes": "",
  "rules": null,
  "created": 1368964815,
  "treeId": 3,
  "strictMatch": false,
  "storeFailures": false,
  "enabled": false
}

Пример запроса POST для редактирования

http://localhost:4242/api/tree?treeId=3&description=Network%20Device%20Information&method_override=post

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

{
  "name": "Network",
  "description": "Network Device Information",
  "notes": "",
  "rules": null,
  "created": 1368964815,
  "treeId": 3,
  "strictMatch": false,
  "storeFailures": false,
  "enabled": false
}

DELETE

Использование метода DELETE удалит только столкновения, записи несоответствий и ветви для заданного дерева из хранилища. Этот конечный пункт инициирует удаление. Так как удаление может занять некоторое время, конечная точка вернёт успешный ответ 204 без данных, если удаление завершено. Если дерево не найдено, будет возвращён код 404. Если вы хотите удалить само определение дерева, вы можете указать флаг defintion в строке запроса со значением true, и дерево и определения правил будут удалены тоже.

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

Этот метод невозможно отменить. После выполнения очистка будет продолжена, пока не будет остановлен TSD.

Примечание

Перед выполнением запроса DELETE, убедитесь, что где-то на ваших данных не запущена ручная синхронизация дерева. Если она запущена, могут быть сохранены некоторые «оставшиеся» ветви или листья во время очистки. Используйте инструмент _____ CLI некоторое время после удаления для очистки оставшихся ветвей или листьев.

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

http://localhost:4242/api/tree?tree=1&method_override=delete

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