InfluxDB作为一款流行的时序数据库，除了提供各语言官方客户端之外，还暴露了完整的HTTP API。掌握这些接口之后，即使在没有现成SDK的环境里，比如嵌入式设备、低代码平台或者简单的脚本任务中，也能轻松完成数据写入和查询。本文以InfluxDB 1.x版本为例，讲解write和query两个核心接口的使用方法。
一、通过write接口写入数据
InfluxDB的写入接口地址是/write，请求方式为POST，数据格式采用行协议（Line Protocol）。行协议的基本结构是：measurement加逗号加tag键值对，再加空格分隔field键值对，最后是可选的时间戳。例如一条CPU监控数据可以写成cpu,host=server01,region=cn usage=0.64 1700000000000000000。
调用接口时需要通过db参数指定目标数据库，通过precision参数指定时间戳精度，可选值包括ns、u、ms、s、m和h。如果不传时间戳，服务端会使用服务器当前时间，这在采集端时钟不准确的场景下比较有用。下面是一个完整的curl写入示例：
curl -i -XPOST 'http://localhost:8086/write?db=mydb&precision=s' \ --data-binary 'cpu,host=server01,region=cn usage=0.64,memory=72.5 1700000000'
写入成功时返回HTTP 204状态码，没有响应体。如果返回400，通常是行协议格式有错误，比如tag和field之间误用了逗号；如果返回404，多半是数据库不存在，需要先通过/query接口执行CREATE DATABASE创建库。
批量写入是提升性能的关键。一次请求中可以在body里放多行数据，每行一条记录，用换行符分隔。相比逐条写入，批量写入能大幅减少HTTP连接开销，官方建议每次批量几百到几千条为宜。另外，开启gzip压缩（请求头加Content-Encoding: gzip）也能显著降低网络传输量，对于跨机房上报的场景尤其有效。
二、通过query接口查询数据
查询接口地址是/query，默认使用GET方法，把InfluxQL语句放在q参数中。查询同样需要指定db参数。最简单的例子：
curl -G 'http://localhost:8086/query?db=mydb' \ --data-urlencode 'q=SELECT * FROM cpu LIMIT 5'
注意这里使用了curl -G配合--data-urlencode，这样查询语句会被正确编码后附加到URL上，避免特殊字符导致的问题。返回结果是JSON格式，数据放在results数组下的series中，包含columns列名和values数据行两个部分，解析时按索引对应即可。
实际查询中经常需要加时间范围条件。InfluxQL支持WHERE time > now() - 1h这样的相对时间写法，也支持绝对时间戳。聚合分析则依赖GROUP BY time()配合聚合函数，比如统计每5分钟的平均CPU使用率：
curl -G 'http://localhost:8086/query?db=mydb' \ --data-urlencode 'q=SELECT mean(usage) FROM cpu WHERE time > now() - 6h GROUP BY time(5m) fill(null)'
fill(null)用于控制空时间桶的填充方式，可选值还有fill(0)、fill(previous)等，在画监控图表时很实用。此外，还可以通过GROUP BY host按tag分组统计，tag在InfluxDB中是建了索引的，过滤性能远好于field，设计数据模型时应把常用于过滤的维度放到tag里。
查询较长时建议改用POST方式提交，把q放进请求体，避免URL超长被网关或代理截断。如果开启了chunked流式响应，加上chunked=true参数可以让结果分块返回，对大时间跨度的查询能减少客户端等待时间。
三、认证鉴权与常见问题处理
生产环境通常会开启认证。开启后每个请求需要带上u和p参数传递用户名密码，或者使用Authorization: Token请求头。curl示例如下：
curl -G 'http://localhost:8086/query?db=mydb&u=admin&p=secret123' \ --data-urlencode 'q=SELECT count(usage) FROM cpu'
除了认证问题，日常调试中还有几类高频错误值得注意。第一类是写入返回partial write，说明批次里部分数据点的时间戳与已有数据类型冲突，比如同一个field先是浮点数又是字符串，InfluxDB的field类型在首次写入时就固定了，类型不一致只能换field名或新建measurement。第二类是查询返回database not found，多因db参数拼写错误。第三类是查询有数据但聚合结果为空，通常是WHERE条件里的field比较只支持时间，其他条件必须针对tag，这一点和SQL的习惯差异较大。
关于性能，还有两个参数值得关注。写入时可以设置rp参数指定保留策略（Retention Policy），让不同时效的数据落到不同策略中自动清理；查询时对超大结果集务必加上LIMIT或时间范围限定，避免一次性拉取千万行数据把内存打爆。只要遵循批量写入、tag建模、范围查询这几个原则，HTTP API完全能支撑起一套稳定的监控数据采集方案。