资源树管理
更新时间: 2025/07/09
在Gitcode上查看源码

简介

资源树提供openUBMC平台的基础管理功能,本模块主要提供一些常用的资源树相关的API以及公共资源树接口的管理功能

代理对象

代理对象用于简化对资源树的访问,开发只需要输入path和interface即可获取代理对象,通过代理对象实现对资源树接口的访问

1)获取代理对象

lua
local mdb = require 'mdb'
local obj = mdb.get_object(bus, path, interface)

2)获取属性

lua
    local prop = obj.Property

3)设置属性

lua
    obj.Property = 1

4)调用方法

在方法名后添加'_PACKED'字段返回结构化响应

lua
local obj = mdb.get_object(bus, path, interface)
local rsp = obj:Test_PACKED(1)
local r1, r2 = rsp.r1, rsp.r2
local s1, s2 = r2.s1, r2.s2

不添加'_PACKED'字段返回多参数响应

lua
local obj = mdb.get_object(bus, path, interface)
local r1, r2 = obj:Test(1)
local s1, s2 = r2[1], r2[2]

接口说明

mdb_service

提供操作资源树的一些常用API

加载方式

lua
local mdb_service = require 'mc.mdb.mdb_service'

get_object(bus, path, interfaces)

描述

  • 根据Path, Interfaces查找Service与Interface的映射关系
  • 获取指定路径(Path)下符合目标接口(interfaces)的对象

参数

参数类型描述是否必选
bususerdatadbus服务必选
pathstring资源树path必选
interfacesstring资源树interfaces必选

返回

  • 资源树对象

异常

示例

lua
local mdb_service = require 'mc.mdb.mdb_service'
local rsp = mdb_service.get_object(bus, path, interfaces)
local object = rsp.Object

get_sub_objects(bus, path, depth, interfaces)

描述

  • 根据Path, Depth, Interfaces查找Path、service与Interface的映射关系
  • 递归获取指定路径(Path)下所有层级(Depth)的子对象,并过滤出符合目标接口(interfaces)的资源

参数

参数类型描述是否必选
bususerdatadbus服务必选
pathstring资源树path必选
depthinteger层级必选
interfacesstring资源树interfaces必选

返回

  • 资源树对象列表

异常

示例

lua
local mdb_service = require 'mc.mdb.mdb_service'
local rsp = mdb_service.get_sub_objects(bus, path, depth, interfaces)
local sub_objects = rsp.SubObjects

get_sub_paths(bus, path, depth, interfaces)

描述

  • 根据Path, Depth, Interfaces查找所有满足条件的Paths

参数

参数类型描述是否必选
bususerdatadbus服务必选
pathstring资源树path必选
depthinteger层级必选
interfacesstring资源树interfaces必选

返回

  • Paths列表

异常

示例

lua
local mdb_service = require 'mc.mdb.mdb_service'
local rsp = mdb_service.get_sub_paths(bus, path, depth, interfaces)
local sub_paths = rsp.SubPaths

get_parent_objects(bus, path, interfaces)

描述

  • 根据Path, Interfaces查找所有该Path的祖先Path

参数

参数类型描述是否必选
bususerdatadbus服务必选
pathstring资源树path必选
interfacesstring资源树interfaces必选

返回

  • 祖先Path对象

异常

示例

lua
local mdb_service = require 'mc.mdb.mdb_service'
local rsp = mdb_service.get_parent_objects(bus, path, interfaces)
local partent_objects = rsp.ParentObjects

get_service_name(bus, sender)

描述

  • 根据dbus的Sender查找service

参数

参数类型描述是否必选
bususerdatadbus服务必选
senderstringdbus消息Sender必选

返回

  • service名称

异常

示例

lua
local mdb_service = require 'mc.mdb.mdb_service'
local rsp = mdb_service.get_service_name(bus, sender)
local service_name = rsp.ServiceName

get_service_names(bus)

描述

  • 查找所有的service

参数

参数类型描述是否必选
bususerdatadbus服务必选

返回

  • service名称

异常

示例

lua
local mdb_service = require 'mc.mdb.mdb_service'
local rsp = mdb_service.get_service_names(bus)
local service_names = rsp.ServiceNames

get_path(bus, interface, filter, ignore_case, disable_cache)

描述

  • 根据Interface下的属性值查找满足条件的Path及其Service(属性值可以配置忽略大小写选项,返回按字典序排序的第一个Path)

参数

参数类型描述是否必选
bususerdatadbus服务必选
interfacestring资源树interface必选
filterstring筛选符合特定属性的资源树Path必选
ignore_caseboolean是否忽略大小写必选
disable_cacheboolean是否禁用缓存机制,强制从dbus实时获取最新路径可选

