HTTP API

OpenTSDB 提供了一个基于 HTTP 的应用程序编程接口，以实现与外部系统的集成。几乎所有 OpenTSDB 功能都可以通过 API 访问，例如查询时间序列数据，Management 元数据和存储数据点。在研究各个端点之前，请阅读整页以获取有关标准 API 行为的重要信息。

Overview

HTTP API 本质上是 RESTful 的，但是由于并非所有 Client 端都可以遵守严格的 REST 协议，因此可以通过各种替代方式提供替代访问。尽管可以通过请求访问可插拔的formatters来发送或接收不同格式的数据，但是默认的数据交换是通过 JSON 进行的。标准的 HTTP 响应代码用于所有返回的结果，并且错误将以正确的格式作为内容返回。

1.X 至 2.x 版本

OpenTSDB 1.x 具有简单的 HTTP API，该 API 提供对常见行为的访问，例如查询数据，自动完成查询和静态文件请求。 OpenTSDB 2.0 引入了一个新的，正式的 API，如此处所述。尽管大多数调用已被弃用，但仍可以访问 1.0 API，并且在版本 3 中可以将其删除。所有 2.0 API 调用均以/api/开始。

Serializers

2 .0 引入了可插入的序列化器，该序列化器可用于解析用户 Importing 并以 XML 或 JSON 等不同格式返回结果。序列化程序仅适用于 2.0 API 调用，所有 1.0 的行为均与以前相同。有关序列化器和支持的选项的详细信息，请阅读HTTP Serializers

除非被查询字符串或Content-TypeHeaders 覆盖，否则所有 API 调用均使用默认的 JSON 序列化程序。覆盖：

• 查询字符串 -提供诸如serializer=<serializer_name>之类的参数，其中<serializer_name>是串行器的硬编码名称，如/api/serializers serializer输出字段中所示。

• Content Type -如果未提供查询字符串，则 TSD 将解析 HTTP 请求中的Content-TypeHeaders。每个序列化器都可以提供 Content Type，如果与传入请求匹配，则将使用适当的序列化器。如果未找到 Map 到 Content Type 的序列化程序，则将使用默认的序列化程序。

• 默认 -如果未提供查询字符串参数，或者缺少 Content Type 或 Content Type 不匹配，则将使用默认的 JSON 序列化器。

API 文档将使用 JSON 序列化程序显示请求和响应。有关序列化程序更改行为的方式，请参见插件文档。

Authentication/Permissions

到目前为止，OpenTSDB 缺少身份验证和访问控制系统。因此，访问 API 时不需要身份验证。如果您希望限制对 OpenTSDB 的访问，请使用网络 ACL 或防火墙来阻止访问。我们不建议在具有公共 IP 地址的计算机上运行 OpenTSDB。

Response Codes

每个请求都将返回标准的 HTTP 响应代码。大多数响应都将包含内容，尤其是错误代码，其中将包含正文中关于错误原因的详细信息。从 API 返回的成功代码包括：

常见的错误响应代码包括：

Errors

如果发生错误，则 API 将返回一个响应，其中包含根据所请求的响应类型格式化的错误对象。错误对象字段包括：

所有错误都将返回有效的 HTTP 状态错误代码和带有错误详细信息的内容主体。默认格式化程序以application/jsonContent Type 将错误消息作为 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"
    }
}

请注意，堆栈跟踪被截断。另外，跟踪将包括系统特定的行尾(在这种情况下，对于 Windows 为\r\n)。如果为用户显示或写入日志，请确保用新的行和标签替换\n或\r\n和\r字符。

Verbs

HTTP API 本质上是 RESTful 的，这意味着它通过使用 HTTP 谓词确定操作过程来尽最大努力遵守 REST 协议。例如，一个GET请求仅应返回数据，一个PUT或POST应该修改数据，而DELETE应该删除它。文档将反映哪些动词可以在端点上使用以及它们可以做什么。

