多值數(shù)據(jù)寫(xiě)入
本文介紹多值數(shù)據(jù)寫(xiě)入的寫(xiě)入模式及其響應(yīng)內(nèi)容。
時(shí)序多值模型
多值的模型是針對(duì)數(shù)據(jù)源建模，我們每一行數(shù)據(jù)針對(duì)的是一個(gè)數(shù)據(jù)源，它的被測(cè)量的多個(gè)指標(biāo)在同一行上，所以每一個(gè)數(shù)據(jù)源，數(shù)據(jù)的來(lái)源在每一個(gè)時(shí)間點(diǎn)上都有一行，這就是多值的模型。比如某個(gè)機(jī)器的cpu，mem和load指標(biāo)。每次是數(shù)據(jù)操作可以使用多個(gè)指標(biāo)數(shù)據(jù)。
多值模型數(shù)據(jù)寫(xiě)入
請(qǐng)求路徑和方法
請(qǐng)求路徑 | 請(qǐng)求方法 | 描述 |
|---|---|---|
/api/mput | POST | 一次寫(xiě)入多個(gè)數(shù)據(jù)點(diǎn)。 |
多值模型數(shù)據(jù)和單值模型數(shù)據(jù)不兼容。單值模型數(shù)據(jù)需要通過(guò)原有的/api/put接口進(jìn)行寫(xiě)入。同時(shí)多值寫(xiě)入數(shù)據(jù)需要通過(guò)/api/mquery接口進(jìn)行查詢，單值寫(xiě)入的數(shù)據(jù)需要通過(guò)/api/query 進(jìn)行查詢。
請(qǐng)求參數(shù)
名稱 | 類(lèi)型 | 是否必需 | 描述 | 默認(rèn)值 | 舉例 |
|---|---|---|---|---|---|
summary | 無(wú)類(lèi)型 | 否 | 是否返回摘要信息。 | false | /api/mput?summary |
details | 無(wú)類(lèi)型 | 否 | 是否返回詳細(xì)信息。 | false | /api/mput?details |
sync_timeout | Integer | 否 | 超時(shí)時(shí)間，單位毫秒，0為永不超時(shí)。 | 0 | /api/mput/?sync&sync_timeout=60000 |
ignoreErrors | 無(wú)類(lèi)型 | 否 | 是否忽略部分?jǐn)?shù)據(jù)點(diǎn)的寫(xiě)入異常。 | false | /api/mput/?ignoreErrors |
所有“無(wú)類(lèi)型”的參數(shù)只要提供，都被視為 true。比如summary=false以及summary=true都被當(dāng)做summary=true。
如果details和summary都設(shè)置，API將返回details信息。
請(qǐng)求內(nèi)容
數(shù)據(jù)點(diǎn)格式為JSON格式，各參數(shù)說(shuō)明如下：
名稱 | 類(lèi)型 | 是否必需 | 是否有使用限制 | 描述 | 舉例 |
|---|---|---|---|---|---|
metric | String | 是 | 只可包含大小寫(xiě)英文字母、中文、數(shù)字，以及特殊字符 | 存儲(chǔ)的指標(biāo)名。 | sys.cpu。 說(shuō)明 高可用版本支持的metric長(zhǎng)度最多為255字節(jié)。 |
timestamp | Long | 是 | 無(wú) | 時(shí)間戳。單位為秒或者毫秒，判斷規(guī)則詳見(jiàn)下面的“時(shí)間戳說(shuō)明”。 | 1499158925 |
fields | Map | 是 | field 名字限制和 metric 限制一樣，field 值只支持 String，Number，Boolean | 域數(shù)據(jù)值。 | “fields” : {“speed” : 20.8, “l(fā)evel” : 4, “direction” : “East”, “description” : “Fresh breeze”} |
tags | Map | 是 | 可以包含大小寫(xiě)英文字母、中文、數(shù)字，以及特殊字符 | Tagk 和 Tagv 是字符串鍵值對(duì)，至少一個(gè)鍵值對(duì)。 | {“host”:”web01”}，非字符串類(lèi)型的tagk，tagv會(huì)強(qiáng)制轉(zhuǎn)換為字符串類(lèi)型。 |
時(shí)間戳說(shuō)明
本說(shuō)明適用于讀寫(xiě)數(shù)據(jù)（/api/put & /api/mput）和查詢數(shù)據(jù)（/api/query & /api/mquery）兩個(gè)接口。時(shí)間戳的單位可以是秒或者毫秒。TSDB 會(huì)通過(guò)數(shù)值大小來(lái)判斷時(shí)間戳的單位，規(guī)則如下：
時(shí)間戳區(qū)間為 [4294968,4294967295]：判斷為秒，表示的時(shí)間區(qū)間為：[1970-02-20 01:02:48, 2106-02-07 14:28:15]。
時(shí)間戳區(qū)間為 [4294967296,9999999999999]：判斷為毫秒，表示的時(shí)間區(qū)間為：[1970-02-20 01:02:47.296, 2286-11-21 01:46:39.999]。
時(shí)間戳區(qū)間為（-∞,4294968）和（9999999999999,+∞）：判斷為非法時(shí)間戳區(qū)間。
數(shù)據(jù)點(diǎn)值說(shuō)明
String數(shù)值類(lèi)型的數(shù)據(jù)值可以為任意字符，支持JSON字符串存儲(chǔ)，最大為20 KB。
寫(xiě)入數(shù)據(jù)示例：
請(qǐng)求：
POST/api/mput請(qǐng)求體：[ { "metric":"wind", "fields":{ "speed":20.8, "level":4, "direction":"East", "description":"Fresh breeze" }, "tags":{ "sensor":"IOTE_8859_0001", "city":"hangzhou", "province":"zhejiang", "country":"china" }, "timestamp":1346846400 }, { "metric":"wind", "fields":{ "speed":40.2, "level":6, "direction":"South", "description":"Fresh breeze" }, "tags":{ "sensor":"IOTE_8859_0002", "city":"hangzhou", "province":"zhejiang", "country":"china" }, "timestamp":1346846401 } ]
寫(xiě)入模式及其響應(yīng)內(nèi)容
根據(jù)寫(xiě)入時(shí)指定請(qǐng)求參數(shù)，TSDB支持四種模式的寫(xiě)入，分別如下所示：
極簡(jiǎn)模式
寫(xiě)入時(shí)在
api/mput后不帶任何參數(shù)。TSDB寫(xiě)入成功會(huì)返回204表示成功，寫(xiě)入失敗時(shí)會(huì)返回錯(cuò)誤碼以及對(duì)應(yīng)的錯(cuò)誤消息，但不會(huì)帶更多信息。適用于一般性的業(yè)務(wù)監(jiān)控?cái)?shù)據(jù)上報(bào)的場(chǎng)景。
統(tǒng)計(jì)模式
寫(xiě)入時(shí)在
api/mput后帶上summary。TSDB寫(xiě)入成功或失敗時(shí)會(huì)按下述響應(yīng)內(nèi)容返回成功的數(shù)據(jù)點(diǎn)數(shù)和失敗的數(shù)據(jù)點(diǎn)數(shù)方便業(yè)務(wù)端進(jìn)行統(tǒng)計(jì)。名稱
數(shù)據(jù)類(lèi)型
描述
success
Integer
寫(xiě)入成功的數(shù)據(jù)點(diǎn)數(shù)。
failed
Integer
未能成功寫(xiě)入的數(shù)據(jù)點(diǎn)數(shù)。
示例如下：
{ "failed":0, "success": 20 }注意在統(tǒng)計(jì)模式下。對(duì)于一個(gè)
api/mput請(qǐng)求中寫(xiě)入的一批數(shù)據(jù)，要么全部成功，要么全部失敗。失敗時(shí)返回的failed本質(zhì)就是該批次的全部數(shù)據(jù)點(diǎn)數(shù)。
在多值寫(xiě)入時(shí)，返回的success或failed統(tǒng)計(jì)的數(shù)據(jù)點(diǎn)數(shù)是基于單值模型統(tǒng)計(jì)的點(diǎn)數(shù)。即一個(gè)多值數(shù)據(jù)點(diǎn)在統(tǒng)計(jì)時(shí)會(huì)乘以其field個(gè)數(shù)。
該模式適用于一般性業(yè)務(wù)監(jiān)控?cái)?shù)據(jù)上報(bào)時(shí)對(duì)于上報(bào)數(shù)據(jù)存在統(tǒng)計(jì)需求時(shí)的場(chǎng)景。
詳細(xì)模式
詳細(xì)模式是上述統(tǒng)計(jì)模式的擴(kuò)展模式。寫(xiě)入時(shí)在
api/mput后帶上details。此時(shí)TSDB寫(xiě)入或失敗時(shí)，會(huì)按下述響應(yīng)內(nèi)容返回成功的數(shù)據(jù)點(diǎn)數(shù)以及導(dǎo)致失敗的直接原因。名稱
數(shù)據(jù)類(lèi)型
描述
success
Integer
寫(xiě)入成功的數(shù)據(jù)點(diǎn)數(shù)。
failed
Integer
未寫(xiě)入的數(shù)據(jù)點(diǎn)數(shù)。
errors
Array
描述引起寫(xiě)入失敗直接原因的數(shù)組。其中只會(huì)包含第一個(gè)引發(fā)失敗的數(shù)據(jù)點(diǎn)及其失敗原因。
注意在詳細(xì)模式下，對(duì)于一個(gè)
api/mput請(qǐng)求中寫(xiě)入的一批數(shù)據(jù)，要么全部成功，要么全部失敗。而且返回的errors中只會(huì)返回第一個(gè)引發(fā)失敗的數(shù)據(jù)點(diǎn)及其失敗原因（直接原因），該批次的其他數(shù)據(jù)點(diǎn)不會(huì)包含在errors中，只會(huì)體現(xiàn)在統(tǒng)計(jì)信息failed中。該模式適用于業(yè)務(wù)監(jiān)控?cái)?shù)據(jù)上報(bào)時(shí)對(duì)于上報(bào)數(shù)據(jù)存在統(tǒng)計(jì)需求且需要失敗定位時(shí)的場(chǎng)景。
容錯(cuò)模式
寫(xiě)入時(shí)在
api/mput后帶上ignoreErrors。TSDB寫(xiě)入時(shí)，會(huì)保證一個(gè)請(qǐng)求的一批數(shù)據(jù)中盡量寫(xiě)入。即使這個(gè)批次中存在一些非法數(shù)據(jù)時(shí)，對(duì)于其他合法數(shù)據(jù)盡力寫(xiě)入成功。返回時(shí)，會(huì)將該批次數(shù)據(jù)中寫(xiě)入失敗的數(shù)據(jù)全部返回，返回的響應(yīng)內(nèi)容和指定details時(shí)相同，只是此時(shí)通過(guò)errors字段返回的將是該一批次數(shù)據(jù)中所有的失敗數(shù)據(jù)，未被返回的數(shù)據(jù)可以認(rèn)為寫(xiě)入成功。名稱
數(shù)據(jù)類(lèi)型
描述
success
Integer
寫(xiě)入成功的數(shù)據(jù)點(diǎn)數(shù)。
failed
Integer
未寫(xiě)入的數(shù)據(jù)點(diǎn)數(shù)。
errors
Array
描述該批次數(shù)據(jù)中所有未能成功寫(xiě)入的數(shù)據(jù)點(diǎn)數(shù)組及其各自的失敗原因。
注意在容錯(cuò)模式下，一個(gè)批次中存在部分?jǐn)?shù)據(jù)寫(xiě)入失敗時(shí)，TSDB響應(yīng)的返回碼仍然是200。除非發(fā)生因底層存儲(chǔ)異常等嚴(yán)重錯(cuò)誤導(dǎo)致全量數(shù)據(jù)失敗時(shí)，才會(huì)返回200以外的返回碼。該模式下返回的
failed就是真實(shí)失敗的數(shù)據(jù)點(diǎn)數(shù)。該模式適用于業(yè)務(wù)監(jiān)控?cái)?shù)據(jù)上報(bào)時(shí)對(duì)于上報(bào)數(shù)據(jù)的完整性存在需求，對(duì)于失敗數(shù)據(jù)希望進(jìn)行修復(fù)重試時(shí)的場(chǎng)景。