写入数据

写入模式及其响应内容

根据写入时指定请求参数，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 就是真实失败的数据点数

  该模式适用于业务监控数据上报时对于上报数据的完整性存在需求，对于失败数据希望进行修复重试时的场景。