返回

  • 按字典序排序的第一个Path及其Service

异常

示例

lua
local mdb_service = require 'mc.mdb.mdb_service'
local rsp = mdb_service.get_path(bus, interface, filter, ignore_case, disable_cache)
local path, service = rsp.Path, rsp.Service

get_interface_owners(bus, interface)

描述

  • 查询拥有该Interface的Sender和Path

参数

参数类型描述是否必选
bususerdatadbus服务必选
interfacestring资源树interface必选

返回

  • 拥有该Interface的Sender和Path,即由包含多个 {Path = '/xx/xx/xx', Sender = 'xxx'} 格式的表组成的列表

异常

示例

lua
local mdb_service = require 'mc.mdb.mdb_service'
local rsp = mdb_service.get_interface_owners(bus, interface)
local interface_owners = rsp.InterfaceOwners

is_valid_path(bus, path, ignore_case)

描述

  • 判断路径是否是一个有效路径

参数

参数类型描述是否必选
bususerdatadbus服务必选
pathstring资源树path必选
ignore_caseboolean是否忽略大小写可选

返回

  • 判断结果,类型为boolean

异常

示例

lua
local mdb_service = require 'mc.mdb.mdb_service'
local rsp = mdb_service.is_valid_path(bus, path, ignore_case)
local result = rsp.Result

get_sub_paths_paging(bus, path, depth, interfaces, skip, top)

描述

  • 分页查找子路径

参数

参数类型描述是否必选
bususerdatadbus服务必选
pathstring资源树path必选
depthinteger层级必选
interfacesstring资源树interfaces必选
skipinteger跳过的路径数量必选
topinteger返回的路径数量必选

返回

  • 查找到的子路径集合

异常

示例

lua
local mdb_service = require 'mc.mdb.mdb_service'
local rsp = mdb_service.get_sub_paths_paging(bus, path, depth, interfaces, skip, top)
local sub_paths = rsp.Paths

get_classes(bus, service)

描述

  • 获取服务下的所有类名

参数

参数类型描述是否必选
bususerdatadbus服务必选
servicestring服务名必选

返回

  • 查找到的子路径集合

异常

示例

lua
local mdb_service = require 'mc.mdb.mdb_service'
local rsp = mdb_service.get_classes(bus, service)
local class_names = rsp.ClassNames

get_object_list(bus, class_name)

描述

  • 根据类名查询对象名、service和Path

参数

参数类型描述是否必选
bususerdatadbus服务必选
class_namestring类名必选

返回

  • 由包含多个 {object_name, {service, path}} 格式的表组成的列表

异常

示例

lua
local mdb_service = require 'mc.mdb.mdb_service'
local rsp = mdb_service.get_object_list(bus, class_name)
local object_list = rsp.ObjectList

get_object_owner(bus, object_name)

描述

  • 根据对象名查找service和Path

参数

参数类型描述是否必选
bususerdatadbus服务必选
object_namestring对象名必选

返回

  • service和Path信息

异常

示例

lua
local mdb_service = require 'mc.mdb.mdb_service'
local rsp = mdb_service.get_object_owner(bus, object_name)
local object_owners = rsp.ObjectOwners

get_matched_objects(bus, service, interface_pattern)

描述

  • 根据服务名和Interface pattern查找object name, Path, Interfaces

参数

参数类型描述是否必选
bususerdatadbus服务必选
servicestring服务名必选
interface_patternstring接口模式,用于模式匹配必选

返回

  • object name, Path, Interfaces信息

异常

示例

lua
local mdb_service = require 'mc.mdb.mdb_service'
local rsp = mdb_service.get_matched_objects(bus, service, interface_pattern)
local matched_objects = rsp.MatchedObjects

信号订阅

加载方式

lua
local subscribe_signal = require 'mc.mdb.subscribe_signal'

subscribe_virtual_interface(bus, interface, object_list, slots)

描述

  • 订阅虚接口

参数

参数类型描述是否必选
bususerdatadbus服务必选
interfacestring虚接口名必选
object_listtable虚对象列表必选
slotstable信号槽必选

返回

异常

示例

lua
local subscribe_signal = require 'mc.mdb.subscribe_signal'
subscribe_signal.subscribe_virtual_interface(bus, interface, object_list, slots)

subscribe_non_virtual_interface(bus, interface, object_list, slots)

描述

  • 订阅非虚接口

参数

参数类型描述是否必选
bususerdatadbus服务必选
interfacestring接口名必选
object_listtable对象列表必选
slotstable信号槽必选

返回

异常

示例

