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 返回的成功代码包括：

Code	Description
200	请求成功完成
204	服务器已成功完成请求，但未在正文中返回内容。这主要用于存储数据点，因为没有必要将数据返回给调用方
301	如果 API 调用已迁移或应转发到另一台服务器，则可以使用此方法

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

Code	Description
400	API 用户通过查询字符串或内容数据提供的信息有误或丢失。这通常将在错误正文中包含有关导致问题的参数的信息。更正数据，然后重试。
404	找不到请求的端点或文件。这通常与静态文件端点有关。
405	不允许使用所要求的动词或方法。请参阅您要访问的端点的文档
406	该请求无法以指定的格式生成响应。例如，如果您要求logs endpoing 的 PNG 文件，则由于日志条目无法轻松转换为 PNG 图片，您将收到 406 响应。
408	该请求已超时。这可能是由于从底层存储系统获取数据超时或其他问题所致
413	查询返回的结果可能太大，服务器的缓冲区无法处理。如果您从 OpenTSDB 请求大量原始数据，则会发生这种情况。在这种情况下，将查询分解为较小的查询，然后分别运行
500	OpenTSDB 内部发生内部错误。确保 OpenTSDB 所依赖的所有系统都是可访问的，并检查错误列表中的问题
501	所请求的功能尚未实现。这可能与格式化程序一起出现，或者在调用依赖于插件的方法时出现
503	发生暂时的过载。检查与 OpenTSDB 交互的其他用户/应用程序，并确定是否需要减少请求或扩展系统。

Errors

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

Field Name	Data Type	Always Present	Description	Example
code	Integer	Yes	HTTP 状态码	400
message	String	Yes	有关错误原因的描述性错误消息	缺少必需的参数
details	String	Optional	有关错误的详细信息，通常是堆栈跟踪	缺失值：类型
trace	String	Optional	JAVA 堆栈跟踪，描述了生成错误的位置。可以通过tsd.http.show_stack_trace配置选项禁用此功能。 TSD 的默认值是显示堆栈跟踪。	See below

所有错误都将返回有效的 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。下表描述了动词行为和覆盖。

Verb	Description	Override
GET	用于从 OpenTSDB 检索数据。可以提供覆盖来修改内容。 注意 ：通过 GET 请求只能使用查询字符串参数；请参阅下面的 Comments。	N/A
POST	用于使用请求中的内容主体在 OpenTSDB 中更新或创建对象。将使用格式化程序来解析内容主体	method_override=post
PUT	用提供的内容替换系统中的整个对象	method_override=put
DELETE	用于从系统中删除数据	method_override=delete

如果给定的 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