openTSDB详解之HTTP API

openTSDB详解之HTTP API[待完善]

openTSDB 提供了一个基于HTTP应用的编程接口，为了与外部系统集成。几乎所有的openTSDB特点就是可以通过API访问得到，诸如：查询时间序列数据，管理元数据以及存储数据点。请阅读这个完整的页面为了重要的信息关于标准的API行为，在详细探究单独的端点时。

Overview

HTTP API本质上是RESTful，但是提供了可选的访问，通过不同的重载，因为不是所有的客户端能够拥有一个严格REST 协议。默认的数据是通过JSON，尽管可插拔的formatters可以被访问，通过请求，接收或者是以不同的格式发送数据。标准的HTTP响应代码被用于所有的返回结果，错误将会被返回作为内容，使用合适的格式。

Version 1.x to 2.x

openTSDB 1.x 有一个简单的HTTP API，这个API提供了访问到公共的行为诸如：查询数据，自动完成查询以及静态文件请求。openTSDB 2.0引进了一个新的，格式化的API，这个API也就是现在这里需要介绍的文档。1.0 版本的API仍然可访问，尽管大多数调用已经被弃用，或许被移除在version 3中。所有的2.0 版本的API调用均已/api/开头。

Serializers

2.0 引进了可插拔的序列化，允许解析用户输入，并返回结果使用不同的格式，诸如xml, json。序列化仅仅应用于2.0 版本API调用，所有的1.0 与之前的行为相同。想了解Serializers的细节，已经其支持的选项，可以阅读HTTP Serializers。
所有的API 调用使用默认的JSON 序列器，直到被查询字符串或者是Content-Type重载。重载可以这么实现：
- Query String: 应用一个参数诸如serializer=<serializer_name>，其中<serializer_name>是一个硬编码的名字，关于序列化其，正如展示在/api/serializers/serializer输出的字段

Warning

如果一个序列化没有被找到，匹配<serializer_name>值的话，查询将会返回一个错误而不是进一步处理。
- Content-Type：如果一个查询字符串没有给出，TSD将会解析Content-Type头来自于HTTP请求。每个序列化其可能应用一个内容字段，如果匹配的上即将到来的请求，合适的序列化器将会被使用。如果一个序列化其没有被定位，映射到内容类型，默认的序列化器将会被使用。

Default:如果没有查询字符串给出，或者content-type是丢失了，或者不匹配，默认的JSON序列化器将会被使用。
API文档将会展示请求以及响应使用JSON序列化器。查看plugin 文档，对于哪种序列化其自动变化的行为。

Note

JSON 规格说明书指定表述那字段能够以任何顺序出现，所以不要假设给出的例子中的排序将会被保留。数组可能被排序，如果那样的话，将会被记录下来。

Authentication / Permissions

然而截止，openTSDB缺少一个验证以及访问控制系统。因此，没有验证请求是需要的，在访问API的时候。如果你希望限制访问openTSDB，使用网络ACLs或者防火墙阻塞。我们的确不推荐运行openTSDB在一个公共机器上。

Response Codes

每个请求将会被返回，使用一个标准的HTTP回复码。大多数响应警徽包涵content，尤其是错误码，这个错误码将会包涵细节在体中，关于什么时候运行错误了。API中成功的码包括：

Code    Description
200     The request completed successfully
204     The server has completed the request successfully but is not returning content in the body. This is primarily used for storing data points as it is not necessary to return data to caller
301     This may be used in the event that an API call has migrated or should be forwarded to another server

常见的错误码有：
Common error response codes include:

Code    Description
400     Information provided by the API user, via a query string or content data, was in error or missing. This will usually include information in the error body about what parameter caused the issue. Correct the data and try again.
404     The requested endpoint or file was not found. This is usually related to the static file endpoint.
405     The requested verb or method was not allowed. Please see the documentation for the endpoint you are attempting to access
406     The request could not generate a response in the format specified. For example, if you ask for a PNG file of the logs endpoing, you will get a 406 response since log entries cannot be converted to a PNG image (easily)
408     The request has timed out. This may be due to a timeout fetching data from the underlying storage system or other issues
413     The results returned from a query may be too large for the server's buffers to handle. This can happen if you request a lot of raw data from OpenTSDB. In such cases break your query up into smaller queries and run each individually
500     An internal error occured within OpenTSDB. Make sure all of the systems OpenTSDB depends on are accessible and check the bug list for issues
501     The requested feature has not been implemented yet. This may appear with formatters or when calling methods that depend on plugins
503     A temporary overload has occurred. Check with other users/applications that are interacting with OpenTSDB and determine if you need to reduce requests or scale your system.

Errors

如果一个错误发生了，API将会返回一个响应使用一个error object，格式化每个请求的响应类型。Error object 字段包括：

