第三方接入

约 2363 字大约 8 分钟

2025-03-03

简述

第三方接入是提供给外部系统来进行集成的方案，目前包含两种方式：

方式	方向	说明
开放接口	外部 → 平台	第三方通过访问令牌调用平台 API
Hook 扩展机制	双向	标准化扩展架构（推荐），平台可在业务节点调用第三方，第三方也可注册为 Hook Server 被平台调用；设备上下线/属性/事件变化推送已并入此机制

开放接口

开放接口是提供给第三方访问我方接口的认证方式，采用开放认证权限同用户的方式，开放认证的权限由绑定用户的权限来决定（按绑定用户的实际角色计算，不再统一视为管理员）。

认证方式

开放服务使用 JWT Bearer auth 方式，在 http 头中添加： Authorization Bearer <jwt token>

token 由访问令牌的 accessKey / accessSecret 签发，payload 包含绑定用户、租户编码、过期时间等信息。

配置方式

已支持 Web 配置：在 console 用户中心 → 访问令牌 页面创建和管理（可设置有效期、可用租户范围）。

旧版的 sys_tenant_open_access 表已废弃，不再使用。

Hook 扩展机制（推荐）

Hook 扩展机制是标准化的第三方扩展架构：HookServer 注册 + HookCapability 声明 + 标准协议。第三方注册一个 HTTP 服务并声明关注的事件点，即可在平台业务节点（权限校验、数据过滤、事件通知等）插入自定义逻辑；平台自身服务也可以注册为 Hook Server 被其他模块调用。

配置方式

Hook 扩展机制由平台管理员统一配置（平台管理端）。进入路径：platform-manage → 系统运维 → Hook扩展管理，或通过 API /api/v1/system/hook/server、/api/v1/system/hook/capability 管理。

操作步骤

登录平台管理端（platform-manage），进入 系统运维 → Hook扩展管理：

点击新增，填写 Hook Server 信息：
- 企业：下拉选择（可搜索）。默认 common（全局通用，全平台可用）；选择具体企业则仅该企业业务会命中此 Hook Server
- 名称 / 描述：服务标识与说明
- 服务端点：第三方接收 Hook 回调的 HTTP 地址
- 鉴权类型：无鉴权 / HMAC 签名 / 自定义请求头（可叠加）
- 失败策略：忽略（失败仅记日志，业务继续，推荐事件通知类）/ 阻断（失败拦截业务）
- 超时 / 最大重试次数 / 状态：调用控制参数

保存后，对服务声明 能力（Capability）：点击列表行的能力，添加该服务关注的事件点：
- 能力编码（code）：业务模块标识，如 areaInfo、devicePropertyReport
- 子编码（subCode）：模块内具体事件，如 create、report；填 * 匹配该模块所有事件
- 类型（kind）：sync（同步扩展点，调用方等待返回）/ async（异步事件通知，调用方异步派发）。设备推送类建议选 async
- 描述：能力说明

通过 API 注册（可选）

也可通过 HTTP API 完成同样配置：

POST /api/v1/system/hook/server/create
Authorization: Bearer <token>
Content-Type: application/json

{
    "tenantCode": "common",
    "name": "my-ext-service",
    "desc": "我的扩展服务",
    "endpoint": "https://my-service.example.com/hook",
    "authType": "hmac",
    "authConfig": {"secret": "your-secret-key"},
    "status": 1,
    "timeoutSec": 10,
    "maxRetry": 3,
    "failPolicy": "ignore"
}

POST /api/v1/system/hook/capability/create
Authorization: Bearer <token>
Content-Type: application/json

{
    "serverID": "123",
    "code": "devicePropertyReport",
    "subCode": "report",
    "kind": "async",
    "desc": "监听设备属性上报"
}

tenantCode（企业维度）：common（默认）表示全平台所有企业都可匹配到该服务；填具体企业编码则仅该企业的业务调用会命中。平台自身注册的服务（如 things-apisvr）均为 common。 authType=custom（自定义请求头）：第三方要求自定义 Header（如 Authorization: Bearer xxx、X-Api-Key）时使用，headers 键值对逐个写入 Hook 请求头，可与 hmac 签名叠加。

企业级 Hook 申请流程

Hook 由平台管理员统一配置，租户侧无自助页面。
若企业需要接收设备事件推送（设备上下线/属性/事件）或使用平台 Hook 点，需向平台管理员申请，由管理员在平台管理端创建 Hook Server，并在"企业"字段选择该企业（tenantCode），同时声明所需能力。
企业侧需准备好接收 Hook 回调的 HTTP 服务（按本文下方"请求与响应报文"实现），并将端点、鉴权方式等提供给平台管理员。
使用说明（含各语言签名验证示例、Go 中间件）：见仓库内 docs/中台/功能说明/Hook扩展/使用说明.md。

核心概念

