HTTP API

OpenTSDB предоставляет HTTP-базированный интерфейс прикладного программирования для интеграции с внешними системами. Практически все функции OpenTSDB доступны через API, такие как запросы данных временных рядов, управление метаданными и сохранение точек данных. Пожалуйста, прочитайте всю эту страницу для важной информации о стандартном поведении API перед изучением отдельных конечных точек.

Обзор

HTTP API имеет RESTful характер, но предоставляет альтернативный доступ через различные переопределения, поскольку не все клиенты могут придерживаться строгого протокола REST. По умолчанию обмен данными происходит через JSON, хотя через запрос можно получить доступ к подключаемым formatters для отправки или получения данных в разных форматах. Стандартные HTTP-коды ответов используются для всех возвращаемых результатов, а ошибки возвращаются как содержимое с использованием правильного формата.

Версии 1.X до 2.x

OpenTSDB 1.x имел простой HTTP API, который предоставлял доступ к общему поведению, такому как запросы данных, автозаполнение запросов и запросы статических файлов. OpenTSDB 2.0 представляет новый формализованный API, как документировано здесь. API 1.0 все еще доступен, хотя большинство вызовов устарели и могут быть удалены в версии 3. Все вызовы API 2.0 начинаются с /api/.

Сериализаторы

2.0 вводит подключаемые сериализаторы, которые позволяют парсить пользовательский ввод и возвращать результаты в различных форматах, таких как XML или JSON. Сериализаторы применяются только к вызовам API 2.0, все вызовы 1.0 ведут себя так же, как и раньше. Для получения подробной информации о сериализаторах и поддерживаемых вариантах, пожалуйста, обратитесь к HTTP Serializers

Все вызовы API используют сериализатор JSON по умолчанию, если не указано иное в параметрах запроса или Content-Type заголовке. Для переопределения:

• Параметр запроса - Укажите параметр, например, serializer=<serializer_name> , где <serializer_name> - жестко заданное имя сериализатора, как показано в /api/serializers serializer поле вывода.

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

  Если не найдено сериализатора, соответствующего значению <serializer_name>, запрос вернет ошибку вместо дальнейшей обработки.

• Content-Type - Если параметр запроса не указан, TSD проанализирует Content-Type заголовок из HTTP-запроса. Каждый сериализатор может предоставить тип содержимого, и если он совпадает с входящим запросом, будет использован соответствующий сериализатор. Если сериализатор не найден, соответствующий типу содержимого, будет использован сериализатор по умолчанию.

• По умолчанию - Если параметр запроса не задан или тип содержимого отсутствует или не совпадает, будет использован сериализатор JSON по умолчанию.

Документация API будет отображать запросы и ответы с использованием сериализатора JSON. См. документацию плагина для получения информации о том, как сериализаторы изменяют поведение.

Аутентификация/Разрешения

На данный момент OpenTSDB не имеет системы аутентификации и управления доступом. Поэтому аутентификация не требуется при доступе к API. Если вы хотите ограничить доступ к OpenTSDB, используйте сетевые ACL или брандмауэры для блокирования доступа. Не рекомендуется запускать OpenTSDB на компьютере с общедоступным IP-адресом.

Коды ответов

Каждый запрос будет возвращен со стандартным HTTP-кодом ответа. Большинство ответов будут содержать содержимое, в частности коды ошибок, которые будут включать подробности о возникшей проблеме в теле. К успешным кодам ответов API относятся:

Общие коды ответов об ошибках включают:

Ошибки

Если произойдет ошибка, API вернет ответ с объектом ошибки, отформатированным в соответствии с запрошенным типом ответа. Поля объекта ошибки включают:

Все ошибки будут возвращены с допустимым HTTP-кодом ошибки и телом содержимого с подробными сведениями об ошибке. По умолчанию форматер возвращает сообщения об ошибках в формате JSON с типом содержимого application/json. Если был запрошен другой форматер, вывод может отличаться. См. документацию форматера для получения подробной информации.

