第三方接入与 Hook 扩展

约 1247 字大约 4 分钟

2025-03-03

第三方系统主动调用平台使用开放接口；平台在业务节点调用第三方使用 Hook。Hook 是正式扩展边界，平台维护者可以增加扩展点，应用开发者实现回调端，不需要取得平台私有源码。

开放接口

在访问令牌管理中创建令牌并绑定有权用户，按开放认证合同取得访问 token。请求使用 Authorization: Bearer <token>。权限按绑定用户的实际角色和资源计算，不统一赋予管理员权限。

普通业务集成先使用现有公开接口，不直接连接平台数据库。独立应用客户端与令牌接入见SDK。

注册 Hook Server 和能力

由平台管理员在 platform-manage → 系统运维 → Hook 扩展管理 配置服务。企业需要接收事件时，向管理员提供端点、鉴权方案和所需事件，不能假定企业用户拥有管理全平台 Hook 的权限。

配置	用途
endpoint	可达的回调 HTTP 地址
tenantCode	具体企业或 `common` 公共范围
authType/authConfig/headers	HMAC 或自定义认证头
timeoutSec/maxRetry	超时与可重试错误的重试上限
failPolicy	`fail` 阻断，`ignore` 记录后继续
Capability	code、subCode、kind 及说明

服务创建示例，用本机隔离回调地址替换端点，密钥由安全配置注入：

{
  "tenantCode": "<company-code>",
  "name": "my-ext-service",
  "endpoint": "https://hooks.example.com/hook",
  "authType": "hmac",
  "authConfig": {"secret": "<hook-secret>"},
  "timeoutSec": 10,
  "maxRetry": 3,
  "status": 1,
  "failPolicy": "ignore"
}

发送至 POST /api/v1/system/hook/server/create，再用返回的服务 ID 创建能力：

{
  "serverID": "<server-id>",
  "code": "devicePropertyReportV2",
  "subCode": "report",
  "kind": "async",
  "desc": "接收设备整包属性变化"
}

能力入口为 POST /api/v1/system/hook/capability/create。subCode: "*" 可匹配该 code 的子事件，按实际需要收窄。common 是公共匹配范围，不适合配置仅某企业可接收的私有事件。

标准回调报文

请求头包含 X-Hook-Request-Id 和秒级 X-Hook-Timestamp；HMAC 模式额外包含 X-Hook-Signature: hmac-sha256=<hex>。

{
  "method": "devicePropertyReportV2.report",
  "data": {
    "device": {"productID": "DEMO", "deviceName": "sensor1"},
    "timestamp": "1792112400000",
    "receivedTime": 1792112400123,
    "params": {"temperature": 25.5},
    "quality": {"temperature": "GOOD"}
  },
  "userCtx": {"tenantCode": "<company-code>", "userID": 0}
}

回调返回标准业务信封：

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

回调中的用户上下文用于识别经过验证的调用来源，设备消息无用户时仍需带正确企业范围。收到请求不代表可以信任任意外部伪造的 userCtx，先校验 Hook 鉴权。

HMAC 与重试

签名使用 HMAC-SHA256(secret, timestamp + "." + rawBody)，输出十六进制字符串。验证签名时使用原始请求字节，不能 JSON 解析后重排再签名；校验时间窗并用常量时间比较。

同一次逻辑调用的重试共享请求 ID，接收端按它去重。网络错误和 5xx 可按配置重试；返回业务 code != 200 不按网络错误重试，按失败策略处理。

kind 表达能力用途；同步或异步的真正执行方式由平台调用点决定，不能仅在管理端把 kind 改成 async 就改变阻塞行为。异步通知也不天然具有持久保证，需要必达的业务补持久任务。

已接入的扩展点

code / subCode	作用	注意
`areaInfo.create`	区域创建前扩展	同步校验，可阻断
`deviceBind.<protocolCode>`	设备绑定前扩展	按实际协议匹配
`userSubscribe.deviceSubscribe/projectSubscribe/areaSubscribe`	订阅资源权限计算	系统能力，不让第三方任意放开权限
`dataFilter.<场景>`	查询追加过滤	返回 where + 参数，权限配置由管理员维护
`dmDeviceConn.report` / `dmDeviceDisConn.report`	上下线通知	异步事件，按企业范围
`devicePropertyReport.report` / `devicePropertyReportV2.report`	单属性/整包属性变化	详见设备消息
`deviceEventReport.report`	物模型事件通知	不等同于属性控制已成功
`alarmObject.<hookCode>` 及 schema 子编码	告警对象与指标扩展	按对象提供者合同返回

只有常量而无实际调用点，不算已支持的 Hook；新增能力前确认调用路径，而不是直接在管理界面填写一个名称。

平台新增扩展点

先定义 code/subCode、输入输出和失败策略，再通过现有 Hook 查询/调用入口匹配企业与公共服务。调用方须检查返回值；同步校验应放在允许失败的位置，已提交数据后的回调失败不能伪装为事务回滚。

旧插槽机制已废弃。原文中的 Slot 接入不要用于新模块，迁移到 Hook Server + Capability；存量调用先核对是否还有实际引用，再逐步迁移，不能只删除常量。

验证签名成功/失败、时间窗、同请求重投、超时、5xx、业务错误，以及企业范围与失败策略。设备端与前端观察结果分别验收，不以回调 HTTP 200 代替完整业务成功。

更新日志

2026/10/16 19:46

查看所有更新日志

b3b4d-docs(平台开发): 恢复有效专题并更新当前实现示例于 2026/10/16

后端专题

实时通信

业务能力