lua
local subscribe_signal = require 'mc.mdb.subscribe_signal'
subscribe_signal.subscribe_non_virtual_interface(bus, interface, object_list, slots)

on_properties_changed(bus, path_namespace, cb, interface, properties)

描述

  • 订阅属性变更信号

参数

参数类型描述是否必选
bususerdatadbus服务必选
path_namespacestring或tabledbus对象路径必选
cbfunction属性变更时触发的回调函数必选
interfacestring接口名必选
propertiestable需订阅的特定属性列表,若为nil则监听该接口所有属性可选

返回

  • 返回信号订阅标识符,若path_namespace为table类型,则返回信号订阅标识符数组

异常

示例

lua
local subscribe_signal = require 'mc.mdb.subscribe_signal'
subscribe_signal.on_properties_changed(bus, path_namespace, cb, interface, properties)

on_interfaces_added(bus, path_namespace, cb, expected_intf)

描述

  • 订阅接口新增信号

参数

参数类型描述是否必选
bususerdatadbus服务必选
path_namespacestring或tabledbus对象路径必选
cbfunction接口新增时触发的回调函数必选
expected_intfstring期望订阅的接口名称必选

返回

  • 返回信号订阅标识符,若path_namespace为table类型,则返回信号订阅标识符数组

异常

示例

lua
local subscribe_signal = require 'mc.mdb.subscribe_signal'
subscribe_signal.on_interfaces_added(bus, path_namespace, cb, expected_intf)

on_interfaces_removed(bus, path_namespace, cb, expected_intf)

描述

  • 订阅接口删除信号

参数

参数类型描述是否必选
bususerdatadbus服务必选
path_namespacestring或tabledbus对象路径必选
cbfunction接口新增时触发的回调函数必选
expected_intfstring期望订阅的接口名称必选

返回

  • 返回信号订阅标识符,若path_namespace为table类型,则返回信号订阅标识符数组

异常

示例

lua
local subscribe_signal = require 'mc.mdb.subscribe_signal'
subscribe_signal.on_interfaces_removed(bus, path_namespace, cb, expected_intf)

自发现回调注册

加载方式

lua
local mdb_manager = require 'mc.mdb.object_manage'

on_add_object(bus, cb, preprocess_cb)

描述

  • 用于注册对象新增回调
  • preprocess_cb有以下两个功能:
    1. 特定场景下需要业务补全属性后再进行持久化恢复
    2. 如果preprocess_cb返回true则立刻进行资源上树,否则业务自己上树

参数

参数类型描述是否必选
bususerdatadbus服务必选
cbfunction对象新增回调函数必选
preprocess_cbfunction补全属性以及控制上树可选

返回

异常

示例

lua
local mdb_manager = require 'mc.mdb.object_manage'
mdb_manager.on_add_object(bus, cb, preprocess_cb)

on_delete_object(bus, cb)

描述

  • 用于注册对象删除回调

参数

参数类型描述是否必选
bususerdatadbus服务必选
cbfunction对象删除回调函数必选

返回

异常

示例

lua
local mdb_manager = require 'mc.mdb.object_manage'
mdb_manager.on_delete_object(bus, cb)

on_add_object_complete(bus, cb)

描述

  • 用于注册对象新增完成回调

参数

参数类型描述是否必选
bususerdatadbus服务必选
cbfunction对象新增完成回调函数必选

返回

异常

示例

lua
local mdb_manager = require 'mc.mdb.object_manage'
mdb_manager.on_add_object_complete(bus, cb)

on_delete_object_complete(bus, cb)

描述

  • 用于注册对象删除完成回调

参数

参数类型描述是否必选
bususerdatadbus服务必选
cbfunction对象删除完成回调函数必选

返回

异常

示例

lua
local mdb_manager = require 'mc.mdb.object_manage'
mdb_manager.on_delete_object_complete(bus, cb)

配置管理

提供接口对bmc.kepler.MicroComponent.ConfigManage接口下的方法进行实现

加载方式

lua
local mdb_config_manage = require 'mc.mdb.micro_component.config_manage'

on_import(cb)

描述

  • 注册配置导入Import方法的回调

参数

参数类型描述是否必选
cbfunction配置导入Import方法的回调函数必选

返回

异常

示例

lua
local mdb_config_manage = require 'mc.mdb.micro_component.config_manage'
mdb_config_manage.on_import(cb)

on_export(cb)

描述

  • 注册配置导出Export方法的回调

参数

参数类型描述是否必选
cbfunction配置导出Export方法的回调函数必选

返回

异常

示例

lua
local mdb_config_manage = require 'mc.mdb.micro_component.config_manage'
mdb_config_manage.on_export(cb)

