帮助中心

Appearance

3. 快速开始：一条最小可跑链路 ​

本节给出从零到验收的 8 个步骤。示例中的 <控制台地址>、admin、<明文密码>、4 均为占位符，执行前请替换为实际值。

【注意】以下示例统一用 -k 跳过自签证书校验；DC 为第 2 步查到的 deviceCode。

bash
BASE="https://<控制台地址>:8095"
API="$BASE/api/mlinkClient"

3.1 第 1 步：登录拿 token ​

bash
PWD_MD5=$(md5 -q -s '<明文密码>')          # macOS；Linux 用 printf '%s' '<明文密码>' | md5sum | cut -d' ' -f1

TOKEN=$(curl -sk -X POST "$API/system/login" \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode "login_name=admin" \
  --data-urlencode "password=$PWD_MD5" \
  | sed -n 's/.*"token":"\([^"]*\)".*/\1/p')

AUTH="Authorization: Bearer $TOKEN"
echo "$TOKEN"

响应片段：

json
{ "code": 200, "msg": "登录成功", "data": { "token": "xxxxxxxx", "expire": 86400 } }

3.2 第 2 步：查连接列表，拿到 deviceCode ​

bash
curl -sk "$API/system/conn/list" -H "$AUTH"

响应片段：

json
{
  "code": 200,
  "msg": "ok",
  "data": {
    "all": {
      "total": 1,
      "list": [
        { "id": 4, "deviceCode": "4", "nickName": "测试网关A", "host": "192.168.1.100", "port": "8090", "status": 1 }
      ]
    },
    "add": { "total": 1, "list": [] },
    "discover": { "total": 0, "list": [] }
  }
}
bash
DC=4        # ← 用上一步返回的 deviceCode 覆盖

已实测（2026-09-12，31 条连接的现场）：data 下三个分组都存在 ——
data.all.total=31（全部连接）、data.add.total=31（可添加/已纳管）、data.discover.total=0（待发现）。
取 deviceCode 用 data.all.list[].deviceCode ✓

3.3 第 3 步：确认驱动已安装，并取驱动表单字段 ​

bash
curl -sk -X POST "$API/config/driver/list/$DC" -H "$AUTH" \
  -H 'Content-Type: application/json' \
  -d '{"limit":{"page":1,"limit":999},"filter":{"type":"das"}}'

curl -sk "$API/config/driver/conf/$DC?name=PLC_Siemens_S7_Ethernet" -H "$AUTH"

driver/list 响应片段：

json
{ "count": 1, "drivers": [ { "name": "PLC_Siemens_S7_Ethernet", "version": "1.0.0", "type": "das", "desc": "" } ] }

driver/conf 返回原始 JSON 文本（驱动动态表单定义），其中每个字段的 key 就是后续建服务/建通道时 para 的字段名。

3.4 第 4 步：建采集服务 ​

bash
curl -sk -X POST "$API/config/das/insert/$DC" -H "$AUTH" \
  -H 'Content-Type: application/json' \
  -d '{
        "app": [{
          "name": "SVC_A",
          "type": "PLC_Siemens_S7_Ethernet",
          "das_type": "das",
          "desc": "1#线采集服务",
          "para": { "ip": "192.168.1.10", "port": "102" }
        }]
      }'

响应片段（裸结构，没有外层 code）：

json
{
  "app": [
    { "id": "", "name": "SVC_A", "err": { "code": 200, "msg": "ok" }, "channels": null }
  ]
}

【警告】建服务的成功响应常是裸的 {"app":[...]}。判成功必须看 app[0].err.code == 200，不要去找外层 code。

【注意】app[0].id 恒为空字符串，channels 恒为 null。后续定位服务请用 name。

3.5 第 5 步：建通道 ​

bash
curl -sk -X POST "$API/config/das/channel/insert/$DC" -H "$AUTH" \
  -H 'Content-Type: application/json' \
  -d '{"app":[{"name":"SVC_A","channels":[{"name":"CH1","alisa":"1#线","para":{}}]}]}'

响应片段：

json
{ "code": 200, "msg": "ok", "app": "SVC_A", "channelName": "CH1" }

【警告】创建通道的别名字段名是 alisa（不是 alias）；更新通道才是 alias。写错字段名不会报错，别名会被静默丢弃。

【警告】一次只能建 1 个通道（服务端只取 channels[0]）；channels 传空数组会触发服务端 panic。批量建通道请用 4.4 的 batch/insert + batch/progress 轮询。

3.6 第 6 步：导入测点（推荐用文件导入） ​

先下载模板，填好后导入：

bash
curl -sk -X POST "$API/config/point/import/template" -H "$AUTH" -o collect-template.xlsx

curl -sk -X POST "$API/config/point/import/$DC?sn=SVC_A&cn=CH1" -H "$AUTH" \
  -F 'file=@./points_das.xlsx'

响应片段：

json
{ "total": 1000, "successNum": 998, "failNum": 2, "tempFileName": "data/point_reason/<uuid>/SVC_A_CH1failure.xlsx" }

有失败项时，用 tempFileName 下载失败报告：

bash
curl -sk -X POST "$API/config/point/export/errInfo" -H "$AUTH" \
  -H 'Content-Type: application/json' \
  -d '{"tempFileName":"data/point_reason/<uuid>/SVC_A_CH1failure.xlsx"}' -o fail.xlsx

点表列名、长度约束与枚举见第 5 章数据字典。

3.7 第 7 步：建上传服务并生成上传测点 ​

上传服务与采集服务共用同一个接口，只是 das_type 不同：

bash
curl -sk -X POST "$API/config/das/insert/$DC" -H "$AUTH" \
  -H 'Content-Type: application/json' \
  -d '{"app":[{"name":"UPL_A","type":"<上传驱动名>","das_type":"upload","desc":"上传服务","para":{}}]}'

从采集服务/通道批量生成上传点：

bash
curl -sk -X POST "$API/config/point/upload/$DC" -H "$AUTH" \
  -H 'Content-Type: application/json' \
  -d '{"uname":"UPL_A","app":[{"name":"SVC_A","channels":[{"name":"CH1"}]}]}'

响应片段（恒定成功）：

json
{ "err": { "code": 200, "msg": "ok" } }

【警告】该接口的响应不代表真实结果（服务端 gRPC 返回值被丢弃），必须用 4.6 的 upoint/list 回查确认。

3.8 第 8 步：启动服务并回查验收 ​

bash
curl -sk -X POST "$API/config/das/cmd/$DC" -H "$AUTH" \
  -H 'Content-Type: application/json' \
  -d '{"app":[{"cmd":"start","name":"SVC_A"}]}'

# 回查 1：服务树（校验结构）
curl -sk "$API/config/das/tree/$DC" -H "$AUTH"

# 回查 2：通道列表（校验通道）
curl -sk -X POST "$API/config/das/channel/list/$DC" -H "$AUTH" \
  -H 'Content-Type: application/json' -d '{"limit":100,"page":0,"filter":{"app":"SVC_A"}}'

# 回查 3：测点列表（校验测点）
curl -sk -X POST "$API/config/point/select/$DC" -H "$AUTH" \
  -H 'Content-Type: application/json' \
  -d '{"limit":{"page":"0","limit":"10","order":"id","sort":"desc"},"filter":{"app":"SVC_A","channel":"CH1"}}'

验收判据：

回查接口应看到
das/tree出现 entityType: "App" 的服务节点，其 children 下有 entityType: "Channel" 的通道节点
channel/listchannels[] 中出现目标通道，status 符合预期
point/selectcount 与导入的 successNum 一致，样本测点归属正确