文档

通过HTTP API写入数据

更新时间:
一键部署

有很多方法可以向TSDB For InfluxDB®写入数据,包括通过命令行界面(command line interface)和客户端(client libraries)。在这一章中,我们将向您展示如何使用内嵌的HTTP API写入数据。

说明

本章节中的示例使用了curl,一种通过URL来传输数据的命令行工具。

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

单点写入

下面的例子展示了如何将一个数据点写入mydb数据库。其中,该数据点的measurement为cpu_load_short,有两个tag,tag key分别为hostregion,对应的tag value分别为server01us-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
说明

如果您的一个文件中有超过5000个数据点,建议将该文件拆分成多个文件,以便将数据批量写进TSDB For InfluxDB®,因为HTTP请求默认在5秒后超时,虽然写入请求超时后,TSDB For InfluxDB®依旧会尝试将这些数据点写入数据库,但是并不保障数据一定会写入成功。

Schemaless(无模式)的设计

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

注意

如果您尝试写入跟之前类型不同的数据(例如,field原来接收的是整型数据,现在却写了一个字符串进去),TSDB For InfluxDB®会拒绝这些数据。

关于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®.

  • 本页导读 (1)
文档反馈