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返回的成功程式碼包括：

常見的錯誤響應程式碼包括:

錯誤

如果發生錯誤，API將返回一個響應，其中包含按請求的響應型別格式化的錯誤物件。錯誤物件欄位包括：

所有錯誤都將返回有效的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方式)。

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

• /s
• /api/aggregators
• /api/annotation
• /api/config
• /api/dropcaches
• /api/put
• /api/rollup
• /api/histogram
• /api/query
• /api/search
• /api/serializers

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