全部产品
云市场

put

更新时间:2018-12-20 12:14:52

put

/api/put

Method

POST

请求参数

Name Data Type Required Description Default
summary Present Optional 返回结果是否显示success, failed, timeouts等统计信息。 false
details Present Optional 会显示更详细的错误信息在errors里,包括具体是哪个数据点写入出错。建议开启此参数,这样能定位到哪些数据点写入出错。 false
sync Boolean Optional 是否使用同步写入模式。非同步模式性能会略好于同步模式。但是非同步模式由于写入是立即返回成功的,实际数据并不一定真的写入成功。这个参数根据实际需要可以选择开启。 false
sync_timeout Integer Optional 超时时间,写入数据点到达一定时间后没有返回,会被认为写入超时。在sync模式下有效,需要开启details才能看到哪些数据点写入超时。默认值0,表示永远不会超时,一直等。单位毫秒。 0

请求体

  1. // 单数据点
  2. {
  3. "metric": "sys.cpu.nice",
  4. "timestamp": 1346846400,
  5. "value": 18,
  6. "tags": {
  7. "host": "web01",
  8. "dc": "lga"
  9. }
  10. }
  11. // 多数据点
  12. [
  13. {
  14. "metric": "sys.cpu.nice",
  15. "timestamp": 1346846400,
  16. "value": 18,
  17. "tags": {
  18. "host": "web01",
  19. "dc": "lga"
  20. }
  21. },
  22. {
  23. "metric": "sys.cpu.nice",
  24. "timestamp": 1346846400,
  25. "value": 9,
  26. "tags": {
  27. "host": "web02",
  28. "dc": "lga"
  29. }
  30. }
  31. ]

返回结果

返回结果根据参数不通,会有所不一样(具体可以参考下方示例)。不能仅通过HTTP response status是否为200来判断请求是否成功。如果带了summary或者details参数,即使写入有异常,返回也会是200,但是会在返回结果中带上异常带信息。

示例

下面我们将使用curl演示一下,首先准备一个req.json文件,内容如下:

  1. {
  2. "metric": "aliyun.opentsdb.test",
  3. "timestamp": 1543982710,
  4. "value": 100,
  5. "tags": {
  6. "tagK": "tagV"
  7. }
  8. }

1.不带任何参数

  1. curl -i -X POST -d @./req.json http://localhost:4242/api/put
  2. // 返回
  3. // 空

2.带上summary参数

  1. curl -i -X POST -d @./req.json http://localhost:4242/api/put?summary
  2. // 返回
  3. {
  4. "success": 1,
  5. "failed": 0
  6. }

注意这里因为默认使用的是非同步模式,即使你看到success为1,也不代表此时数据点真的已经写入完成。

3.带上details参数

  1. curl -i -X POST -d @./req.json http://localhost:4242/api/put?details
  2. // 返回
  3. {
  4. "success": 1,
  5. "failed": 0,
  6. "errors": [ ]
  7. }

我们看到会多一个errors,如果写入有异常会在这里面包含异常的数据点

4.带上sync和timeout参数

  1. curl -i -X POST -d @./req.json 'http://localhost:4242/api/put?sync&details&timeout=30000'
  2. // 返回
  3. {
  4. "success": 1,
  5. "failed": 0,
  6. "errors": [ ]
  7. }

返回结果没有区别,但是能保证数据已经被写入底层HBase了。

5.模拟一些异常情况,看看返回情况

  1. curl -i -X POST -d @./req.json 'http://localhost:4242/api/put?sync&details&timeout=30000'
  2. // 返回
  3. {
  4. "success": 0,
  5. "failed": 1,
  6. "errors": [
  7. {
  8. "datapoint": {
  9. "metric": "aliyun.opentsdb.test",
  10. "timestamp": 1543982710,
  11. "value": "100",
  12. "tags": {
  13. "tagK": "tagV"
  14. }
  15. },
  16. "error": "Storage exception: Mock exception."
  17. }
  18. ]
  19. }

这里虽然有异常,但是HTTP response status会是200。