写入接口怎么用
InfluxDB 2.x 对外只有一个写入入口：POST /api/v2/write，查询参数声明 org、bucket 与 precision，请求头用 Token 鉴权，请求体是行协议文本，一行代表一个数据点。写入成功返回 204 且没有响应体，参数或行协议出错时返回 400，响应体会说明具体原因。官方客户端、Telegraf 与自研采集器走的都是这个接口，批量与压缩策略直接决定写入吞吐。
批量与压缩
采集器通常按批发送，一次几百到几千行，请求体支持 gzip，压缩后带宽占用通常能降到三分之一左右。自研采集器守住三件事就够了：复用连接、批量发送、开启压缩。行协议里标签值与字段值中的空格、逗号、等号需要转义，否则整行会被解析成错误的测量或字段。
基本信息
| 接口 | POST /api/v2/write?org=<org>&bucket=<bucket>&precision=ns |
|---|---|
| 请求头 | Authorization: Token <token>；Content-Type: text/plain; charset=utf-8；压缩时加 Content-Encoding: gzip |
| 请求体 | 行协议文本：measurement,tag=value field=value timestamp |
| 返回码 | 204 成功；400 行协议或参数错误；401 鉴权失败；404 bucket 不存在；413 请求体超限 |
| 适用版本 | InfluxDB 2.x；1.x 的写入接口是 POST /write?db=<db> |
最小示例
最小示例
# 写一个点：measurement,tag=value field=value timestamp
curl -i -XPOST "http://127.0.0.1:8086/api/v2/write?org=my-org&bucket=my-bucket&precision=s" \
-H "Authorization: Token $INFLUX_TOKEN" \
--data-binary 'cpu,host=web-1 usage=0.73 1719792000'
# 压缩上传：先 gzip 再发送，省带宽
gzip -c data.lp | curl -XPOST "http://127.0.0.1:8086/api/v2/write?org=my-org&bucket=my-bucket&precision=ns" \
-H "Authorization: Token $INFLUX_TOKEN" -H "Content-Encoding: gzip" --data-binary @-
# 时间戳单位由 precision 决定，写毫秒数据必须传 ms
curl -i -XPOST "http://127.0.0.1:8086/api/v2/write?org=my-org&bucket=my-bucket&precision=ms" \
-H "Authorization: Token $INFLUX_TOKEN" --data-binary 'mem,host=web-1 used=1024 1719792000000'典型使用场景
- 自研采集器按批推送指标，避免逐点发送带来的连接开销
- 历史数据导入：把行协议文件批量灌进 bucket
- 联调排查：命令行手工写一条数据，验证 Token 与 bucket 是否正确
- 压测验证：用同一接口测写入吞吐与存储引擎压力
- 数据回填：补写缺失时间段的数据，保持时间线连续
返回码处理
| 返回码 | 含义 | 处理方式 |
|---|---|---|
| 204 | 写入成功且无响应体 | 按批次继续写 |
| 400 | 行协议或参数错误 | 响应体给出行级原因，记录原文 |
| 401 | Token 无效或权限不足 | 检查 Token 的写权限与有效期 |
| 404 | bucket 不存在 | 核对 bucket 名称与 org |
| 413 | 请求体超过上限 | 缩小批次体积后重发 |
precision 决定时间戳的解释单位，与数据实际单位错配时写入依然返回 204，数据却会落到错误的时间点，只能靠查询时间范围来核对。
忽略非 204 返回码继续写入会静默丢数据：400 记录原文并告警，401 与 404 停止重试，只有 5xx 才值得退避重试。