寫入資料 - Time Series Database

請求路徑和方法

請求路徑	要求方法	描述
/api/put	POST	一次寫入多個資料點。

請求參數

名稱	類型	是否必需	描述	預設值	舉例
summary	無類型	否	是否返回摘要資訊。	false	/api/put?summary
details	無類型	否	是否返回詳細資料。	false	/api/put?details
sync_timeout	Integer	否	逾時時間，單位毫秒，0為永不逾時。	0	/api/put/?sync&sync_timeout=60000
ignoreErrors	無類型	否	是否忽略部分資料點的寫入異常。	false	/api/put/?ignoreErrors

注意：

所有“無類型”的參數，只要提供，都被視為 true，比如 summary=false 以及 summary=true 都被當做 summary=true。
如果 details 和 summary 都設定，API 將返回 details 資訊。

請求內容

資料點格式為 JSON 格式，各參數說明如下：

名稱	類型	是否必需	是否有使用限制	描述	舉例
metric	String	是	只可包含大小寫英文字母、中文、數字，以及特殊字元 `-_./():,[]=‘#`	儲存的指標名	sys.cpu。說明高可用版本支援的metric長度最多為255位元組。
timestamp	Long	是	無	時間戳記；單位為秒或者毫秒，判斷規則詳見下面的時間戳記說明。	1499158925
value	Long,Double,String,Boolean	是	無	資料點值	42.5, true
tags	Map	否	可以包含大小寫英文字母、中文、數字，以及特殊字元 `-_./():,[]=‘#`	Tagk 和 Tagv 是字串索引值對，至少一個索引值對	{“host”:”web01”}，非字串類型的tagk，tagv會強制轉換為字串類型

時間戳記說明

本說明適用於讀寫資料 (/api/put) 和查詢資料 (api/query) 兩個介面。

時間戳記的單位可以是秒或者毫秒。TSDB 會通過數值大小來判斷時間戳記的單位，規則如下：

時間戳記區間為 [4294968,4294967295]: 判斷為秒，表示的時間區間為：[1970-02-20 01:02:48, 2106-02-07 14:28:15]。
時間戳記區間為 [4294967296,9999999999999]：判斷為毫秒，表示的時間區間為：[1970-02-20 01:02:47.296, 2286-11-21 01:46:39.999]。
時間戳記區間為（-∞,4294968）和（9999999999999,+∞）：判斷為非法時間戳記區間。

資料點值說明

String數實值型別的資料值可以為任一字元，支援JSON字串儲存，最大為20KB。

Tags說明

向一條時間軸寫入資料時，其Tagkey的個數存在上限。根據TSDB執行個體規格不同，Tagkey的個數上限如下所示：

執行個體規格	單時間軸 Tagkey 數上限（個）
mLarge	16
Large	16
3xLarge	20
4xLarge	20
6xLarge	20
12xLarge	20
24xLarge	24
48xLarge	24
96xLarge	24

寫入資料樣本

請求：POST/api/put

請求體：

[
{
"metric":"sys.cpu.nice",
"timestamp":1346846400,
"value":18,
"tags":{
"host":"web01",
"dc":"lga"
}
},
{
"metric":"sys.cpu.nice",
"timestamp":1346846400,
"value":9,
"tags":{
"host":"web02",
"dc":"lga"
}
},
{
"metric":"sys.cpu.alter",
"timestamp":1346846400,
"value":"High CPU Load",
"tags":{
"host":"web03",
"dc":"lga"
}
},
{
"metric":"sys.cpu.nice",
"timestamp":1346846400,
"value":true,
"tags":{
"host":"web04",
"dc":"lga"
}
}
]

寫入模式及其響應內容

根據寫入時指定請求參數，TSDB支援四種模式的寫入，分別如下所示：

極簡模式
寫入時在 api/put 後不帶任何參數。此時TSDB寫入成功會返回 204 表示成功; 寫入失敗時會返回錯誤碼以及對應的錯誤訊息，但不會帶更多資訊。
適用於一般性的業務監控資料上報的情境。
統計模式
寫入時在 api/put 後帶上 summary 。此時TSDB寫入成功或失敗時會按下述響應內容返回成功的資料點數和失敗的資料點數方便業務端進行統計
名稱
資料類型
描述
success
Integer
寫入成功的資料點數
failed
Integer
未能成功寫入的資料點數
樣本如下：
```
{
    "failed":0,
    "success": 20
}
```
重要
在統計模式下。對於一個 api/put 請求中寫入的一批資料，要麼全部成功；要麼全部失敗。失敗時返回的 failed 本質就是該批次的全部資料點數。
該模式適用於一般性業務監控資料上報時對於上報資料存在統計需求時的情境。

名稱	資料類型	描述
success	Integer	寫入成功的資料點數
failed	Integer	未能成功寫入的資料點數

詳細模式

本質上是上述統計模式的擴充模式。寫入時在 api/put 後帶上 details。此時TSDB寫入或失敗時，會按下述響應內容返回成功的資料點數以及導致失敗的直接原因。

名稱	資料類型	描述
success	Integer	寫入成功的資料點數。
failed	Integer	未寫入的資料點數。
errors	Array	描述引起寫入失敗直接原因的數組。其中只會包含第一個引發失敗的資料點及其失敗原因

樣本如下：

{
    "errors":[{
            "datapoint":{
                "metric":"sys.cpu.nice",
                "timestamp":1365465600,
                "value":"NaN",
                "tags":{
                    "host":"web01"
                }
            },
            "error":"Unable to parse value to a number"
        }],
    "failed":1,
    "success":0
}

重要

在詳細模式下。對於一個 api/put 請求中寫入的一批資料，仍然是要麼全部成功；要麼全部失敗。而且返回的errors中只會返回第一個引發失敗的資料點及其失敗原因（直接原因），該批次的其他資料點不會包含在 errors 中，只會體現在統計資訊 failed 中

該模式適用於業務監控資料上報時對於上報資料存在統計需求且需要失敗定位時的情境。

容錯模式

寫入時在 api/put 後帶上 ignoreErrors。此時TSDB寫入時，會保證一個請求的一批資料中盡量寫入。即使這個批次中存在一些非法資料時，對於其他合法資料儘力寫入成功。返回時，會將該批次資料中寫入失敗的資料全部返回。返回的響應內容和指定 details 時相同，只是此時通過 errors 欄位返回的將是該一批次資料中所有的失敗資料，未被返回的資料可以認為寫入成功。

名稱	資料類型	描述
success	Integer	寫入成功的資料點數。
failed	Integer	未寫入的資料點數。
errors	Array	描述該批次資料中所有未能成功寫入的資料點數組及其各自的失敗原因。

樣本如下：

重要

在容錯模式下，一個批次中存在部分資料寫入失敗時，TSDB響應的返回碼仍然是 200。除非發生因底層儲存異常等嚴重錯誤導致全量資料失敗時，才會返回200以外的返回碼。該模式下返回的failed 就是真實失敗的資料點數

該模式適用於業務監控資料上報時對於上報資料的完整性存在需求，對於失敗資料希望進行修複重試時的情境。