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

心已赠人 2022-04-22 04:10 242阅读 0赞

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

<table> 
 <thead> 
  <tr> 
   <th><strong>Code</strong></th> 
   <th><strong>Description</strong></th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td>200</td> 
   <td>请求成功完成</td> 
  </tr> 
  <tr> 
   <td>204</td> 
   <td>服务器已经成功地完成了请求，但是没有返回正文中的内容。这主要用于存储数据，因为不需要将数据返回给调用者</td> 
  </tr> 
  <tr> 
   <td>301</td> 
   <td>当API调用已经迁移或者应该被转发到另一台服务器时，可以使用这种方法</td> 
  </tr> 
 </tbody> 
</table>

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

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

## 错误 ##

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

<table> 
 <thead> 
  <tr> 
   <th>Field Name</th> 
   <th>Data Type</th> 
   <th>Always Present</th> 
   <th>Description</th> 
   <th>Example</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td>code</td> 
   <td>Integer</td> 
   <td>Yes</td> 
   <td>HTTP状态代码</td> 
   <td>400</td> 
  </tr> 
  <tr> 
   <td>message</td> 
   <td>String</td> 
   <td>Yes</td> 
   <td>关于出错的描述性错误消息</td> 
   <td>Missing required parameter</td> 
  </tr> 
  <tr> 
   <td>details</td> 
   <td>String</td> 
   <td>Optional</td> 
   <td>有关错误的详细信息，通常是堆栈跟踪</td> 
   <td>Missing value: type</td> 
  </tr> 
  <tr> 
   <td>trace</td> 
   <td>String</td> 
   <td>Optional</td> 
   <td>JAVA堆栈跟踪，描述生成错误的位置。可以通过tsd.http.show_stack_trace配置选项禁用此功能。TSD的默认设置是显示堆栈跟踪。</td> 
   <td>见下文</td> 
  </tr> 
 </tbody> 
</table>

所有错误都将返回有效的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方式**)。

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

如果给定的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][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 - 将导致更新系统中存储的数据的字段 [添加链接描述][Link 1]
 *  示例 - 参数值的示例

## 弃用的API ##

阅读不推荐使用的HTTP API [http://opentsdb.net/docs/build/html/api\_http/deprecated.html][http_opentsdb.net_docs_build_html_api_http_deprecated.html]

## API ##

*  [/s][s]
 *  [/api/aggregators][Link 1]
 *  [/api/annotation][api_annotation]
 *  [/api/config][api_config]
 *  [/api/dropcaches][api_dropcaches]
 *  [/api/put][api_put]
 *  [/api/rollup][api_rollup]
 *  [/api/histogram][api_histogram]
 *  [/api/query][api_query]
 *  [/api/search][api_search]
 *  [/api/serializers][api_serializers]

原文地址：[http://opentsdb.net/docs/build/html/api\_http/index.html][http_opentsdb.net_docs_build_html_api_http_index.html]

[beeblebrox.com]: http://xn--beeblebrox-uy5pu07g.com
[www.beeblebrox.com]: http://www.beeblebrox.com
[aurtherdent.com]: http://aurtherdent.com
[Link 1]: http://opentsdb.net/docs/build/html/api_http/aggregators.html
[http_opentsdb.net_docs_build_html_api_http_deprecated.html]: http://opentsdb.net/docs/build/html/api_http/deprecated.html
[s]: http://opentsdb.net/docs/build/html/api_http/s.html
[api_annotation]: http://opentsdb.net/docs/build/html/api_http/annotation/index.html
[api_config]: http://opentsdb.net/docs/build/html/api_http/config/index.html
[api_dropcaches]: http://opentsdb.net/docs/build/html/api_http/dropcaches.html
[api_put]: http://opentsdb.net/docs/build/html/api_http/put.html
[api_rollup]: http://opentsdb.net/docs/build/html/api_http/rollup.html
[api_histogram]: http://opentsdb.net/docs/build/html/api_http/histogram.html
[api_query]: http://opentsdb.net/docs/build/html/api_http/query/index.html
[api_search]: http://opentsdb.net/docs/build/html/api_http/search/index.html
[api_serializers]: http://opentsdb.net/docs/build/html/api_http/serializers.html
[http_opentsdb.net_docs_build_html_api_http_index.html]: http://opentsdb.net/docs/build/html/api_http/index.html