概念	说明
HookServer	注册的扩展服务：endpoint、鉴权、超时/重试、失败策略、所属租户
HookCapability	能力声明：该服务关注哪些事件点（code + subCode），`*` 匹配全部子编码
tenantCode	租户维度：`common`（默认）= 全平台可用，其余 = 仅该租户
kind	能力类型标注：sync（同步扩展点）/ async（异步事件通知）。注意：同步/异步实际由平台侧调用点代码决定，kind 仅作展示与引导
failPolicy	`fail`（失败阻断业务）/ `ignore`（失败仅记日志，业务继续）

鉴权方式

authType	说明
`none`	无鉴权
`hmac`	HMAC-SHA256 签名：`X-Hook-Signature: hmac-sha256=<hex>`，签名串为 `X-Hook-Timestamp + "." + body`，时间窗 ±5 分钟防重放
`custom`	自定义请求头：`headers` 键值对逐个写入请求头（如 `Authorization: Bearer xxx`），可与 hmac 叠加

请求与响应报文

平台 → Hook Server（完整请求示例，含请求头）：

POST https://my-service.example.com/hook
Content-Type: application/json
X-Hook-Request-Id: <uuid>                    # 同一次逻辑调用所有重试共享，用于幂等
X-Hook-Timestamp: 1741622400                 # Unix 秒级时间戳
X-Hook-Signature: hmac-sha256=<hex>          # 仅 authType=hmac 时携带

{
    "method": "devicePropertyReport.report",
    "data": {
        "device": {"productID": "AC", "deviceName": "AI_x123"},
        "timestamp": "1786528142083",
        "identifier": "wendu",
        "param": 25.5
    },
    "userCtx": {
        "userID": 0,
        "tenantCode": "351529002663376",
        "projectID": 2,
        "isAdmin": true
    }
}

字段说明：

字段	说明
`method`	调用点标识，格式 `code.subCode`（如 `areaInfo.create`、`devicePropertyReport.report`）
`data`	业务数据，由各 Hook 点决定（见下方"已有 Hook 点清单"的 data 入参列）
`userCtx`	触发 Hook 的用户上下文（userID/tenantCode/projectID/isAdmin 等）；设备事件路径无用户时 tenantCode 为设备所属租户
`X-Hook-Request-Id`	同一次逻辑调用所有重试共享的 UUID，可用于幂等去重
`X-Hook-Timestamp`	Unix 秒级时间戳，HMAC 校验的时间窗 ±5 分钟防重放
`X-Hook-Signature`	HMAC-SHA256 签名，签名串为 `X-Hook-Timestamp + "." + body`（仅 hmac 鉴权时携带）

Hook Server → 平台：

{ "code": 200, "msg": "success", "data": { } }

调用语义：

code != 200 视为业务失败（不重试），按 failPolicy 决定是否阻断业务（fail 阻断 / ignore 仅记日志继续）
网络错误与 5xx 按指数退避重试（默认 3 次），同一次调用共享 X-Hook-Request-Id 便于幂等
同步 Hook 点（如 areaInfo.create）调用方等待响应；异步事件通知类（设备推送）由平台侧 utils.Go 异步派发，failPolicy 建议 ignore

已有 Hook 点清单

同步扩展点（调用方等待返回，failPolicy=fail 可阻断业务）

code	subCode	触发时机	data 入参	返回
`areaInfo`	`create`	区域创建前（可阻断）	区域信息	无
`userSubscribe`	`*`（订阅 code 动态）	WebSocket 订阅权限检查	`{code, params{productID?, deviceName?}}`	`{list:[{productID, deviceName}]}`
`dataFilter`	`projectScope` / `deviceScope` / 自定义	数据查询权限过滤	`{code, headers{projectId?}}`	`{where, args[]}`
`deviceBind`	`{protocolCode}`	设备绑定前（可阻断）	设备绑定请求	无
`alarmObject`	`{hookCode}`	告警对象树子节点（懒加载）	`{hookCode, parentID, level}`	子节点列表
`alarmObject`	`{hookCode}.schema`（device 固定 `device.schema`）	告警对象可监控字段	`{hookCode}`	指标字段 / 事件字段

异步事件通知（设备推送类，平台侧异步派发，推荐 kind=async + failPolicy=ignore）

code	subCode	触发时机	data 入参	返回
`dmDeviceConn` / `dmDeviceDisConn`	`report`	设备上线 / 下线	ConnectMsg{device{productID, deviceName}, status(1上线/2下线), timestamp}	无
`devicePropertyReport` / `devicePropertyReportV2`	`report`	设备属性上报 / 属性控制后	PropertyReport{device, timestamp, identifier, param} / PropertyReportV2	无
`deviceEventReport`	`report`	设备事件上报	EventReport	无

设备推送类 Hook 点由平台管理员配置 Hook Server 时指定 tenantCode（common=全平台，其余=仅该租户）决定推送范围；接收方收到的 data 结构与上表一致，报文为 Hook 标准信封。 areaInfo.delete、deviceSend.propertyControlSend、system.init 目前只有常量与文档，暂无实际调用点。