跳到主要内容

外部程序联动

边缘不支持的设备也可以通过边缘的数据模型接入。

HTTP 连接界面 — 接收外部推送值的位置

外部程序读取值后，通过 HTTP 推送，该值将被视为边缘直接采集的 标签。平台传输、历史、报警、流程都会正常关联。无需 新建驱动。

何时使用
  • 边缘 没有对应驱动 的协议设备
  • 已有读取值的 现有系统 (MES · SCADA · 自有采集器)
  • 需要上传经过计算、加工后的值时

如何运作​

HTTP 连接 不负责采集。它只是 缓存 收到的值。

외부 프로그램  ──HTTP──▶  엣지의 값 캐시  ──timecycle 주기로 샘플링──▶  태그 이력 · 플랫폼

明明推送了，为什么值会消失​

因为外部是推送，而边缘内部仍然是轮询。

其他驱动是由边缘直接轮询设备。HTTP 连接只是在该“设备”位置上放置了缓存， 而 读取缓存的一方同样是轮询。因此，如果推送方和读取方的节奏 不一致，值就会出现偏差。

外部 → 边缘边缘 → 历史
方式推送 (外部按需)轮询 (timecycle 周期)
若错过—周期之间的值只保留最后一个
MQTT · Kafka · WebSocket 都是如此

接收消息的驱动 全部是相同结构。它们将来自代理的消息覆盖为“最后的值” 一个，然后由采集调度器按周期读取。

驱动值来源
HTTP外部程序的请求
MQTT Client订阅的主题
Kafka消费者收到的记录
WebSocket接收到的帧

因此，“发布到代理的消息数远多于采集到的记录数”是正常的。如果代理的 LAG 为 0，说明边缘已全部接收 — 只是历史记录中每个周期仅保留一条。曾有案例 将此误认为是数据丢失而进行长时间排查 （现场案例集）。

由于此结构，会带来一些特性。请先理解再开始使用。

特性含义
推送的值 不会立即保存会按连接的 timecycle 周期进行采样
若推送频率 快于周期，中间值会丢失仅保留最后的一个值
若推送频率 慢于周期，相同的值会被重复保存会持续读取缓存中剩余的值

若要加快反映速度，请缩短 timecycle。 此值即为反映延迟。 若为 1000（1秒），则最多延迟 1 秒后保存；减至 200，则最多延迟 0.2 秒。最小值为 100（0.1秒）。

期望效果timecycle
几乎即时反映100 ~ 200
常规实时监控1000
变化缓慢的值（温度、液位）5000 以上
即使缩短周期，也并非“全量”

缩短周期可减少延迟，但 仅读取最后一个值 的特性不变。若一个周期内 值变化了三次，则只保留最后一个。

如果需要确保所有事件无一遗漏，此方式并不适用。无论周期设置得多么 密集都无济于事。

缩短周期会增加负载

该连接下的 所有标签 都会按此周期被读取。如果标签较多的连接将周期 降至 100，负载会相应增大。仅为需要快速响应的标签单独创建 HTTP 连接，仅针对该连接 降低周期会更好。

步骤 1 — 创建 HTTP 连接​

在界面中进入 连接 → 添加 → HTTP。

https://<엣지 주소>/ui/connect/http

HTTP 连接 没有任何驱动选项。虽然有 IP 和端口字段，但驱动不会读取 — 仅仅是形式上的输入，所以填入任意值都不影响运行。

也可以使用 REST 方式创建。八个字段全部为必填项。

curl -X POST https://<엣지 주소>/api/v1/opc \
  -H 'X-API-Key: <API 키>' \
  -H 'Content-Type: application/json' \
  -d '{
    "opc_id":        "OPC_EXTERNAL_01",
    "opc_name":      "외부 수집기",
    "opc_type":      "HTTP",
    "site_id":       "SITE_00001",
    "opc_agent_ip":  "127.0.0.1",
    "opc_agent_port": 80,
    "timecycle":     1000,
    "async":         false
  }'
字段规则
opc_id以 OPC_ 开头，大写字母、数字、下划线，1~60 个字符
site_id以 SITE_ 开头
opc_type必须 精确为 HTTP。否则，值推送将被拒绝
opc_agent_port1~65535
timecycle100 以上（毫秒）。此值即为采样周期
缺少任意一项，行为将与界面不同

通过界面创建时，界面会自动填充缺失的值。因此，仅当使用 REST 方式创建时，才会因字段缺失 而导致连接虽建立但无法运行。

步骤 2 — 注册标签并获取 tag_id​

在该连接下创建标签。一个值对应一个标签。

请根据值特性选择数据类型。 即使值是字符串，只要声明的类型匹配，就能正确 解析。反之，如果类型不正确，则会在加载阶段抛出异常。

值类型
电流 · 温度 · 电压 · 重量 · 速度 · 坐标Double
电池 · 错误码 · 计数器Integer
报警 · 状态 · 区域 · 方向 · 颜色String

推送时使用的 tag_id 可通过标签列表界面或标签查询 API 确认。

步骤 3 — 推送值​

curl -X POST https://<엣지 주소>/api/v1/tag/<tag_id>/value \
  -H 'X-API-Key: <API 키>' \
  -H 'Content-Type: application/json' \
  -d '{"value":"1500"}'

值 也可以以字符串形式发送。将根据标签声明的类型进行解析。

认证​

/api/ 以下全部需要认证。没有密钥将被阻止 — 即使配置缺失也不会 开放。

方法形式
请求头 （推荐）X-API-Key: <key>
请求头Authorization: Bearer <key>
浏览器会话登录状态下无需密钥即可通过
查询参数不可用

?api_key=… 在 v1 中已移除。 使用会返回 401。请勿照搬旧示例。

请使用 HTTPS 调用​

默认值为 仅限 HTTPS。若以 http:// 调用，会返回 403。

值未进入时​

按顺序排查。

  1. 连接是否已启动 — 若为停止状态，则拒绝接收值。请在界面中启动该 连接。
  2. opc_type 是否为 HTTP — 无法向其他类型的连接推送值。
  3. 是否使用了 HTTPS 调用 — http:// 会返回 403。
  4. 是否通过请求头发送了密钥 — 查询参数会返回 401。
  5. tag_id 是否正确 — 请从标签列表中再次确认。
  6. 是否等待了周期 — 推送的值不会立即保存。请等待 timecycle 后再查看 历史。

了解事项​

每次只能推送一个值。 不存在一个请求可推送多个标签的端点。请为每个标签 分别调用。

即使在双活配置中也能接收。 即使是不具写权限的边缘，也能持续接收通过 HTTP 推送的值。这是 特意设计的，以确保外部联动不会因双活切换而中断。

存在旧端点。 POST /api/http 是旧式方法，通过 opc_id 和 plc_address 指定目标。 该功能将于 2026年12月31日 废弃。 它不适用速率限制和重复预防，因此 新建的联动请使用上述的 /api/v1/tag/{tag_id}/value。

相关文档​