文档文档

使用 InfluxDB API 写入数据

此页面记录了早期版本的 InfluxDB OSS。 InfluxDB OSS v2 是最新的稳定版本。 请参阅等效的 InfluxDB v2 文档: 将数据写入 InfluxDB

使用 命令行界面客户端库 以及通用数据格式(如 Graphite)的插件将数据写入 InfluxDB。

注意:以下示例使用 curl,这是一个使用 URL 传输数据的命令行工具。 通过 HTTP 脚本指南 了解 curl 的基础知识。

使用 InfluxDB API 创建数据库

要创建数据库,请向 /query 端点发送 POST 请求,并将 URL 参数 q 设置为 CREATE DATABASE <new_database_name>。 以下示例向在 localhost 上运行的 InfluxDB 发送请求,并创建 mydb 数据库

curl -i -XPOST http://localhost:8086/query --data-urlencode "q=CREATE DATABASE mydb"

使用 InfluxDB API 写入数据

InfluxDB API 是将数据写入 InfluxDB 的主要方式。

curl -i -XPOST 'http://localhost:8086/write?db=mydb'
--data-binary 'cpu_load_short,host=server01,region=us-west value=0.64 1434055562000000000'
  • 使用 InfluxDB 2.0 API(与 InfluxDB 1.8+ 兼容)写入数据库,请向 /api/v2/write 端点 发送 POST 请求
curl -i -XPOST 'http://localhost:8086/api/v2/write?bucket=db/rp&precision=ns' \
  --header 'Authorization: Token username:password' \
  --data-raw 'cpu_load_short,host=server01,region=us-west value=0.64 1434055562000000000'

写入点时,您必须在 db 查询参数中指定现有数据库。 如果您未通过 rp 查询参数提供保留策略,则点将写入 db 的默认保留策略。 有关可用查询参数的完整列表,请参阅 InfluxDB API 参考 文档。

POST 的正文或 InfluxDB 行协议 包含您要存储的时间序列数据。 数据包括

  • Measurement(测量) (必需)
  • Tags(标签):严格来说,标签是可选的,但大多数序列都包含标签,以区分数据源并使查询既简单又高效。 标签键和标签值都是字符串。
  • Fields(字段)(必需):字段键是必需的,并且始终是字符串,并且 默认情况下,字段值是浮点数。
  • Timestamp(时间戳):在行尾以 Unix 时间(自 1970 年 1 月 1 日 UTC 以来的纳秒数)提供 - 是可选的。 如果您未指定时间戳,则 InfluxDB 使用服务器的本地纳秒时间戳(Unix 纪元)。 默认情况下,InfluxDB 中的时间采用 UTC 格式。

注意: 避免使用以下保留键:_field_measurementtime。 如果保留键作为标签或字段键包含在内,则关联的点将被丢弃。

配置 gzip 压缩

InfluxDB 支持 gzip 压缩。 要减少网络流量,请考虑以下选项

  • 要接受来自 InfluxDB 的压缩数据,请将 Accept-Encoding: gzip 标头添加到 InfluxDB API 请求。

  • 要在将数据发送到 InfluxDB 之前压缩数据,请将 Content-Encoding: gzip 标头添加到 InfluxDB API 请求。

有关为客户端库启用 gzip 的详细信息,请参阅您的客户端库文档。

在 Telegraf InfluxDB 输出插件中启用 gzip 压缩

  • 在 Telegraf 配置文件 (telegraf.conf) 中,在 [[outputs.influxdb]] 下,将 content_encoding = "identity"(默认)更改为 content_encoding = "gzip"

注意 写入 InfluxDB 2.x [[outputs.influxdb_v2]] 的内容默认配置为 gzip 格式压缩。

写入多个点

通过用新行分隔每个点,同时将多个点发布到多个序列。 以这种方式批量处理点可以提高性能。

以下示例将三个点写入数据库 mydb。 第一个点属于 measurement(测量)为 cpu_load_short 且标签集为 host=server02 的序列,并具有服务器的本地时间戳。 第二个点属于 measurement(测量)为 cpu_load_short 且标签集为 host=server02,region=us-west 的序列,并具有指定的时间戳 1422568543702900257。 第三个点与第二个点具有相同的指定时间戳,但它被写入 measurement(测量)为 cpu_load_short 且标签集为 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'

从文件写入点

通过将 @filename 传递给 curl 从文件写入点。 文件中的数据应遵循 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 'http://localhost:8086/write?db=mydb' --data-binary @cpu_data.txt

注意: 如果您的数据文件包含超过 5,000 个点,则可能需要将该文件拆分为多个文件,以便将数据分批写入 InfluxDB。 默认情况下,HTTP 请求在五秒后超时。 InfluxDB 仍会在超时后尝试写入点,但无法确认它们是否已成功写入。

无模式设计

InfluxDB 是一个无模式数据库。 您可以随时添加新的 measurements(测量)、tags(标签)和 fields(字段)。 请注意,如果您尝试写入的数据类型与之前使用的类型不同(例如,将字符串写入先前接受整数的字段),InfluxDB 将拒绝这些数据。

关于 REST 的说明

InfluxDB 仅将 HTTP 用作方便且广泛支持的数据传输协议。

现代 Web API 已确定采用 REST,因为它解决了常见的需求。 随着端点数量的增长,对组织系统的需求变得迫切。 REST 是业界公认的组织大量端点的风格。 这种一致性对开发和使用 API 的人员都有好处:所有相关人员都知道会发生什么。

然而,REST 是一种约定。 InfluxDB 只需三个 API 端点即可完成工作。 这个简单易懂的系统使用 HTTP 作为 InfluxQL 的传输方法。 InfluxDB API 没有尝试成为 RESTful。

HTTP 响应摘要

  • 2xx:如果您的写入请求收到 HTTP 204 No Content,则表示成功!
  • 4xx:InfluxDB 无法理解该请求。
  • 5xx:系统过载或严重受损。

示例

将浮点数写入先前接受布尔值的字段
curl -i -XPOST 'http://localhost:8086/write?db=hamlet' --data-binary 'tobeornottobe booleanonly=true'

curl -i -XPOST 'http://localhost:8086/write?db=hamlet' --data-binary 'tobeornottobe booleanonly=5'

返回

HTTP/1.1 400 Bad Request
Content-Type: application/json
Request-Id: [...]
X-Influxdb-Version: 1.12.0
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 '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.12.0
Date: Wed, 01 Mar 2017 19:38:35 GMT
Content-Length: 45

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

下一步

既然您已经了解如何使用 InfluxDB API 写入数据,请了解如何使用 查询数据 指南查询数据! 有关使用 InfluxDB API 写入数据的更多信息,请参阅 InfluxDB API 参考


此页对您有帮助吗?

感谢您的反馈!


Flux 的未来

Flux 即将进入维护模式。 您可以继续像当前一样使用它,而无需对您的代码进行任何更改。

阅读更多

现已全面上市

InfluxDB 3 Core 和 Enterprise

快速启动。 更快扩展。

获取更新

InfluxDB 3 Core 是一个开源、高速、最新数据引擎,可实时收集和处理数据,并将其持久保存到本地磁盘或对象存储。 InfluxDB 3 Enterprise 以 Core 的基础为构建,增加了高可用性、读取副本、增强的安全性以及数据压缩,从而实现更快的查询和优化的存储。 InfluxDB 3 Enterprise 的免费层可供非商业家庭或业余爱好者使用。

有关更多信息,请查看