influxdb的Rest接口写入数据

上一节课,学习了使用命令行写入数据,这节课,我们学习使用Rest接口写入数据。

Rest接口比较简单,大家按照我们的方式做就可以了。但是必须确保,你自己安装了Influxdb,如果没有安装,请查看InfluxDb的简单安装


使用HTTP接口创建数据库

使用POST方式发送到URL的/query路径,参数qCREATE DATABASE <new_database_name>,下面的例子发送一个请求到本地运行的InfluxDB创建数据库mydb:

curl -i -XPOST http://localhost:8086/query --data-urlencode "q=CREATE DATABASE mydb"
  • curl -i 参数表示将显示请求和响应http协议信息。
  • curl -X 参数表示请求协议。
  • --data-urlencode 表示请求的参数进行url编码

执行如下图:

使用HTTP接口创建数据库


使用HTTP接口写数据

通过HTTP接口POST数据到/write路径是我们往InfluxDB写数据的主要方式。下面的例子写了一条数据到mydb数据库。这条数据的组成部分是measurement为cpu_load_short,tag的key为host和region,对应tag的value是server01us-west,field的key是value,对应的数值为0.64,而时间戳是1434055562000000000

curl -i -XPOST 'http://localhost:8086/write?db=mydb' --data-binary 'cpu_load_short,host=server01,region=us-west value=0.64 1434055562000000000'

执行结果:

influxdb写数据

验证数据是否写入成功:

influxdb写数据成功

当写入这条数据点的时候,你必须明确存在一个数据库名为mydb的数据库。想要获取更多参数的完整信息。

POST的请求体我们称之为行协议(Line Protocol),包含了你希望存储的时间序列数据。它的组成部分有measurement,tags,fields和timestamp。

  • measurement是InfluxDB必须的,你可以理解为表名。
  • 严格地说,tags是可选的,但是对于大部分数据都会包含tags用来区分数据的来源,让查询变得容易和高效。tag的key和value都必须是字符串。
  • fields的key也是必须的,而且是字符串,默认情况下field的value是float类型的。
  • timestamp在这个请求行的最后,是一个从1/1/1970 UTC开始到现在的一个纳秒级的Unix time,它是可选的,如果不传,InfluxDB会使用服务器的本地的纳米级的timestamp来作为数据的时间戳,注意无论哪种方式,在InfluxDB中的timestamp只能是UTC时间。

同时写入多个数据

要想同时发送多个数据点到多个series(在InfluxDB中measurement加tags组成了一个series),可以用新的行来分开这些数据点。这种批量发送的方式可以获得更高的性能。

下面的例子就是写了三个数据点到mydb数据库中。 - 第一个点所属series的measurement为cpu_load_short,tag是host=server02,timestamp是server本地的时间戳; - 第二个点同样是measurement为cpu_load_short,但是tag为host=server02,region=us-west,且有明确timestamp为1422568543702900257的series; - 第三个数据点和第二个的timestamp是一样的,但是series不一样,其measurement为cpu_load_short,tag为direction=in,host=server01,region=us-west

curl -i -XPOST 'http://localhost:8086/write?db=mydb' --data-binary 'cpu_load_short,host=server02 value=0.67
cpu_load_short,host=server02,region=us-west value=0.55 1422568543702900257
cpu_load_short,direction=in,host=server01,region=us-west value=2.0 1422568543702900257'

执行后表中的数据如下:

influx-data


写入文件中的数据

可以通过curl@filename来写入文件中的数据,且这个文件里的数据的格式需要满足InfluxDB的行语法。

给一个正确的文件(cpu_data.txt)的例子:

cpu_load_short,host=server02 value=1.67
cpu_load_short,host=server02,region=us-west value=1.55 1422568543702900257
cpu_load_short,direction=in,host=server01,region=us-west value=12.0 1422568543702900257

看我们如何把cpu_data.txt里的数据写入mydb数据库:

curl -i -XPOST 'http://localhost:8086/write?db=mydb' --data-binary @cpu_data.txt

说明:如果你的数据文件的数据点大于5000时,你必须把他们拆分到多个文件再写入InfluxDB。因为默认的HTTP的timeout的值为5秒,虽然5秒之后,InfluxDB仍然会试图把这批数据写进去,但是会有数据丢失的风险。

上面的rest请求执行的结果:

influxdb-批量插入数据

注意查询出的数据是按照时间排序的,不是按照插入的顺序排列的。


无模式设计

InfluxDB是一个无模式(schemaless)的数据库,你可以在任意时间添加measurement,tags和fields。

注意:如果你试图写入一个和之前的类型不一样的数据(例如,filed字段之前接收的是数字类型,现在写了个字符串进去),那么InfluxDB会拒绝这个数据。这也差不多是Influxdb对数据类型较少的限制之一了,建议你一定要记住。


对于REST的一个说明

InfluxDB使用HTTP作为方便和广泛支持的数据传输协议。

现代web的APIs都基于REST的设计,因为这样解决了一个共同的需求。因为随着终端数量的增长,组织系统的需求变得越来越迫切。REST是为了组织大量终端的一个业内认可的标准。这种一致性对于开发者和API的消费者都是一件好事:所有的参与者都知道期望的是什么。

REST的确是很方便的,而InfluxDB也只提供了三个API,这使得InfluxQL在翻译为HTTP请求的时候很简单便捷。


Rest请求返回值介绍及常见错误

Rest调用的时候,会返回http状态码,这些状态码,代表着influxdb的一些状态,如下:

  • 2xx:如果你写了数据后收到HTTP 204 No Content,说明写入成功了!
  • 4xx:表示InfluxDB不知道你发的是什么鬼,可能是你的http请求哪里出错了,请检查一些http的参数。
  • 5xx:系统过载或是influxdb崩溃,暂时不可用。

举几个返回错误的例子:


两次写入值类型不一样

还是在mydb中写入数据,第一次booleanonly接收的是布尔值,第二次booleanonly是一个浮点值,两次值不一样

curl -i -XPOST 'http://localhost:8086/write?db=mydb' --data-binary 'table1 booleanonly=true'  
curl -i -XPOST 'http://localhost:8086/write?db=mydb' --data-binary 'table1 booleanonly=5'

这时系统返回:

HTTP/1.1 400 Bad Request
Content-Type: application/json
Request-Id: [...]
X-Influxdb-Version: 1.2.x
Date: Wed, 01 Mar 2017 19:38:01 GMT
Content-Length: 150

{"error":"field type conflict: input field \"booleanonly\" on measurement \"tobeornottobe\" is type float, already exists as type boolean dropped=1"}

注意,第一条语句是插入成功的,第二条错误。上面返回了400错误码,也返回了一段json,json中说得很清楚,类型冲突,


写入数据到一个不存在的数据库中:

curl -i -XPOST 'http://localhost:8086/write?db=atlantis' --data-binary 'liters value=10'

返回值:

HTTP/1.1 404 Not Found
Content-Type: application/json
Request-Id: [...]
X-Influxdb-Version: 1.2.x
Date: Wed, 01 Mar 2017 19:38:35 GMT
Content-Length: 45

{"error":"database not found: \"atlantis\""}

下一步

现在你已经知道了,如何通过HTTP API写入数据了,下面我们来看看怎么通过读数据来读出它们。