使用 InfluxDB API 写入数据

使用 命令行界面、客户端库 和常见数据格式（如 Graphite）的插件将数据写入 InfluxDB。

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

使用 InfluxDB API 创建数据库

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

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

使用 InfluxDB API 写入数据

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

• 要使用 InfluxDB v1 API 写入数据库，请向 /write 端点发送 POST 请求。

  以下示例演示如何将一个点写入 mydb 数据库。点数据包括 measurement cpu_load_short、标签键 host 和 region 以及 标签值 server01 和 us-west、字段键 value 以及 字段值 0.64 以及 时间戳 1434055562000000000。

curl -i -XPOST 'https://127.0.0.1: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 'https://127.0.0.1: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（必需）
• 标签：严格来说，标签是可选的，但大多数序列都包含标签，以区分数据源并使查询变得简单高效。标签键和标签值都是字符串。
• 字段（必需）：字段键是必需的，并且始终是字符串，并且 默认情况下，字段值是浮点数。
• 时间戳：在行末尾以 Unix 时间（自 1970 年 1 月 1 日 UTC 以来的纳秒数）提供 - 是可选的。如果您未指定时间戳，则 InfluxDB 使用服务器的本地纳秒时间戳（Unix 纪元）。默认情况下，InfluxDB 中的时间采用 UTC 格式。

注意： 避免使用以下保留键：_field、_measurement 和 time。如果保留键作为标签或字段键包含在内，则关联的点将被丢弃。

配置 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 'https://127.0.0.1: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 'https://127.0.0.1:8086/write?db=mydb' --data-binary @cpu_data.txt

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

无模式设计

InfluxDB 是一个无模式数据库。您可以随时添加新的 measurement、标签和字段。请注意，如果您尝试写入的数据类型与之前使用的类型不同（例如，将字符串写入先前接受整数的字段），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 'https://127.0.0.1:8086/write?db=hamlet' --data-binary 'tobeornottobe booleanonly=true'

curl -i -XPOST 'https://127.0.0.1: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.11.8
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://127.0.0.1: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.11.8
Date: Wed, 01 Mar 2017 19:38:35 GMT
Content-Length: 45

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

后续步骤

现在您已经了解了如何使用 InfluxDB API 写入数据，请了解如何使用 查询数据 指南查询数据！有关使用 InfluxDB API 写入数据的更多信息，请参阅 InfluxDB API 参考。