Field Name	Data Type	Always Present	Description	Example
code	Integer	Yes	The HTTP status code	400
message	String	Yes	A descriptive error message about what went wrong	Missing required parameter
details	String	Optional	Details about the error, often a stack trace	Missing value: type
trace	String	Optional	A JAVA stack trace describing the location where the error was generated. This can be disabled via the tsd.http.show_stack_trace configuration option. The default for TSD is to show the stack trace.	See below

所有的错误将会返回和一个无效的HTTP Status error code，并且一个内容体带有错误详情。默认的格式化返回错误信息使用JSON，带有application/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字符使用换行和tab键。

Verbs

HTTP API本质上是RESTful。【译者注：我一直不大理解这个意思】意味着它不能尽其最大努力添加REST 协议通过使用HTTP verbs去决定一个动作课程。例如，一个GET请求应该仅仅返回数据，一个PUT或者POST应该修改数据并且DELETE将会移除数据。文档将会展示什么样的vrbs将会被使用在一个endpoint上并且他们该怎么做。
然而，在某些情况下，诸如DELETE，PUT这样的verbs被防火墙，代理阻塞，或者根本在客户端中就不能实现。而且，大多数开发者习惯使用GET和POST而不是其它的动作。因此，尽管openTSDB API支持其它的verbs，大多数的请求能够被执行仅仅通过GET方式，通过添加请求字符串method_override。这个参数允许客户端传递数据为大多数API 调用，因为查询字符串而不是内容体。例如，你能删除一个注释通过发起一个GET请求，请求字符串：/api/annotation?start_time=1369141261&tsuid=010101&method_override=delete。下列表描述了动作行为已经重载方式。

Verb    Description     Override
GET     Used to retrieve data from OpenTSDB. Overrides can be provided to modify content. Note: Requests via GET can only use query string parameters; see the note below.  N/A
POST    Used to update or create an object in OpenTSDB using the content body from the request. Will use a formatter to parse the content body  method_override=post
PUT     Replace an entire object in the system with the provided content    method_override=put
DELETE  Used to delete data from the system     method_override=delete

如果一个方法不支持与给出的API调用，TSD将会返回一个405错误。

Note

HTTP 规范声明不应该有一个联系在数据传输在请求体中，以及URI在一个GET请求中。那么OpenTSDB的API不能解析内容在GET请求中。然而，你能提供一个查询字符串使用数据，并且重载用于更新的数据在某些端中。但是我们建议你使用POST对于任何写的数据。

API Versioning

openTSDB 2.0的版本调用是版本化的，所以用户能够升级使用保证背景兼容。为了访问一个具体的API版本，你能写一个URL类似/api/v/诸如/api/v2/suggest。这将访问suggest端的版本2。版本从1开始，对于OpenTSDB2.0.0。请求对于一个并不存在的版本将会导致调用最近的版本。同样，如果你不提供一个显示的版本，诸如/api/suggest，那么最近的版本将会被使用。

Query String Vs.Body Content

大多数API端支持查询字符串参数，尤其是对于这些从系统中获取数据。然而，由于编码某些字符的复杂性，典型的如Unicode，所有的端也支持访问通过POST内容使用格式化器。默认的格式是json，所以客户端能够使用他们最喜欢的方式生成JSON对象并将其发送到OpenTSDB API通过一个POST请求。POST请求将会普遍提供更好的灵活性在字段上，并且完全的Unicode支持，而不是查询字符串。

Compressed Requests

API 能够接收内容体，已经被压缩的。确保设置Content-Encoding头去gzip以及传递二进制编码数据到（Make sure to set the Content-Encoding header to gzip and pass the binary encoded data over the wire.）这典型的有用对于推送数据点到/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的状态码，并且一个Error（上述）对于内容体：表述访问会被拒绝，无论请求是否是预起飞或者一个规则的请求。请求不会被处理。
默认情况下，tsd.http.request.cors_domains列表是空的并且CORS是无效的。请求被传递通过没有追加CORS具体的headers。如果一个Options请求到达，它将收到一个405错误消息。

Note

不要依赖CORS为了安全。用一种HTTP请求是极其容易愚弄域名的，openTSDB不执行反向查找或域验证。CORS仅仅被实现作为一种方式让javaScript开发者去使用API。

Documention

下面列出的每个端的文档将会包涵细节关于如何使用端。每页将会包涵一个端描述，支持何种verbs，请求中的字段，响应的字段已经例子。
请求参数是一个字段列表，你能传递到你的请求中。每个表有如下的信息：
- Name:字段名
- DataType：你需要提供的数据类型。
- Required：一个成功查询的参数是否需要。如果参数被要求，你将看到Required否则将会是Optional。
- Description:一个细节描述关于参数，包括什么值是被允许如果应用的话。
- QS:如果参数能够被应用通过查询字符串，这个字段将会有一个Yes在其中，否则，将会有一个No，则意味着：参数仅仅被应用作为请求体内容的一部分。
- RW：描述这个参数是否会导致存储在openTSDB中的数据被更新。这个字段中可能的值是：