【翻译】OpenTSDB 2.3 文档--HTTP API介绍

HTTP API

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

概览

HTTP API本质上是RESTful，通过实现RESTful来对外支持访问，并非所有客户端都遵循严格的REST协议。默认数据交换是通过JSON进行的，尽管可插拔式的格式化工具formatters可以通过请求request来访问（意思是通过在请求的request中配置请求的格式，来使用对应的formatter，默认会使用JSON），以发送或接收不同格式的数据。标准HTTP响应代码用于所有返回的结果，错误将使用正确的格式作为返回内容返回。

版本1.X到2.x.

OpenTSDB 1.x有一个简单的HTTP API，可以访问常见的行为，例如查询数据，自动完成查询和静态文件请求。OpenTSDB 2.0引入了一个新的，形式化的API，如此该文所述。虽然大多数调用都已弃用，但仍可访问1.0 API，并且可能会在版本3中删除。所有2.0 API都以/api/开头。

串行器Serializers

2.0引入了可插入的序列化程序，允许解析用户输入并以不同的格式（如XML或JSON）返回结果。序列化程序仅适用于2.0 API调用，所有1.0都像以前一样运行。有关支持的序列化程序和选项的详细信息，请阅读HTTP序列化程序。

除非被查询字符串覆盖（理解为在查询串中明确指出使用哪串行器）或Content-Type标头覆盖，否则所有API调用都使用默认的JSON序列化程序。使用方式：

查询字符串中指明 -提供一个参数，例如serializer=<serializer_name>，其中<serializer_name>是硬编码的名称，/api/serializers输出字段中会包含所有serializer的名称(访问你的OPENTSDB的/api/serializers接口就可以看到了，通过GET方式)
警告：如果未找到与提供<serializer_name>相匹配的序列化程序serializer，则查询将返回错误而不是进一步处理。
Content-Type - 如果未给出查询字符串，TSD将解析HTTP请求头中的Content-Type字段。每个串行器serializer都支持一个content type，如果与传入请求中的匹配，将使用对应的serializer。如果找不到合适的序列化程序serializer，则将使用默认的JSON序列化程序。
默认值 - 如果未通过查询字符串或者content-type指明，则将使用默认的JSON序列化程序。

本API文档将使用JSON序列化程序显示请求和响应。有关序列化程序改变行为的方式，请参阅插件文档。
注意：JSON规范声明字段可以按任何顺序出现，因此不要假设将保留给定示例中的顺序。可以对数组进行排序，如果是，则将对其进行记录（JSON中字段是没有顺序的，所以示例中的字段顺序是可以变更）。

认证/权限

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

响应代码

每个请求都将返回标准的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交互的其他用户/应用程序，并确定是否需要减少请求或扩展系统。

错误

如果发生错误，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的默认设置是显示堆栈跟踪。	见下文

所有错误都将返回有效的HTTP状态错误代码和包含错误详细信息的内容正文。默认格式化程序将错误消息作为JSON返回application/json内容类型。如果请求了不同的格式化程序，则输出可能不同。有关详细信息，请参阅formatter文档。

示例错误结果:

    “error” ： { 
        “code” ： 400 ，
        “message” ： “缺少参数<code> type </ code>” ，
        “trace” ： “net.opentsdb.tsd.BadRequestException：缺少参数<code> type </ code> \ r \ n \ tat \ net.opentsdb.tsd.BadRequestException.missingParameter（BadRequestException.java：78）〜[bin /：na] \ r \ n \ 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（未知来源）[na：1.6.0_26] \ r \ n“ 
    } 
}

请注意，堆栈跟踪被截断。此外，跟踪将包括系统特定的行结尾（在本例中\r\n为Windows）。如果为用户显示或写入日志，请务必使用新行和制表符替换\n或 \r\n和\r字符。

Verbs

