通过HTTP API写入数据

通过HTTP API发送POST请求到/write路径是数据写入TSDB For InfluxDB®的主要方式。假设已经成功创建好数据库mydb，现在我们来探索如何通过HTTP API将数据写入mydb。

单点写入

下面的例子展示了如何将一个数据点写入mydb数据库。其中，该数据点的measurement为cpu_load_short，有两个tag，tag key分别为host和region，对应的tag value分别为server01和us-west，field key是value，field value是0.64，timestamp是1434055562000000000：

curl -i -XPOST 'https://<网络地址>:3242/write?db=mydb&u=<账号名称>&p=<密码>' --data-binary 'cpu_load_short,host=server01,region=us-west value=0.64 1434055562000000000'

• <网络地址>是您购买的TSDB For InfluxDB®实例的地址。

• <账号名称>和<密码>分别是您设置的用户账号和密码。

• TSDB For InfluxDB®默认使用端口3242。

• 数据写入的时候，需要设置参数db的值，该值必须是一个已有的数据库。如果您没有通过参数rp来设置数据保留策略的话，那么数据会写到db默认的数据保留策略中。

想要获得完整的参数信息，请参阅文档HTTP API。

我们称POST的主体内容，包含你想要存储的时序数据，为行协议（Line Protocol），它的组成部分有measurement、tags、fields和timestamp。TSDB For InfluxDB®要求时序数据必须有measurement。严格来讲，tag是可选的，但是大多数时序数据都会包含tag，用于区分数据的来源，使查询变得简单和高效。tag key和tag value都必须是字符串。field key也是必须的，并且必须是字符串，field value默认的数据类型是float。时间戳放在行的最后，是一个从UTC 1970年1月1日起到现在的纳秒级的Unix时间，它是可选的，如果没有明确给出时间戳，TSDB For InfluxDB®会把服务器本地的纳秒级的Unix时间当作数据点的时间戳。在TSDB For InfluxDB®中，任何时间戳都是UTC时间（协调世界时）。

多点写入

通过用换行符来分隔多个数据点，可以将它们同时发送到多个时间序列，这种批量发送的方式可以获得更高的性能。

下面的例子展示了将3个数据点写入数据库mydb。

• 第一个点属于measurement为cpu_load_short、tag为host=server0的时间序列，timestamp是服务器本地的时间戳。

• 第二个点属于measurement为cpu_load_short、tag为host=server02,region=us-west的时间序列，有明确的时间戳，timestamp为142256854370290025。

• 第三个点跟第二个点的时间戳一样，但是该数据点属于measurement为cpu_load_short、tag为direction=in,host=server01,region=us-west的时间序列。

curl -i -XPOST 'https://<网络地址>:3242/write?db=mydb&u=<账号名称>&p=<密码>' --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'

文件写入

curl通过@filename的方式，将文件中的数据点写入TSDB For InfluxDB®。文件中的数据需要满足行协议的语法。

以下是格式正确的文件（cpu_data.txt）的一个示例：

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

通过以下命令将文件cpu_data.txt里的数据写入数据库mydb：

curl -i -XPOST 'https://<网络地址>:3242/write?db=mydb&u=<账号名称>&p=<密码>' --data-binary @cpu_data.txt

Schemaless（无模式）的设计

TSDB For InfluxDB®是一个Schemaless的数据库。您可以在任意时间添加新的measurement、tags和fields。

关于REST的说明

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

现代Web的API都基于REST的设计，因为它解决了一个共同的需求。随着终端数量的增加，对组织系统的需求变得越来越迫切。REST是一个工业界认定的用来组织大量终端的标准。这种一致性对于API的开发者和消费者都有好处：每个参与者都知道期望的是什么。

然而，REST只是一个惯例。TSDB For InfluxDB®是一个简单、易懂的系统，只提供三个API端点，使用HTTP作为InfluxQL的传输方法。所以TSDB For InfluxDB® API并不试图完全符合RESTful的标准。

HTTP返回值概要

• 2xx：如果您发送写请求后返回信息HTTP 204 No Content，说明数据成功写入TSDB For InfluxDB®了！

• 4xx：表示TSDB For InfluxDB®不知道您发的是什么请求。

• 5xx：系统过载或着严重受损。

下面举几个返回错误的例子：

• field value原来是布尔类型的，现在写入浮点数：

curl -i -XPOST 'https://<网络地址>:3242/write?db=<数据库名称>&u=<账号名称>&p=<密码>' --data-binary 'tobeornottobe booleanonly=true'

curl -i -XPOST 'https://<网络地址>:3242/write?db=<数据库名称>&u=<账号名称>&p=<密码>' --data-binary 'tobeornottobe booleanonly=5'

系统会返回：

HTTP/1.1 400 Bad Request
Content-Type: application/json
Request-Id: [...]
X-Influxdb-Version: 1.7.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"}

• 将数据写入到一个不存在的数据库：

curl -i -XPOST 'https://<网络地址>:3242/write?db=atlantis&u=<账号名称>&p=<密码>' --data-binary 'liters value=10'

系统会返回：

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

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

后续任务

现在您已经知道了如何使用TSDB For InfluxDB®内置的HTTP API来写入数据，下一步，我们将在文档通过HTTP API查询数据中学习如何将数据读出来。若想获取更多关于如何使用HTTP API写入数据的信息，请查阅文档HTTP API。

InfluxDB® is a trademark registered by InfluxData, which is not affiliated with, and does not endorse, TSDB for InfluxDB®.