{
  "error": {
    "code": 400,
    "message": "Missing parameter <code>type</code>",
    "trace": "net.opentsdb.tsd.BadRequestException: Missing parameter <code>type</code>\r\n\tat net.opentsdb.tsd.BadRequestException.missingParameter(BadRequestException.java:78) ~[bin/:na]\r\n\tat net.opentsdb.tsd.HttpQuery.getRequiredQueryStringParam(HttpQuery.java:250) ~[bin/:na]\r\n\tat net.opentsdb.tsd.SuggestRpc.execute(SuggestRpc.java:63) ~[bin/:na]\r\n\tat net.opentsdb.tsd.RpcHandler.handleHttpQuery(RpcHandler.java:172) [bin/:na]\r\n\tat net.opentsdb.tsd.RpcHandler.messageReceived(RpcHandler.java:120) [bin/:na]\r\n\tat org.jboss.netty.channel.SimpleChannelUpstreamHandler.handleUpstream(SimpleChannelUpstreamHandler.java:75) [netty-3.5.9.Final.jar:na]\r\n\tat org.jboss.netty.channel.DefaultChannelPipeline.sendUpstream(DefaultChannelPipeline.java:565) [netty-3.5.9.Final.jar:na]
    ....\r\n\tat java.lang.Thread.run(Unknown Source) [na:1.6.0_26]\r\n"
  }
}

Глаголы

HTTP API имеет RESTful характер, что означает, что он старается придерживаться REST-протокола, используя HTTP-глаголы для определения курса действий. Например, запрос GET должен возвращать только данные, PUT или POST должны изменять данные, а DELETE - удалять их. Документация будет отражать, какие глаголы могут быть использованы на конечной точке и что они делают.

Однако в некоторых ситуациях глаголы, такие как DELETE и PUT, блокируются брандмауэрами, прокси-серверами или не реализованы в клиентах. Кроме того, большинство разработчиков привыкли использовать GET и POST исключительно. Поэтому, хотя OpenTSDB API поддерживает расширенные глаголы, большинство запросов можно выполнить с помощью GET, добавив параметр запроса method_override. Этот параметр позволяет клиентам передавать данные для большинства вызовов API в виде значений параметров запроса вместо содержимого тела. Например, вы можете удалить аннотацию, выполнив GET с параметром запроса /api/annotation?start_time=1369141261&tsuid=010101&method_override=delete. В следующей таблице описывается поведение глаголов и переопределения.

Если метод не поддерживается для данного вызова API, TSD вернет ошибку 405.

Версии API

API-вызовы OpenTSDB 2.0 имеют версионирование, позволяющее пользователям обновлять систему с гарантированной обратной совместимостью. Для доступа к определенной версии API вы создаете URL, например /api/v<version>/<endpoint> , например /api/v2/suggest. Это даст доступ к версии 2 конечной точки suggest. Версионирование начинается с 1 для OpenTSDB 2.0.0. Запросы к несуществующей версии приведут к обращению к последней версии. Также, если вы не укажете явную версию, например /api/suggest, будет использована последняя версия.

Строка запроса против содержимого тела запроса

Большинство API-конечных точек поддерживают параметры строки запроса, особенно те, которые извлекают данные из системы. Однако из-за сложностей кодирования некоторых символов, особенно Unicode, все конечные точки также поддерживают доступ через содержимое тела POST-запроса с использованием форматеров. По умолчанию используется формат JSON, поэтому клиенты могут использовать свой любимый способ генерации объекта JSON и отправить его в API OpenTSDB через POST запрос. POST запросы обычно предоставляют большую гибкость в предлагаемых полях и полную поддержку Unicode по сравнению со строками запросов.

Сжатые запросы

API может принимать содержимое тела, которое было сжато. Убедитесь, что вы установили заголовок Content-Encoding в gzip и передали двоичные закодированные данные по сети. Это особенно полезно для отправки точек данных на /api/put конечную точку. Пример с использованием curl:

