softbus_daemon/src/api/API_INTERFACE_TABLE.md

softbus_daemon API 接口表

本文档汇总 src/api 当前对外接口，分为：

• D-Bus 直接方法
• executeCommand JSON 命令接口
• HTTP REST 接口

1) D-Bus 服务基础信息

项目	值
Service	com.softbus.Daemon
ObjectPath	/com/softbus/Daemon
Interface	com.softbus.Daemon
适配类	IpcDBus

2) D-Bus 方法表（IpcDBus）

方法	入参	返回	说明
isRunning()	无	bool	核心服务是否初始化完成
ping()	无	QString	健康探针，固定返回 pong
getVersion()	无	QString	进程版本号
getStatus()	无	QString(JSON)	返回服务状态（pid/role/running/timestamp 等）
getPid()	无	qint64	返回守护进程 PID
shutdown()	无	void	关闭 CoreService 并退出进程
reloadConfig()	无	bool	预留，当前为占位实现
executeCommand(requestJson)	QString(JSON)	QString(JSON)	统一 JSON 命令入口

3) executeCommand 协议

3.1 请求格式

{
  "id": "req-001",
  "action": "add_filter",
  "params": {}
}

3.2 响应格式

{
  "id": "req-001",
  "code": 0,
  "message": "ok",
  "data": {}
}

4) action 路由表（CommandDispatcher）

action	params 关键字段	成功 code	失败 code	说明
add_filter	id, endpointHash?, deviceId?, stableKey?, condition?	0	4001	添加过滤规则
remove_filter	id	0	4041	删除过滤规则
add_transform_rule	id, endpointHash?, deviceId?, stableKey?, scale?, offset?, unit?	0	4002	添加转换规则
remove_transform_rule	id	0	4042	删除转换规则
add_mapping_rule	compositeKey, domPath, scale?, offset?, unit?, metadataId?, pointId?, catalogVersion?, updatedBy?	0	4004 / 5002	新增/更新映射规则；成功后持久化到 runtime_mappings.json；5002 表示持久化失败
remove_mapping_rule	compositeKey	0	4043 / 5002	删除映射规则并持久化
list_mapping_rules	无	0	-	返回 items 与 mappingCatalogVersion
discovery_start	ttlMs?	0	-	开启嗅探模式
discovery_stop	无	0	-	关闭嗅探模式
discovery_clear	无	0	-	清空发现池
list_rules	无	0	-	返回规则计数状态
get_status	无	0	-	返回规则计数 + discovery/mapping 状态
其他未知 action	-	-	4040	未知动作

5) HTTP REST 路由表（RestApiRoutes）

5.1 通用路由

方法	路径	说明
GET	/health	健康检查，返回 {"ok": true}
GET	/v1/status	透传 get_status 的状态响应
POST	/v1/command	统一命令入口（请求体为 executeCommand JSON）

5.2 设备树 / 设备路由

方法	路径	请求参数	说明
GET	/api/v1/device-tree	无	返回当前设备树快照
GET	/api/v1/devices	无	返回当前运行态设备列表
GET	/api/v1/devices/{id}	path: id(int)	返回指定运行态设备详情
PATCH	/api/v1/device-tree/nodes/{id}	body: 任意可变节点字段子集	部分更新设备树节点；当前至少保护 id、params.stableKey、params.online、params.lastSeenTs

5.3 规则管理路由

方法	路径	请求参数	说明
GET	/api/v1/rules/status	无	返回动态规则计数状态
POST	/api/v1/rules/filter	body: id, endpointHash?, deviceId?, stableKey?, condition?	新增过滤规则
DELETE	/api/v1/rules/filter/{id}	path: id	删除过滤规则
POST	/api/v1/rules/transform	body: id, endpointHash?, deviceId?, stableKey?, scale?, offset?, unit?	新增转换规则
DELETE	/api/v1/rules/transform/{id}	path: id	删除转换规则

• 说明：
  • transform 规则已经在 PipelineEngine::applyTransformAndEnrich(...) 中生效。
  • filter 路由当前主要提供“注册表管理”能力；动态 filter 规则尚未真正接入 PipelineEngine::stage3Filter(...) 的执行链路。

5.4 Pipeline 路由

方法	路径	请求参数	说明
GET	/api/v1/pipeline/status	无	返回 pipeline 运行状态、session 数量、队列容量、插件摘要与 counters
GET	/api/v1/pipeline/counters	无	返回 in/out/drop/error/mergeDrop 计数器快照
GET	/api/v1/pipeline/config	无	返回当前运行时配置快照

• 说明：/v1/status 仍然是 control-plane 摘要（规则 + discovery + mapping），不等同于 /api/v1/pipeline/status。

5.5 插件 / 协议能力路由

方法	路径	请求参数	说明
GET	/api/v1/plugins	无	返回 parser / framer / mapper 三类逻辑插件的统一列表
GET	/api/v1/plugins/protocols	无	返回按协议聚合后的能力快照（parser/framer/mapper pluginId）
GET	/api/v1/plugins/mappers	无	返回 mapper 插件列表

5.6 Metadata / Profile 路由

方法	路径	请求参数	说明
GET	/api/v1/metadata	无	返回 data（字典数组）与可选 catalogVersion（根级字段）
GET	/api/v1/metadata/{metadataId}	path: metadataId	返回指定 metadata 详情（含可选 catalogVersion）
GET	/api/v1/profiles	无	返回 data 与可选 catalogVersion
GET	/api/v1/profiles/{deviceId}	path: deviceId	返回指定 deviceId 关联的全部 profile（含可选 catalogVersion）

5.7 Discovery 路由

方法	路径	请求参数	说明
POST	/api/v1/discovery/start	body: ttlMs?	开启嗅探；可设置自动关闭 TTL
POST	/api/v1/discovery/stop	无	关闭嗅探
GET	/api/v1/discovery/status	无	获取发现池运行状态
POST	/api/v1/discovery/clear	无	清空发现池样本
GET	/api/v1/discovery/samples	query: offset?, limit?, endpointHash?, protocol?	拉取样本（按更新时间倒序，且过滤已映射 key）

5.8 Mapping 路由

方法	路径	请求参数	说明
POST	/api/v1/mapping/bind	body: compositeKey, domPath, scale?, offset?, unit?, metadataId?, pointId?, catalogVersion?, updatedBy?	绑定或更新映射规则并写入 runtime_mappings.json
POST	/api/v1/mapping/unbind	body: compositeKey	删除映射规则并持久化
GET	/api/v1/mapping/list	无	返回 items 与 mappingCatalogVersion

6) 通用错误码约定（当前实现）

code	message	说明
0	ok	成功
4000	invalid_json	请求 JSON 无法解析或非对象
4001	invalid_filter_rule	过滤规则参数非法
4002	invalid_transform_rule	转换规则参数非法
4003	invalid_action	action 为空或分发器不可用
4004	invalid_mapping_rule	映射规则参数非法
4040	unknown_action	action 未注册
4041	filter_not_found	删除过滤规则时未找到
4042	transform_rule_not_found	删除转换规则时未找到
4043	mapping_rule_not_found	删除映射规则时未找到
5002	persist_mappings_failed	映射规则内存更新成功但写入 runtime_mappings.json 失败

7) 维护建议

• 新增 action 时，同时更新：
  • CommandDispatcher::dispatch(...)
  • 本文档第 4 节 action 表
• 新增 REST 路由时，同时更新：
  • RestApiRoutes.cpp
  • 本文档第 5 节路由表
• 若扩展返回结构，保持 code/message/data 三元组不变，避免客户端兼容性问题。