HTTP API 主站

HTTP API 主站将同一源站的 HTTP/HTTPS 资源映射为网关变量，支持 JSON Pointer 取值、数组分页和明确业务确认的写入。插件名称为“HTTP API 主站”，类型标识为 HttpApiMaster。公共设备、变量与权限操作见采集配置。

建立设备与配置变量

进入“开发配置 → 采集配置”，在“无通道”下新增 HTTP API 主站设备。填写源站和认证参数，保存并启用。该设备自行管理 HTTP 连接，无需创建 TCP 通道。

参数	说明
源站地址	HTTP/HTTPS 绝对地址，不得带用户名、密码或片段。变量 path 从源站根路径开始。
认证方式	None、Basic、Bearer、ApiKey。凭据只填设备属性，避免写入地址、变量名或截图。
API Key 请求头	ApiKey 模式的头名称，默认 X-API-Key。
默认请求头 JSON	字符串值对象，例如 {"Accept":"application/json"}。点位同名普通字段优先。
客户端证书名称、CA 名称	HTTPS 可选择受管客户端证书及私有信任 CA；客户端证书须有私钥。留空 CA 时使用系统信任，始终校验主机名。
使用系统代理	决定是否采用当前运行环境的系统代理。
请求超时毫秒	100–120000，默认 5000；分页全部请求共享此期限。
最大响应字节数	1–16777216，默认 1048576；分页时也是全部页原始正文的累计上限。
最大并行连接数	1–32，默认 4；连接排队计入总超时。
默认读取、写入方法	读取 GET/POST；写入 PUT/POST/PATCH/DELETE，变量地址可覆盖。

地址与取值

变量地址填写 JSON 对象，例如：

{"path":"/api/rooms/1?unit=celsius","pointer":"/data/temperature","readMethod":"GET","writeMethod":"PATCH","writePath":"/api/rooms/1","writeSuccessPointer":"/result/ok"}

地址字段	说明
path、writePath	同源且以 / 开始的相对路径与查询参数；writePath 可省略。拒绝跨源、凭据及片段。
pointer	空字符串取根值；/data/value 取成员，/items/0 取数组元素；~1 表示 /，~0 表示 ~。
readMethod、readBody	可选读取方法及任意 JSON 请求正文；默认使用设备读取方法。
writeMethod、contentType	可选写入方法及正文媒体类型，默认 application/json。
headers	点位字符串请求头对象。不能覆盖 Authorization、API Key、Cookie、Host 或传输控制字段。
writeSuccessPointer	配置后必须存在且为布尔 true；未配置时根对象 success:false 仍判失败。
pagination	配置 nextPointer 与 1–64 的 maxPages，默认 16；pointer 必须指向数组。下一页值为同源链接，null/空串表示结束。

数组分页示例：

{"path":"/api/items?page=1","pointer":"/items","headers":{"Accept":"application/json"},"pagination":{"nextPointer":"/next","maxPages":8}}

每页返回 {"items":[...],"next":"/api/items?page=2"}，最后一页 next 为 null。分页循环、页数或总正文超限均返回失败，不把半份数组更新到变量。此合同使用响应正文的下一页链接；不自动推测 token 或 Link 头。

标量选对应数值、Boolean 或 String 类型；数组和对象选 Object。空 pointer 的 String 变量也可接收纯文本。写正文按源站实际合同填写 JSON，不能把“请求发出”当作写成功。

使用地址字段编辑器

1. 在设备“实时变量”页新增或编辑变量，点击“变量地址”右侧的“字段编辑”。
2. 在“资源映射”填写资源路径和值指针。需要覆盖设备默认读取方法时，勾选对应字段；POST 读取可配置 JSON 正文。
3. 数组分页需勾选“数组分页”，填写下一页指针和最大页数；值指针必须定位数组。按需填写写入方法、路径、确认指针、普通请求头和媒体类型。
4. 点击“确认并回填”，检查生成的地址 JSON，再点击变量窗口的“确定”。重新打开字段窗口，核对分页和其他字段保存正确。

未勾选表示未设置并沿用该字段默认行为；勾选后的“空值”表示明确的 JSON null，两者不能混用。字段窗口的“取消”会放弃当前修改；认证凭据应在设备属性配置。

检查实时变量

保持当前设备，在采集工作区顶部切换到“实时变量”标签，核对地址、当前值、在线状态、采集时间、变化时间和错误。连续成功读取时采集时间推进；值未变化时变化时间可以保持不变。数组和对象显示有长度限制的内容摘要，完整分页结果可到专属调试读取页查看。

对授权测试资源写入后，先核对业务确认，再读回并确认变量更新。分页中任一页失败时，不把已收到的部分数组当作新值；具体失败应查看变量错误与读取结果。

协议调试与特殊方法

选中设备，打开顶部“协议调试”。第一个页签“核心状态”显示连接和请求状态；右侧依次提供“特殊方法”、读取、批量读取与写入。

使用工作区顶部“刷新”更新连接和最近响应摘要，当前输入与操作结果会保留。HTTP 资源地址中的“数组分页”控制实际请求的后续页，与工作区列表的显示分页分别使用。

1. 在“读取”填写完整变量地址 JSON，点击“读取一次”，检查值和最后响应时间。
2. 在“批量读取”每行填写一个地址，最多 32 项。逐项检查结果，某项失败不代表其它项失败。
3. 在“写入”核对目标与正文，点击“写入测试”并确认，再从读取页读回。DELETE 会执行远端删除语义，应仅操作授权测试资源。
4. 等待期间可取消。已发送的远端写入无法撤回，应读回确认最终状态。

状态区显示最近收到的 HTTP 状态码；源站返回 Retry-After 时同时显示等待提示，例如 7 表示建议等待七秒。后续响应没有该头时提示清除。收到 429 或业务失败时仍应检查读取结果，不能仅凭最近响应时间判定操作成功；插件不会据此自动重放写入。

读取数组分页时，结果区只在全部页校验通过后显示合并数组：

“特殊方法”中提供 ReadAddressAsync、ReadAddressesAsync、WriteAddressAsync；使用相同地址合同、认证、证书和限制。批量特殊方法的 addressesJson 是地址 JSON 字符串数组。

JSON 参数按方法参数顺序填写数组，可省略使用默认值的尾部参数，也可使用“字段编辑”。例如执行 ReadAddressAsync：

["{\"path\":\"/status\",\"pointer\":\"/value\"}"]

故障处理

现象	检查与处理
401/403	核对认证方式、凭据及源站授权；不要把凭据改写到查询字符串。
连接或 TLS 失败	核对 DNS、端口、代理、证书有效期、SAN 主机名及 CA；不能通过关闭校验解决。
HTTP 200 但写失败	核对业务确认指针，必须返回布尔 true；检查根对象 success=false。
Pointer 不存在	核对实际 JSON 结构、大小写、数组索引及转义。
分页失败	核对 next 结束值、同源地址、循环、页数和累计正文上限。
超时、429、5xx	检查源站负载与采集频率；写操作不自动重放，先读回再决定是否重试。

入站变量写入使用网关现有授权 API；数据上送使用 Webhook 等转发功能，本插件用于主动采集设备 API。