调用开放 API 与访问令牌
用登录接口拿到 JWT,走 Bearer 鉴权调用常用查询接口,并建立 SSE 长连接订阅实时点位流;另附北向订阅 API 的签名换 token 示例。
你将完成
读完本篇你将能够:
- 用
/auth/login获取访问令牌(JWT)并带在后续请求里; - 用 curl 完成测点查询与实时值快照两类常用调用;
- 建立实时总线 SSE 连接,订阅点位值流;
- 知道去哪里查全部接口文档。
开始之前
- 一个平台账号(权限决定能访问哪些接口);
- 能访问服务端
8999端口的机器;curl 7.5+ 或任意 HTTP 客户端。
鉴权方式#
所有业务接口走 JWT Bearer 鉴权:先换令牌,再把它放进 Authorization 请求头。令牌有过期时间(登录响应的 expireIn),过期后用 refreshToken 换新或重新登录。
获取访问令牌#
TOKEN=$(curl -s -X POST http://localhost:8999/api/v1/auth/login \
-H "Content-Type: application/json" \
-d '{"username":"admin","password":"******"}' \
| jq -r '.data.accessToken')
响应 data 里包含 accessToken、refreshToken、expireIn 与用户信息。此后每个请求都带:
curl -s http://localhost:8999/api/v1/iiot/gateways \
-H "Authorization: Bearer $TOKEN"
令牌保密
JWT 等同于账号凭据,只放请求头,不要写进 URL、日志或前端代码;生产环境务必启用 HTTPS。
查询类常用接口#
curl -s "http://localhost:8999/api/v1/iiot/tags?gateway_id=1&keyword=液位&page=1&page_size=10" \
-H "Authorization: Bearer $TOKEN"
curl -s "http://localhost:8999/api/v1/iiot/realtime/snapshot?gatewayId=1&paths=示例设备/灌装产线PLC/原料罐液位" \
-H "Authorization: Bearer $TOKEN"
快照返回 items 数组:每条含 path(设备路径/测点名)、value、quality 与 ts。paths 多个时用英文逗号分隔。
订阅实时数据(SSE 总线)#
实时推送走 SSE 长连接,按会话订阅主题。顺序是:先建连接,再订阅,之后值变化会以 event: tag 帧推过来。
curl -N "http://localhost:8999/api/v1/iiot/realtime/bus?sessionId=my-consumer-1" \
-H "Authorization: Bearer $TOKEN" \
-H "Accept: text/event-stream"
另开一个终端,把想看的设备加入订阅:
curl -s -X POST http://localhost:8999/api/v1/iiot/realtime/bus/subscribe \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d '{"sessionId":"my-consumer-1","topics":["realtime.device.示例设备/灌装产线PLC"]}'
收到的帧形如(p 路径、v 值、t 毫秒时间戳):
event: tag
data: {"topic":"realtime.device.示例设备/灌装产线PLC","event":"tag",
"data":{"items":[{"p":"示例设备/灌装产线PLC/原料罐液位","v":36,"t":1794153259303}]}}
常用主题:realtime.tag(已订阅测点)、realtime.device.{设备路径}(整设备值流)、realtime.health(设备健康)、realtime.alarm(报警)。取消订阅调用同路径的 /bus/unsubscribe。
北向订阅 API(第三方免登录)#
如果是外部第三方系统,不必持有平台账号:在订阅应用领取 App Key / App Secret,签名换短期 token 后订阅专用 SSE 流。
TS=$(date +%s000); NONCE=$(openssl rand -hex 8)
SIG=$(printf '%s\n%s\n%s' "$APP_KEY" "$TS" "$NONCE" \
| openssl dgst -sha256 -hmac "$APP_SECRET" | awk '{print $2}')
TOKEN=$(curl -s -X POST http://localhost:8999/api/v1/northbound/stream-token \
-H "Content-Type: application/json" \
-d "{\"appKey\":\"$APP_KEY\",\"ts\":$TS,\"nonce\":\"$NONCE\",\"sig\":\"$SIG\"}" \
| jq -r '.data.token')
curl -N -H "Authorization: Bearer $TOKEN" \
"http://localhost:8999/api/v1/northbound/stream?paths=默认分组/测试/"
首屏收到全量快照帧,随后是增量帧与心跳;请求量受应用的限流与日配额约束。
预期结果
两条 SSE 连接都能持续收到数据帧:平台账号走实时总线,第三方走订阅 API;把 curl 换成任何语言的 EventSource / HTTP 客户端即可接入你的系统。
常见问题#
返回 401#
令牌过期或没带 Authorization 头。重新登录换 token;SSE 连接同样需要请求头携带(浏览器 EventSource 做不到时改用 fetch 流式读取)。
SSE 一直只有 retry 行#
订阅在连接建立之前发送会被拒(「当前用户的 SSE 会话不存在」)。先起 bus 连接,再调 subscribe。
想看全部接口与参数#
服务端自带 Swagger 文档:浏览器打开 http://<服务地址>:8999/swagger/index.html,可按模块筛选并在线试调。
下一步#
- 用北向连接器把数据送出去 MQTT 出站与订阅应用的完整流程。
- 数据存储与保留策略 想直接查库时先看这里。
- 实时监控 页面上看实时值的入口。
这篇文档对你有帮助吗?