Web API

本机 HTTP 接口，供配置工具、语言 SDK 的服务模式、现场排障页使用。真正用法是西门子式诊断：先看运行态、通道诊断、报警和过程数据质量，再按需读写过程数据。结构体映射只是辅助，不是主路径。

项	值
品牌	Darra Profinet Slave
产品	PROFINET IO Device
监听	仅本机回环；端口固定、不可配置（数字见 GET /api/info 的 port）
JSON	camelCase；枚举为字符串
鉴权	回环默认放行。配置了 Api:ApiKey 后，所有请求必须带 X-Darra-PnS-Api-Key
请求体上限	64 KB（超限 HTTP 413）
授权	无授权端点。授权只在配置工具注册 + 服务内部复查；未授权时 POST /api/start 失败

成功响应按各端点结构（启停带 ok），不叠加 success。失败统一：

{ "success": false, "message": "…", "code": 400, "errorCode": 0, "timestamp": "…" }

字段	说明
success	恒为 false
code	与 HTTP 状态码一致
message	事实描述。内部异常不进响应，查本机服务日志
errorCode	协议栈 / 包装层返回码；运行态失败取服务当前错误码；纯客户端错误（400 / 401 / 404 / 413）为 0
timestamp	本地时间

GET / 返回基础观测页（只看状态 / 过程数据，禁止配置）。JSON 服务信息在 GET /api/info。

---

端点总表

方法	路径	页	用途
GET	/	本页	基础观测页
GET	/api/info	本页	服务信息 + 端点清单
GET	/api/status	运行态	运行态快照
GET	/api/diag	诊断	诊断计数器 / AR / 事件簿
POST	/api/diag	诊断	标准通道诊断 add / update / remove
GET	/api/alarms	报警	活动报警
GET	/api/alarms/history	报警	报警历史（最近 500 条，时间升序）
POST	/api/alarms/ack	报警	确认单条活动报警
POST	/api/alarms/ack-all	报警	确认全部活动报警
POST	/api/alarm	报警	发送过程报警（设备→控制器）
GET	/api/io	过程数据	过程映像当前值
POST	/api/io	过程数据	写设备→控制器区（部分覆盖）
GET	/api/im	标识与记录	I&M 设备标识
GET	/api/records	标识与记录	用户区记录（Index 0x0000–0x7FFF）
POST	/api/start	启停与复位	启动从站
POST	/api/stop	启停与复位	停止从站（软停）
POST	/api/reset	启停与复位	复位
POST	/api/config/reload	启停与复位	重载运行配置

语言 SDK 也可以转发到本接口。用 HTTP 轮询过程数据只适合观测或一次性写入。

---

鉴权

未配置 Api:ApiKey：只接受本机回环。服务本身只监听回环，此分支为双保险。

配置了密钥后，所有请求（含 GET /api/info）必须带：

X-Darra-PnS-Api-Key: <密钥>

缺头或不匹配 → HTTP 401。比较为恒定时间。POST /api/config/reload 不热更新已加载的密钥，改密钥需重启服务。

---

GET /api/info

服务存活探测 + 端点清单。

{
  "serviceName": "DarraPnSService",
  "version": "1.0.0",
  "endpoints": [
    "GET / (Web 前端)",
    "GET /api/info",
    "GET /api/status"
  ]
}

字段	说明
serviceName	Windows 服务名
version	产品版本
port	固定监听端口（整数，不可配置）。以现场响应为准，不要在工程里写死
endpoints	已注册端点清单

---

GET /

返回内嵌观测页（状态 / 过程数据查看 + 输出区基础写入）。静态页缺失时回退为与 GET /api/info 相同的 JSON，保证存活探测不丢。

---

调用约定

• 请求体超过 64 KB → HTTP 413。
• 未知路径 / 方法不对 → HTTP 404，message 含方法与路径。
• 周期数据交换进行中调用 POST /api/stop / POST /api/reset / POST /api/config/reload 会打断正在交换的应用关系。先等控制器断开（GET /api/status 的 connected=false），再停、复位或重载。接口本身不因此返回 4xx。
• POST /api/start、写过程数据、诊断、报警不受上条限制。