寫入模式及其響應內容

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

• 極簡模式

  寫入時在 api/put 后不帶任何參數。此時TSDB寫入成功會返回 204 表示成功; 寫入失敗時會返回錯誤碼以及對應的錯誤消息，但不會帶更多信息。

  適用于一般性的業務監控數據上報的場景。

• 統計模式

  寫入時在 api/put 后帶上 summary 。此時TSDB寫入成功或失敗時會按下述響應內容返回成功的數據點數和失敗的數據點數方便業務端進行統計

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

  示例如下：

  {
      "failed":0,
      "success": 20
  }

  注意

  在統計模式下。對于一個 api/put 請求中寫入的一批數據，要么全部成功；要么全部失敗。失敗時返回的 failed 本質就是該批次的全部數據點數。

  該模式適用于一般性業務監控數據上報時對于上報數據存在統計需求時的場景。

• 詳細模式

  本質上是上述統計模式的擴展模式。寫入時在 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 就是真實失敗的數據點數

  該模式適用于業務監控數據上報時對于上報數據的完整性存在需求，對于失敗數據希望進行修復重試時的場景。