通过 HTTP API 发送测量数据

任何能够发送带 JSON 正文的 HTTP 请求的系统，都可以向 FreeMaint Connect 提供数据：Node-RED、Home Assistant、读取 Modbus 的网关、PLC 或您自己的脚本。创建一个类型为“HTTP API（Node-RED、脚本…）”的连接，即可获得其 URL 和访问密钥。

请求

方法：POST，发送到创建连接时显示的 URL（以 /connect/ingest/generic 结尾）。
请求头 Authorization：Bearer 后接访问密钥。
请求头 Content-Type: application/json。
数据被接受时，FreeMaint 返回 202；数据会在数秒内完成存储。

请求正文

正文在 items 下列出设备。每台设备包含一个标识符（device）、一个可选的显示名称、一个可选的时间（ts，ISO 8601 格式）以及其数据点。每个数据点包含 key 和 value，最好还包含 unit 和 quantity。创建页面会显示一个可直接复制的完整示例。

数据点字段

key

该通道在此设备上的名称，例如 power 或 energy_total。相同的 key 始终写入同一个通道。

value

一个数字。

unit

例如 W、kWh、°C 或 mm/s。以 Wh 或 MWh 表示的电能会换算为 kWh，温度换算为 °C，振动速度换算为 mm/s。 Pa、hPa、kPa、mbar、psi、inH2O、inWC 或 mmH2O 表示的压力会换算为 bar。如需以其他单位读取通道，请在 FreeMaint 中选择其显示单位。通道页面会在“接收单位”下显示最新读数的单位。毫与兆区分大小写：mW 和 mWh 表示毫，MW 和 MWh 表示兆。也接受 BACnet 单位名称，不区分大小写：“PASCALS”、“inches-of-water”、“kilowatt-hours”……

quantity

所测量的物理量，例如 power、energy、temperature 或 vibration_velocity。FreeMaint 据此选择合适的单位和图表。

kind

对于只增不减的计数器（电能累计值、运行小时数），设为 CUMULATIVE，FreeMaint 随后会计算两次读数之间的用量。对于普通测量值，省略此字段即可。

限制

每个请求最多 500 台设备和 5000 个数据点。
每个连接每分钟最多 120 个请求；超出后 FreeMaint 返回 429，您的系统应稍后重试。
格式错误的请求会收到 400 响应并指明问题所在，便于修正配置有误的网关。
每个新通道都会计入您套餐的活动通道上限。

提示

典型配置：Node-RED 流程每分钟读取一次 Modbus 电能表并发送其数值；Home Assistant 自动化转发某个传感器的数据；Teltonika 路由器通过其 Data to Server 功能发送读数。

警告

请妥善保管访问密钥：任何持有它的人都可以向此连接发送数据。如果密钥可能已泄露，请生成新密钥并选择“立即吊销”。