on_backup(cb)

描述

  • 注册备份Backup方法的回调

参数

参数类型描述是否必选
cbfunction备份Backup方法的回调函数必选

返回

异常

示例

lua
local mdb_config_manage = require 'mc.mdb.micro_component.config_manage'
mdb_config_manage.on_backup(cb)

on_recover(cb)

描述

  • 注册还原Recover方法的回调

参数

参数类型描述是否必选
cbfunction还原Recover方法的回调函数必选

返回

异常

示例

lua
local mdb_config_manage = require 'mc.mdb.micro_component.config_manage'
mdb_config_manage.on_recover(cb)

调试命令

提供接口对bmc.kepler.MicroComponent.Debug接口下的方法进行实现

加载方式

lua
local intf_debug = require 'mc.mdb.micro_component.debug'

on_dump(cb)

描述

  • 注册一键收集Dump方法的回调

参数

参数类型描述是否必选
cbfunction一键收集Dump方法的回调函数必选

返回

异常

示例

lua
local intf_debug = require 'mc.mdb.micro_component.debug'
intf_debug.on_dump(cb)

重启操作

描述

  • 提供接口对bmc.kepler.MicroComponent.Reboot接口下的方法进行实现

加载方式

lua
local reboot = require 'mc.mdb.micro_component.reboot'

on_prepare(cb)

描述

  • 注册重启前准备操作Prepare方法的回调

参数

参数类型描述是否必选
cbfunction重启前准备操作Prepare方法的回调函数必选

返回

异常

示例

lua
local reboot = require 'mc.mdb.micro_component.reboot'
reboot.on_prepare(cb)

on_action(cb)

描述

  • 注册善后操作Action方法的回调

参数

参数类型描述是否必选
cbfunction善后操作Action方法的回调函数必选

返回

异常

示例

lua
local reboot = require 'mc.mdb.micro_component.reboot'
reboot.on_action(cb)

on_cancel(cb)

描述

  • 注册组件回退操作Cancel方法的回调

参数

参数类型描述是否必选
cbfunction组件回退操作Cancel方法的回调函数必选

返回

异常

示例

lua
local reboot = require 'mc.mdb.micro_component.reboot'
reboot.on_cancel(cb)

微组件信息

提供接口对bmc.kepler.MicroComponent接口下的方法进行实现,bmc.kepler.MicroComponent接口下属性承载组件的信息

组件信息

Name:组件名 Version:组件版本 Author:组件作者 Pid:进程id Status:组件状态

加载方式

lua
local mc_component = require 'mc.mdb.micro_component'

on_health_check(cb)

描述

  • 注册健康状态检查HealthCheck方法的回调

参数

参数类型描述是否必选
cbfunction健康状态检查HealthCheck方法的回调函数必选

返回

异常

示例

lua
local mc_component = require 'mc.mdb.micro_component'
mc_component.on_health_check(cb)

task模块

加载方式

lua
local task_mgmt = require 'mc.mdb.task_mgmt'

create_task(bus, name, path, timeout, timeout_cb)

描述

  • 创建任务

参数

参数类型描述是否必选
bususerdatadbus服务必选
namestringtask名称必选
pathstring资源树path必选
timeoutinteger任务总时长,单位为分钟可选
timeout_cbfunction超时回调函数可选

返回

  • 执行成功时,返回三个值:TASK_CREATE_SECCESSFUL, nil, id TASK_CREATE_SECCESSFUL类型为integer,值为0 id即任务id

异常

  • 若timeout不为nil且小于0,则抛异常
  • 若任务总数超过最大限制(32个),则抛异常

示例

lua
local task_mgmt = require 'mc.mdb.task_mgmt'
local create_code = task_mgmt.create_code

local name = 'test'
local path = '/bmc/kepler/UpdateService'
local timeout = 30

-- timeout设置任务总时长30分钟,默认不限制时长
local create, err, id = task_mgmt.create_task(dbus, name, path, timeout)
-- create为0则创建成功,create_code枚举包括:TASK_CREATE_SUCCESSFUL、TASK_NUMBER_OF_TASKS_REACHES_MAXIMUM、TASK_TIMEOUT_IS_OUT_OF_RANGE
assert(create, create_code.TASK_CREATE_SUCCESSFUL)
-- 当创建不成功时,接口返回错误对象err,可以用来抛错
error(err)

update_task(id, data)

描述

  • 更新任务信息

参数

参数类型描述是否必选
bususerdatadbus服务必选
idinteger任务id必选
datatable任务信息,包含了State、Progress、Parameters等信息必选

返回

  • 执行成功时,返回TASK_CREATE_SECCESSFUL TASK_CREATE_SECCESSFUL类型为integer,值为0

