OpenTSDB HTTP API 概述
HTTP API
原文地址 ：http://opentsdb.net/docs/build/html/api_http/index.html
OpenTSDB 提供基于 HTTP 的应用程序编程接口，以实现与外部系统的集成。 几乎所有 OpenTSDB 功能都可以通过 API 访问，例如查询时间序列数据、管理元数据和存储数据点。 在调查各个端点之前，请阅读整个页面以获取有关标准 API 行为的重要信息。
Overview
HTTP API 本质上是 RESTful，但通过各种覆盖提供替代访问，因为并非所有客户端都可以遵守严格的 REST 协议。 默认数据交换是通过 JSON 进行的，尽管可以通过请求访问可插入的格式化程序，以发送或接收不同格式的数据。 标准 HTTP 响应代码用于所有返回的结果，错误将使用正确的格式作为内容返回。
Version 1.X to 2.x
OpenTSDB 1.x 有一个简单的 HTTP API，它提供了对常见行为的访问，例如查询数据、自动完成查询和静态文件请求。 OpenTSDB 2.0 引入了一个新的、形式化的 API，如此处所述。 尽管大多数调用已被弃用并且可能会在版本 3 中删除，但 1.0 API 仍然可以访问。所有 2.0 API 调用都以 /api/开头。
Serializers
2.0 引入了可插入序列化程序，允许解析用户输入并以不同格式（如 XML 或 JSON）返回结果。 序列化程序仅适用于 2.0 API 调用，所有 1.0 的行为都和以前一样。 有关支持的序列化程序和选项的详细信息，请阅读HTTP Serializers。
所有 API 调用都使用默认的 JSON 序列化程序，除非被查询字符串或 Content-Type 标头覆盖。 要覆盖：
-
Query String - 提供诸如
serializer=<serializer_name>之类的参数，其中<serializer_name>是序列化程序的硬编码名称，如/api/serializersserializer输出字段中所示。Warning
如果找不到与
<serializer_name>值匹配的序列化程序，查询将返回错误而不是进一步处理。 -
Content-Type - 如果未给出查询字符串，TSD 将解析 HTTP 请求中的
Content-Type标头。 每个序列化器都可以提供一个内容类型，如果与传入的请求匹配，将使用正确的序列化器。 如果未找到映射到内容类型的序列化程序，则将使用默认序列化程序。 -
Default - 如果未提供查询字符串参数或内容类型缺失或不匹配，则将使用默认的 JSON 序列化程序。
API 文档将使用 JSON 序列化程序显示请求和响应。 有关序列化程序改变行为的方式，请参阅插件文档。
Note
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 端点的 PNG 文件，您将收到 406 响应，因为日志条目无法转换为 PNG 图像（很容易） |
| 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 | 关于出错的描述性错误消息 | Missing required parameter |
| details | String | Optional | 有关错误的详细信息，通常是堆栈跟踪 | Missing value: type |
| trace | String | Optional | 描述产生错误的位置的 JAVA 堆栈跟踪。 这可以通过 tsd.http.show_stack_trace 配置选项禁用。 TSD 的默认设置是显示堆栈跟踪。 | See below |
所有错误都将返回一个有效的 HTTP 状态错误代码和一个包含错误详细信息的内容正文。 默认格式化程序将错误消息作为具有 application/json 内容类型的 JSON 返回。 如果请求了不同的格式化程序，输出可能会有所不同。 有关详细信息，请参阅格式化程序文档。
Example Error Result
{
"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"
}
}
请注意，堆栈跟踪被截断。 此外，跟踪将包括系统特定的行尾（在这种情况下 \r\n 对于 Windows）。 如果为用户显示或写入日志，请确保用新行和制表符替换 \n 或\r\n 和\r 字符。
Verbs
HTTP API 本质上是 RESTful，这意味着它通过使用 HTTP 动词来确定操作过程来尽力遵守 REST 协议。例如，GET 请求应该只返回数据，PUT 或 POST 应该修改数据，而 DELETE 应该删除它。文档将反映可以在端点上使用哪些动词以及它们的作用。
但是，在某些情况下，诸如DELETE 和 PUT 之类的动词会被防火墙、代理阻止或未在客户端中实现。此外，大多数开发人员习惯于专门使用GET 和 POST。因此，虽然 OpenTSDB API 支持扩展动词，但大多数请求可以通过添加查询字符串参数method_override 仅使用 GET 来执行。此参数允许客户端将大多数 API 调用的数据作为查询字符串值而不是正文内容传递。例如，您可以通过发出带有查询字符串 /api/annotation?start_time=1369141261&tsuid=010101&method_override=delete 的 GET来删除注释。下表描述了动词行为和覆盖。
| Verb | Description | Override |
|---|---|---|
| GET | 用于从 OpenTSDB 检索数据。 可以提供覆盖来修改内容。 注意：通过 GET 的请求只能使用查询字符串参数； 请参阅下面的注释。 | N/A |
| POST | 用于使用请求中的内容正文在 OpenTSDB 中更新或创建对象。 将使用格式化程序来解析内容正文 | method_override=post |
| PUT | 用提供的内容替换系统中的整个对象 | method_override=put |
| DELETE | 用于从系统中删除数据 | method_override=delete |
如果给定 API 调用不支持某个方法，则 TSD 将返回 405 错误。
Note
HTTP 规范规定，在请求正文中传递的数据和 GET 请求中的 URI 之间不应存在关联。 因此 OpenTSDB 的 API 不会解析 GET 请求中的正文内容。 但是，您可以提供带有数据的查询字符串和用于更新某些端点中的数据的覆盖。 但是我们建议您将 POST 用于写入数据的任何内容。
API Versioning
OpenTSDB 2.0 的 API 调用调用是版本化的，以便用户可以在保证向后兼容性的情况下进行升级。 要访问特定的 API 版本，您需要创建一个 URL，例如 /api/v<version>/<endpoint>，例如/api/v2/suggest。 这将访问建议端点的版本 2。 OpenTSDB 2.0.0 的版本控制从 1 开始。 对不存在的版本的请求将调用最新版本。 此外，如果您不提供明确的版本，例如 /api/suggest，将使用最新版本。
Query String Vs. Body Content
大多数 API 端点都支持查询字符串参数，尤其是那些从系统获取数据的参数。 然而，由于对某些字符进行编码的复杂性，尤其是 Unicode，所有端点也支持使用格式化程序通过 POST 内容进行访问。 默认格式是 JSON，因此客户端可以使用他们喜欢的方式生成 JSON 对象，并通过 POST 请求将其发送到 OpenTSDB API。 与查询字符串相比，POST 请求通常会在所提供的字段和完全 Unicode 支持方面提供更大的灵活性。
Compressed Requests
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 为跨域资源共享 (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。
如果源域与配置列表中的域不匹配，则响应将是 200 状态代码和内容正文的错误（见上文），表明访问被拒绝，无论请求是预检还是常规请求要求。该请求将不会被进一步处理。
默认情况下，tsd.http.request.cors_domains 列表是空的并且 CORS 被禁用。请求在不附加 CORS 特定标头的情况下通过。如果 Options 请求到达，它将收到 405 错误消息。
Note
不要依赖 CORS 来保证安全。 在 HTTP 请求中欺骗域非常容易，而且 OpenTSDB 不执行反向查找或域验证。 CORS 的实现只是为了让 JavaScript 开发人员更轻松地使用 API。
Documentation
下面列出的每个端点的文档将包含有关如何使用该端点的详细信息。 Eahc 页面将包含端点的描述、支持的动词、请求中的字段、响应中的字段和示例。
请求参数是您可以随请求传入的字段名称列表。 每个表都有以下信息：
- Name - 字段名称
- Data Type - 您需要提供的数据类型。 例如。
String应该是文本，Integer必须是一个整数（正或负），Float应该是一个十进制数。 数据类型也可以是复杂的对象，例如数组或值或对象的映射。 如果您在此列中看到“Present”，则只需将参数添加到查询字符串即可将值设置为“true”，参数的实际值将被忽略。 例如/api/put?summary将有效地设置summary=true。 如果您请求/api/put?summary=false，API 仍会将请求视为summary=true。 - Required - 成功查询是否需要该参数。 如果参数是必需的，您将看到
Required，否则它将是Optional。 - Description - 参数的详细说明，包括允许的值（如果适用）。
- Default -
Optional参数的默认值。 如果需要数据，此字段将为空白。 - QS -如果可以通过查询字符串提供参数，则此字段中将包含
Yes，否则将包含No，表示该参数只能作为请求正文内容的一部分提供。 - RW - 描述此参数是否会导致更新存储在 OpenTSDB 中的数据。 此列中的可能值为：
- empty - 这意味着该字段仅用于查询，不一定代表响应中的字段。
- RO - 出现在响应中但只读的字段。 与请求一起传递的值不会改变输出字段。
- RW or W - Will导致更新系统中存储的数据的字段
- Example - 参数值示例