但是，在某些情况下，诸如DELETE和PUT之类的动词被防火墙，代理阻止或未在 Client 端中实现。此外，大多数开发人员习惯于单独使用GET和POST。因此，尽管 OpenTSDB API 支持扩展动词，但通过添加查询字符串参数method_override，大多数请求仅用GET即可执行。此参数允许 Client 端将大多数 API 调用的数据作为查询字符串值而不是正文内容传递。例如，您可以通过发出带有查询字符串/api/annotation?start_time=1369141261&tsuid=010101&method_override=delete的GET来删除 Comments。下表描述了动词行为和覆盖。

如果给定的 API 调用不支持该方法，则 TSD 将返回 405 错误。

API Versioning

OpenTSDB 2.0 的 API 调用版本已版本化，因此用户可以以严格的向后兼容性进行升级。要访问特定的 API 版本，您可以制作一个诸如/api/v<version>/<endpoint>之类的 URL，例如/api/v2/suggest。这将访问suggest端点的版本 2.对于 OpenTSDB 2.0.0，版本控制从 1 开始。请求不存在的版本将导致调用最新版本。另外，如果您未提供显式版本(例如/api/suggest)，则将使用最新版本。

查询字串与。身体内容

大多数 API 端点都支持查询字符串参数，尤其是那些从系统中获取数据的参数。但是，由于编码某些字符(尤其是 Unicode)的复杂性，所有端点还支持使用格式化程序通过 POST 内容进行访问。默认格式为 JSON，因此 Client 端可以使用自己喜欢的方式生成 JSON 对象，并通过POST请求将其发送到 OpenTSDB API。与查询字符串相比，POST请求通常在提供的字段和完全 Unicode 支持方面提供更大的灵 Active。

Compressed Requests

API 可以接受已压缩的正文内容。确保将Content-EncodingHeaders 设置为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 为跨域资源共享(CORS)请求提供了简单的预检支持。要启用 CORS，您必须在tsd.http.request.cors_domains配置设置中提供通配符*或逗号分隔的特定域列表，然后重新启动 OpenTSDB。例如，您可以提供*的值，也可以提供诸如beeblebrox.com,www.beeblebrox.com,aurtherdent.com之类的域的列表。域列表不区分大小写，但必须完全匹配 Client 端发送的任何值。

当GET，POST，PUT或DELETE请求到达且OriginHeaders 设置为有效域名时，服务器会将域与配置的列表进行比较。如果域出现在列表中或设置了通配符，则服务器将在处理完成后将Access-Control-Allow-Origin和Access-Control-Allow-MethodsHeaders 添加到响应中。允许的方法将始终为GET, POST, PUT, DELETE。每个端点不会改变。如果请求是 CORS 预检，即使用OPTION方法，则响应将相同，但内容主体为空，状态码为 200.

如果Origin域与配置列表中的域不匹配，则响应将是 200 状态代码和内容正文的错误(请参见上文)，表明访问被拒绝，无论请求是预检还是常规请求。该请求将不再处理。

默认情况下，tsd.http.request.cors_domains列表为空，并且 CORS 被禁用。通过请求时，不会附加 CORS 特定的 Headers。如果Options请求到达，它将收到 405 错误消息。

Documentation

下面列出的每个端点的文档将包含有关如何使用该端点的详细信息。 Eahc 页面将包含端点的描述，支持的动词，请求中的字段，response 中的字段以及示例。

请求参数是您可以随请求传递的字段名称的列表。每个表具有以下信息：

• 名称-字段名称

• 数据类型-您需要提供的数据类型。例如。 String应该是文本，Integer必须是整数(正数或负数)，Float应该是十进制数。数据类型也可以是复杂的对象，例如值或对象的数组或 Map。如果在此列中看到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 -将 将 导致对存储在系统中的数据进行更新的字段

• 示例-参数值的示例

Deprecated API

Read 不推荐使用的 HTTP API

API Endpoints

• /s

• /api/aggregators

• /api/annotation

• /api/config

• /api/dropcaches

• /api/put

• /api/rollup

• /api/histogram

• /api/query

• /api/search

• /api/serializers

• /api/stats

• /api/suggest

• /api/tree

• /api/uid

• /api/version