异常

  • 若id对应的task不存在,则输出错误日志,返回错误码
  • 若data类型不为table,则输出错误日志,返回错误码
  • 若data的数据,如State、Progress、Parameters等类型不符合要求,则输出错误日志,返回错误码
元素类型
Progressnumber,范围0~100
Statestring
Statusstring
Parameterstable
MessageIdstring
MessageArgstable

示例

lua
local task_mgmt = require 'mc.mdb.task_mgmt'

local task_state = task_mgmt.state
local task_status = task_mgmt.status
local update_code = task_mgmt.update_code

-- data表中可更新任意部分数据,不一定要全部字段一并更新
local data = {
    Progress = 50, -- 进度为0-100
    -- 任务执行状态包括:New(默认)、Starting、Running、Suspended、Interrupted、Pending、Stopping、Completed、Killed、Exception、Cancelled
    State = task_state.Running,
    -- 任务状况包括:OK(默认)、Warning、Error、Critical
    Status = task_status.OK,
    Parameters = { -- 填写任务附加信息
        key1 = 1,
        key2 = 2
    },
    MessageId = 'IncorrectImageLength', -- 可以从错误引擎中获取
    MessageArgs = {'1', '2', '3'} -- 错误参数参照错误引擎输入
}

local update = task_mgmt.update_task(id, data) -- 返回的update是错误码,具体见下
assert(update, update_code.TASK_UPDATE_SUCCESSFUL)

update_code中的枚举包括:

  • TASK_UPDATE_SUCCESSFUL:0,成功
  • TASK_ID_DO_NOT_EXIST:-1,id不存在
  • TASK_DATA_IS_NOT_TABLE:-2,data不是表
  • TASK_PROGRESS_OUTOFRANGE:-3,Progress进度更新超出0-100
  • TASK_STATE_OUTOFRANGE:-4,State更新超范围
  • TASK_STATUS_OUTOFRANGE:-5,Status更新超范围
  • TASK_PARAMETERS_IS_NOT_TABLE:-6,Parameters不是表
  • TASK_MESSAGEID_IS_NOT_STRING:-7,MessageId不是字符串
  • TASK_MESSAGEARGS_IS_NOT_TABLE:-8,MessageArgs不是表
  • TASK_ENDED:-9,任务已结束

正常结束任务示例

lua
local task_mgmt = require 'mc.mdb.task_mgmt'
local task_state = task_mgmt.state
local task_status = task_mgmt.status

-- 当Progress为100,或State为'Completed'时,将在10分钟后销毁任务
data = {
    Progress = 100, -- 设置Progress或State都可以结束任务
    State = task_state.Completed,
    Parameters = {…},

}

update = task_mgmt.update_task(id, data)

异常结束任务示例

lua
local task_mgmt = require 'mc.mdb.task_mgmt'
local task_state = task_mgmt.state
local task_status = task_mgmt.status

-- 当State为'Exception'或'Cancelled'时,同样会结束任务
data = {
    State = task_state.Exception, -- 或者设置为task_state.Cancelled
    Status = task_status.Critical
    Parameters = {…},

}

update = task_status.update_task(id, data)

destroy_task(id)

描述

  • 获取与销毁任务资源树对象

参数

参数类型描述是否必选
idinteger任务id必选

返回

  • 执行成功时,返回true

异常

示例

lua
local task_mgmt = require 'mc.mdb.task_mgmt'
-- 只能获取到本服务的任务,不能获取到其他服务
local obj = task_mgmt.get_task_obj(id)

print('Progress: ', obj.Progress)

-- 只能销毁本服务的任务资源树对象
task_mgmt.destroy_task(id)

task_mgmt使用注意事项

在资源树接口中使用时,为了使任务信息能够先返回,请使用异步机制执行任务

示例

lua
local task_mgmt = require 'mc.mdb.task_mgmt'
local create_code = task_mgmt.create_code

local name = 'test'
local path = '/bmc/kepler/UpdateService'
local timeout = 30

-- 假设这个是资源树的执行回调
local function upgrade()
    -- 任务创建后会注册一个资源树对象
    -- /bmc/kepler/UpdateService/TaskService/Tasks/:id
    local create, err, id = task_mgmt.create_task(dbus, name, path, timeout)
    -- 业务处理放到协程中处理,因为任务本身就是并行场景,而且还会涉及抛错或其他异常的场景,可能导致无法给前端接口返回任务id
    skynet.fork_once(function()
        task_mgmt.update_task(...) -- 更新任务信息
    end)
    -- 需要确保资源树接口的返回是任务id
    return id
end