简述

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

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

开放接口

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

认证方式

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

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

配置方式

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

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

webhook 消息推送

消息推送需要第三方提供 url，推送的方式为 post，格式为 json，推送 http 头可以添加第三方自定义参数。

配置方式

暂不支持 web 配置，需要在数据库中添加配置信息（后续将并入 Hook 扩展机制统一管理）。

表名: sys_tenant_open_webhook

参数说明:

参数	类型	说明
tenantCode	String	租户号
code	String	推送内容编码（见下方端点清单）
hosts	array[string]	访问的地址列表（当前实际使用 hosts[0]）
uri	String	访问的路径
desc	String	描述
handler	map[string]string	自定义 http 头

与旧版差异：已移除 access_secret 字段；推送失败重试 3 次（间隔 2s），查不到配置时有 15 分钟负缓存。

推送端点及内容

code	含义	触发时机
dmDeviceConn / dmDeviceDisConn	设备上线 / 下线	设备连接状态变化
devicePropertyReport	属性变化（单属性）	设备属性上报、属性控制后
devicePropertyReportV2	属性变化（整包）	设备属性上报
deviceEventReport	事件上报	设备事件上报

设备上下线推送

{
  "device": {
    "productID": "产品ID",
    "deviceName": "设备名"
  },
  "status": 1,
  "timestamp": "毫秒时间戳字符串"
}

status：1 为上线，2 为下线。

设备属性变化推送

单属性（devicePropertyReport）：

{
  "device": {
    "productID": "产品ID",
    "deviceName": "设备名"
  },
  "identifier": "标识符id",
  "timestamp": "毫秒时间戳字符串",
  "param": {"aaa": 123}
}

整包（devicePropertyReportV2）的 params 为 {标识符: 值} 的 map，其余字段相同。

字段定义:

字段名	含义	备注
device.productID	产品id
device.deviceName	设备名
timestamp	设备数据时间	毫秒时间戳(string类型)
identifier	推送属性的标识符	仅单属性格式
param / params	推送属性的参数	和物模型上定义的类型一致

设备事件变化推送

{
    "device":{
        "productID":"254pwnKQsvK",
        "deviceName":"test5"
    },
    "timestamp":"1670852257719",
    "identifier":"low_power",
    "type":"alert",
    "params":{
        "voltage":2.8
    }
}

字段定义:

字段名	含义	备注
device.productID	产品id
device.deviceName	设备名
timestamp	设备数据时间	毫秒时间戳(string类型)
identifier	推送事件的标识符
params	事件参数	和物模型上定义的类型一致
type	事件类型	信息:info 告警:alert 故障:fault

演进提示：webhook 推送将统一并入下方的 Hook 扩展机制（sys_tenant_open_webhook 配置将迁移为 sys_hook_server，报文格式将统一为 Hook 标准信封），届时会提供配置页面。切换前会提前通知在用第三方。

Hook 扩展机制（推荐）

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

配置方式

已支持 Web 配置：platform-manage → 系统运维 → Hook扩展管理，或通过 API /api/v1/system/hook/server、/api/v1/system/hook/capability 管理。

核心概念

概念	说明
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：

{
    "method": "areaInfo.create",
    "data": { "..." : "由 Hook 点决定的业务数据" },
    "userCtx": { "userID": 1001, "tenantCode": "default", "...": "..." }
}

Hook Server → 平台：

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

code != 200 视为业务失败（不重试），按 failPolicy 决定是否阻断；网络错误与 5xx 按指数退避重试（默认 3 次），同一次调用共享 X-Hook-Request-Id 便于幂等。

已有 Hook 点清单

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}	指标字段 / 事件字段

areaInfo.delete、deviceSend.propertyControlSend、system.init 目前只有常量与文档，暂无实际调用点。

详细文档

• 使用指南（含各语言签名验证示例、Go 中间件）：docs/中台/功能说明/Hook扩展/使用说明.md
• 设计方案（数据模型、协议细节、缓存机制）：docs/中台/功能说明/Hook扩展/设计方案.md

更新日志

2026/7/21 17:54

查看所有更新日志

• d5807-Merge #9 into master from docs/hook-third-party-update于 2026/7/21
• d4fa0-doc: 更换皮肤到最新版于 2025/3/3
• 64643-doc于 2024/12/9
• 4066c-doc: 完善文档于 2024/11/12
• d8115-doc于 2024/10/30
• 5741d-初始化于 2024/9/6

贡献者: godLei6, 杨磊

上一页数据库使用

下一页插槽使用