进阶 · 10 分钟

HTTP 接口触发与幂等

MES 调一个接口就能出纸。难的不是「能调通」,是「调重了不会多打一张」——这是接口对接和接口对接到不出错的分界线。

两个必须理解的规则

必须带数据行

请求里要有 rows,一条数据一行。空请求不触发打印——这样「调通了但没数据」不会被误当成一次打印任务。

默认按请求 ID 判重

同一个请求 ID 在保留期内只处理一次。不按报文内容判重——因为产线上「同一张标连打两张」是合法业务,按内容去重会吞单。

第 1 步:建流程,加 HTTP 触发节点

给触发节点起个别名(如 line3-print),别名就是接口路径的一部分,改名等于换地址,联调后别乱改。

幂等配置两项:

  • 判重字段:默认取请求 ID(如 request_id)
  • 保留时长:重复请求在多长时间内算重投,例如 86400 秒(一天)

如果对接方连请求 ID 都给不了,才改成「按报文指纹」判重——这是降级方案,要先确认业务上不存在合法的重复报文。

第 2 步:接加工与出纸

HTTP 触发(别名=line3-print,幂等=request_id,保留 86400s)
 → 条件过滤(material_no 非空 且 qty > 0)
 → 字段加工(机台={{machine}},班次={{shift}},日期={{#date}})
 → 条件分叉(qty >= 500 => 1 / * => 2)
 → 打印机(出口 1 → 3 号线;出口 2 → 本机)
 → 记录(runId + 来源)

第 3 步:发一次请求

curl -X POST "http://<本机IP>:<端口>/api/v1/flow/line3-print" \
  -H "Content-Type: application/json" \
  -d '{
    "request_id": "MO-20261116-0001",
    "rows": [
      {"material_no":"A-1001","qty":12,"machine":"MJ-03","shift":"早班"}
    ]
  }'

具体端口、鉴权头与字段名以软件内该节点的说明为准,不同版本可能略有差异。

第 4 步:重投验幂等

把同一条请求原样再发一次。正确的行为是:

  • 返回 409,并且带上原来那次的 runId
  • 一张纸都不多出
  • 运行记录里只有一次执行

如果第二次又打了一批,说明幂等没开、或判重字段没对上(比如字段名写成了 requestId)。

联调顺序(少走弯路)

  1. 先本机用 curl 打通,确认出纸与字段都对
  2. 再跨机从 MES 服务器调,检查防火墙与端口
  3. 最后压重投故意连发三次同一个请求 ID,确认只打一次
  4. 留一份样例报文给客户 IT,写在交接文档里

常见问题

返回 404 / 找不到流程

三种可能:流程没发布(草稿不执行)、流程没启动、别名打错。发布与启动是两个动作,都要做。

返回成功但没出纸

看运行记录:如果节点在「条件过滤」处就结束了,说明数据行被过滤掉了(字段为空或不满足条件);如果卡在「刷新数据源」,说明查不到关联数据,这一路被停住。

重投时返回 200 不是 409

请求 ID 不相同(比如对方每次都生成新 ID),或者判重字段配的不是这个字段。跟对接方确认 ID 的生成规则——必须是业务幂等的 ID,不能是随机 UUID。

能不能直接调打印机端口 9100?

不能,那是打印机原始指令通道。接口触发要打到 LabelGo 的开放接口上,由软件负责模板、流水号、防重与记录。

并发调用会怎样?

同一时刻最多 2 批在处理,多余的排队(最多 20 批),队列满会丢批并写警告日志。上游要有节流,别一次推一百批。


相关:落盘出标 · 故障排查 · 注塑案例(M5)