$ gzip -9c clear-32k.json > gzip-32k.json

$ file gzip-32k.json
gzip-32k.json: gzip compressed data, was "clear-32k.json", from Unix, last modified: Thu Jan 16 15:31:55 2014

$ ls -l gzip-32k.json
-rw-r--r-- 1 root root 1666 févr.  4 09:57 gzip-32k.json

$ curl -X POST --data-binary "@gzip-32k.json" --header "Content-Type: application/json" --header "Content-Encoding: gzip" http://mytsdb1:4242/api/put?details
{"errors":[],"failed":0,"success":280}

CORS

OpenTSDB предоставляет простую и предварительную поддержку Cross-Origin Resource Sharing (CORS) запросов. Для включения CORS, вы должны указать либо символ подстановки * , либо список отдельных доменов через запятую в настройке tsd.http.request.cors_domains и перезапустить OpenTSDB. Например, вы можете указать значение * или предоставить список доменов, таких как beeblebrox.com,www.beeblebrox.com,aurtherdent.com. Список доменов нечувствителен к регистру, но должен полностью соответствовать любому значению, отправляемому клиентами.

Когда GET, POST, PUT или DELETE запрос поступает с заголовком Origin , установленным на допустимое имя домена, сервер сравнивает домен с настроенным списком. Если домен появляется в списке или был установлен символ подстановки, сервер добавит заголовки Access-Control-Allow-Origin и Access-Control-Allow-Methods в ответ после завершения обработки. Разрешенные методы всегда будут GET, POST, PUT, DELETE. Они не изменяются в зависимости от конечной точки. Если запрос является предварительным CORS, т.е. используется метод OPTION, ответ будет таким же, но с пустым телом содержимого и кодом состояния 200.

Если домен Origin не совпадает ни с одним доменом в настроенном списке, ответ будет кодом состояния 200 и телом содержимого с ошибкой (см. выше), указывающей на отказ в доступе, независимо от того, был ли запрос предварительным или обычным. Запрос больше не будет обрабатываться.

По умолчанию список tsd.http.request.cors_domains пуст, и CORS отключен. Запросы проходят без добавления специальных заголовков CORS. Если приходит Options запрос, он получит сообщение об ошибке 405.

Документация

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

Параметры запроса — это список имен полей, которые можно передавать в запросе. Каждая таблица содержит следующую информацию:

• Имя — имя поля
• Тип данных — тип данных, которые нужно предоставить. Например, String должно быть текстом, Integer должно быть целым числом (положительным или отрицательным), Float должно быть десятичным числом. Тип данных также может быть сложным объектом, например, массивом или отображением значений или объектов. Если вы видите Present в этом столбце, то просто добавление параметра в строку запроса устанавливает значение в true, фактическое значение параметра игнорируется. Например, /api/put?summary фактически устанавливает summary=true. Если вы запросите /api/put?summary=false, API все равно будет рассматривать запрос как summary=true.
• Обязательно — требуется ли параметр для успешного запроса. Если параметр обязателен, вы увидите Required, в противном случае — Optional.
• Описание — подробное описание параметра, включая допустимые значения, если применимо.
• Значение по умолчанию — значение по умолчанию параметра Optional . Если данные обязательны, это поле будет пустым.
• QS — можно ли указать параметр через строку запроса, в этом поле будет Yes, в противном случае No, означая, что параметр может быть указан только в теле запроса.
• RW — описывает, может ли этот параметр привести к обновлению данных, хранящихся в OpenTSDB. Возможные значения в этом столбце:
  • пустое — это означает, что поле используется только для запросов и не обязательно представляет поле в ответе.
  • RO — поле, которое отображается в ответе, но является только для чтения. Переданное вместе с запросом значение не изменит поле вывода.
  • RW или W — поле, которое будет приводить к обновлению данных, хранящихся в системе
• Пример — пример значения параметра

Устаревший API

См. Устаревший HTTP API

API-конечные точки