HTTP API本质上是RESTful，这意味着它最好通过使用HTTPVerbs来确定一个行动过程来遵守REST协议。例如，GET请求应仅返回数据，a PUT或POST应修改数据并DELETE应删除它。文档将反映端点上可以使用的Verbs以及它们的作用。

然而，在某些情况下， DELETE和PUT可能没有通过防火墙，被代理服务器阻塞或者在客户端没有实现。此外，大多数开发人员习惯于使用GET和POST。因此，虽然OpenTSDB API支持更多的Verbs，但大多数的请求可以通过给GET加一个参数method_override来实现。此参数允许客户端将大多数API调用的数据作为查询字符串值而不是正文内容传递。例如，您可以通过发出GET带有查询字符串来删除注释/api/annotation?start_time=1369141261&tsuid=010101&method_override=delete。下表描述了Verbs行为和method_override(即大多数的请求都可以改造成GET方式)。

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

如果给定的API调用不支持某个方法，TSD将返回405错误。
注意：HTTP规范声明请求数据与请求中的URI之间不应存在关联，在GET请求中。因此，OpenTSDB的API不会解析GET请求中的请求body。但是，您可以提供包含数据的override的Get请求用于更新某些端点中的数据的覆盖。但我们建议您使用POST（即相当于通过在GET请求中加上override字段，在处理时可以支持读取GET请求的body，但如果这样做的话，建议直接使用POST）。

API版本控制

OpenTSDB 2.0的API都版本化，以便用户可以向后兼容性进行升级。要访问特定的API版本，您需要按格式拼接一个URL，/api/v/，例如/api/v2/suggest。这将访问suggest的第二个版本。OpenTSDB 2.0.0的版本控制从1开始。对不存在的版本的请求将导致调用最新版本。此外，如果您不提供显式版本，例如/api/suggest，将使用最新版本。

Query String Vs. Body Content

大多数API都支持查询字符串参数，尤其是那些从系统中获取数据的。但是，由于编码某些字符（尤其是Unicode）的复杂性，所有API还支持使用POST进行访问，并使用格式化程序编码格式。默认格式为JSON，因此客户端可以使用自己喜欢的方式生成JSON对象，并通过POST请求将其发送到OpenTSDB API 。POST请求通常会在提供的字段中提供更大的灵活性，并且比查询字符串提供完全的Unicode支持（就是相当于说，大多数的API访问功能都可以通过GET请求来作，但是建议通过POST来做）。

压缩请求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头添加到响应中。允许的方法永远是。它不会改变每个终点。如果请求是CORS预检，即使用该方法，则响应将是相同的，但具有空的内容主体和200状态代码。GET, POST, PUT, DELETEOPTION

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

默认情况下，tsd.http.request.cors_domains列表为空并且CORS被禁用。传递请求而不附加CORS特定标头。如果Options请求到达，它将收到405错误消息。

**注意：**不要依赖CORS来提高安全性。在HTTP请求中欺骗域非常容易，而OpenTSDB不执行反向查找或域验证。CORS仅用于使JavaScript开发人员更容易使用API。

文档

下面列出的每个API的文档将包含有关如何使用该端点的详细信息。每个页面将包含API的描述，支持的Verbs，请求的字段，响应中的字段和示例。

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

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
-QS - 如果参数可以通过查询字符串提供，则该字段将包含一个Yes，否则它将具有No参数只能作为请求正文内容的一部分提供的含义。
RW -描述此参数是否可以导致对存储在OpenTSDB中的数据进行更新。此列中可能的值为：
empty -这意味着该字段仅用于查询，并且不一定代表响应中的字段。
RO - 出现在响应中但只读的字段。传递的请求值不会改变输出字段。
RW或W - 将导致更新系统中存储的数据的字段添加链接描述
示例 - 参数值的示例

弃用的API

阅读不推荐使用的HTTP API http://opentsdb.net/docs/build/html/api_http/deprecated.html

API

原文地址：http://opentsdb.net/docs/build/html/api_http/index.html