后端企业应用运维【免费下载链接】bk-cmdb蓝鲸智云配置平台(BlueKing CMDB)项目地址https://gitcode.com/gh_mirrors/bk/bk-cmdb点击查看免费下载本文以蓝鲸智云配置平台BlueKing CMDB仓库目录bk-cmdb对外提供的资源池主机查询接口list_resource_pool_hosts为核心系统讲解其请求参数结构、host_property_filter组合过滤语法、分页与字段裁剪用法、响应数据结构并结合仓库源码剖析该接口从网关鉴权、资源池定位到 coreservice 底层查询的完整调用链。读者读完本文后可以独立构造出符合规范的请求体掌握多层级 AND/OR 过滤规则的编写技巧并理解参数校验与权限控制的具体边界。一、接口概览查询资源池中的主机资源池Resource Pool又称主机池是蓝鲸 CMDB 中用于存放暂未分配到具体业务的主机的公共区域。主机被录入 CMDB 后若尚未归属到某个业务便会进入资源池list_resource_pool_hosts接口正是用于查询这些资源池主机的开放 API典型应用场景包括主机导入后的状态核对、资源池库存盘点、与业务内主机列表进行对账等。项目内容接口路径POST /api/v3/hosts/list_resource_pool_hosts权限要求具备资源池主机的查看权限文档原文View permission for hosts in the host pool鉴权动作在权限体系中对应view_resource_pool_host查看资源池主机动作见 src/ac/iam/types.go请求/响应格式JSON从源码看该接口的服务端路由注册于 src/scene_server/host_server/service/service_initfunc.go由ListResourcePoolHosts处理器Handler承接网关层鉴权规则定义在 src/ac/parser/host.go匹配findResourcePoolHostsPattern /api/v3/hosts/list_resource_pool_hosts后将其归入HostInstance资源类型的FindMany批量查看动作。二、请求参数详解接口请求体包含三个顶层可选参数具体说明如下英文原文档见 docs/apidoc/apigw/open/en/list_resource_pool_hosts.md参数名类型必填说明pagedict否分页查询条件控制起始位置、每页数量与排序host_property_filterobject否主机属性组合查询条件用于按主机属性字段筛选主机fieldsarray否主机属性字段列表控制返回结果中携带哪些字段可加快接口响应、减少网络流量不填则默认返回全部字段2.1 page分页参数名称类型必填说明startint是记录起始位置从 0 开始limitint是每页记录数最大为 500sortstring否排序字段对应的 Go 结构体为metadata.BasePage分页校验逻辑位于 src/common/metadata/page.gostart不得小于 0limit必须大于 0在ListHostsParameter.Validate()中会进一步通过Page.Validate(false)检查limit是否超过common.BKMaxPageSize值为 1000定义于 src/common/definitions.go。而文档声明的单页上限 500 与BKMaxLimitSize 500src/common/definitions.go一致实战中建议将limit控制在 500 以内避免触发校验失败或超时。2.2 fields字段裁剪fields是一个字符串数组例如[bk_host_id, bk_cloud_id, bk_host_innerip]。传入后响应中的每条主机记录将只包含这些字段留空时返回该主机全部属性字段。该参数对于大范围查询、弱网环境下的数据拉取尤其重要——只请求需要的字段可以显著降低响应体体积与网络传输开销。2.3 host_property_filter主机属性组合过滤host_property_filter用于基于主机属性字段搜索主机支持 AND 与 OR 两种组合关系可嵌套且最多嵌套 2 层即规则树的整体深度不超过 3。名称类型必填说明conditionstring否组合条件关系取值为AND或ORrulesarray否规则列表每个元素可以是原子规则或嵌套的组合规则源码层面对该约束给出了硬性校验参数结构体ListHostsParameter在 src/common/metadata/hostserver.go 中定义其Validate()会调用option.HostPropertyFilter.Validate(...)并通过GetDeep() querybuilder.MaxDeep判断嵌套深度。querybuilder.MaxDeep定义于 src/common/querybuilder/types.go注释明确指出嵌套层级的深度按树的高度计算查询条件最大深度为 3 即最多嵌套 2 层。同时该校验还要求同一数组中的元素类型一致NeedSameSliceElementType: true即in/not_in的取值数组内元素类型必须统一。2.4 rules过滤规则的 field / operator / value 三元组rules中的每个原子过滤规则由field、operator、value三个字段构成原文档中称为四元组 quadruples实际即这三个属性字段名称类型必填说明fieldstring是主机属性字段名如bk_os_type、bk_host_outeripoperatorstring是操作符可选值为equal、not_equal、in、not_in、less、less_or_equal、greater、greater_or_equal、between、not_betweenvalue-否操作数不同操作符对应不同的值格式如in需要数组less需要数值关于规则组装与操作符的完整语义说明原文档指向的链接对应仓库内的 src/common/querybuilder/README.md该文档详细描述了查询参数如何被解析为 MongoDB 过滤条件通用操作符equal相等、not_equal不等值格式为基本数据类型数值/布尔/字符串数组操作符in属于集合、not_in不属于集合值必须是同类型基本数据组成的数组数字操作符less、less_or_equal、greater、greater_or_equal值为数值时间操作符datetime_less、datetime_less_or_equal、datetime_greater、datetime_greater_or_equal值使用 RFC3339 格式字符串字符串操作符begins_with、not_begins_with、contains、not_contains、ends_with、not_ends_with值为非空字符串空值操作符is_null、is_not_null、is_empty、is_not_empty不接受参数。文档所列的between/not_between属于范围比较操作符。需要说明的是querybuilder 内部注释提到其不支持between/not_between建议基于基本比较运算符组合实现见 src/common/querybuilder/README.md而本接口文档明确将其列为可选值说明该接口对外仍兼容这两种操作符实战中以接口文档声明为准即可。三、完整请求示例以下请求体综合使用了分页、字段裁剪与两层嵌套的组合过滤可直接复制使用{ page: { start: 0, limit: 10, sort: bk_host_id }, fields: [ bk_host_id, bk_cloud_id, bk_host_innerip, bk_os_type, bk_mac ], host_property_filter: { condition: AND, rules: [ { field: bk_host_outerip, operator: equal, value: 127.0.0.1 }, { condition: OR, rules: [{ field: bk_os_type, operator: not_in, value: [3] }, { field: bk_sla, operator: equal, value: 1 }] }] } }语义解读查询满足公网 IP 等于 127.0.0.1且操作系统类型不属于 3或SLA 等级等于 1的资源池主机按bk_host_id升序分页每页 10 条仅返回指定的 5 个字段。其中第 2 层OR嵌套正好体现了最多嵌套 2 层的边界用法。四、响应结构解析4.1 公共响应体名称类型说明resultbool请求是否成功true 成功false 失败codeint错误码0 表示成功0 表示失败messagestring失败时返回的错误信息permissionobject权限信息dataobject接口返回的数据说明原文档表格中data的类型标注为 array但从实际响应示例看data是一个包含count与info两个字段的对象结构使用时应以示例结构为准。4.2 data查询结果名称类型说明countint记录总数infoarray实际数据主机列表4.3 data.info主机属性字段下表列出了系统内置built-in主机属性字段及其含义。注意此处仅解释系统内置属性字段其余返回字段取决于各租户自定义的属性字段。名称类型说明bk_host_namestring主机名bk_host_inneripstring内网 IPbk_host_idint主机 IDbk_cloud_idint管控区域import_fromstring主机导入来源3 表示 API 导入bk_asset_idstring固定资产编号bk_cloud_inst_idstring云主机实例 IDbk_cloud_vendorstring云厂商bk_cloud_host_statusstring云主机状态bk_commentstring备注bk_cpuintCPU 逻辑核数bk_cpu_architecturestringCPU 架构bk_cpu_modulestringCPU 型号bk_diskint磁盘容量GBbk_host_outeripstring公网 IPbk_host_innerip_v6string内网 IPv6bk_host_outerip_v6string公网 IPv6bk_isp_namestring运营商名称bk_macstring内网 MAC 地址bk_memint内存容量MBbk_os_bitstring操作系统位数bk_os_namestring操作系统名称bk_os_typestring操作系统类型bk_os_versionstring操作系统版本bk_outer_macstring公网 MAC 地址bk_province_namestring省份bk_service_termint保修年限bk_slastringSLA 等级bk_snstring设备 SNbk_statestring当前状态bk_state_namestring国家operatorstring主要维护人bk_bak_operatorstring备份维护人4.4 响应示例{ result: true, code: 0, message: success, permission: null, data: { count: 1, info: [ { bk_cloud_id: 0, bk_host_id: 17, bk_host_innerip: 192.168.1.1, bk_mac: , bk_os_type: 1 } ] } }五、源码级实现剖析5.1 路由注册与网关鉴权接口处理器ListResourcePoolHosts定义于 src/scene_server/host_server/service/findhost.go通过utility.AddHandler(rest.Action{Verb: http.MethodPost, Path: /hosts/list_resource_pool_hosts, ...})注册。网关侧api/v3前缀路径在 src/ac/parser/host.go 命中findResourcePoolHostsPattern后将请求标记为HostInstance类型、FindMany动作随后交由权限中心判断调用方是否持有view_resource_pool_host权限。5.2 资源池的定位默认业务 供应商账户匹配从 findhost.go 的实现可以看到资源池并非独立的物理存储而是逻辑上归属于默认业务default biz服务端首先构造过滤条件{ default: 1 }common.BKDefaultField与common.DefaultAppFlag 1见 src/common/definitions.go、src/common/definitions.go查询默认业务实例若存在多个默认业务则只选用与请求头supplier_account一致的业务否则直接返回CCErrCommGetMultipleObject错误最终以该业务 ID 作为BizID调用底层主机查询。这也解释了为什么调用该接口时无需显式传业务 ID——资源池业务由系统自动定位。5.3 底层查询链路处理器在定位默认业务后调用listBizHostssrc/scene_server/host_server/service/findhost.go构造meta.ListHosts并请求 coreservice 的Host().ListHosts。coreservice 侧入口位于 src/source_controller/coreservice/service/hostsearch.go最终落到 src/source_controller/coreservice/core/host/searcher/searcher.go 的Searcher.ListHosts该实现会先将host_property_filter通过option.GetHostPropertyFilter()内部调用querybuilder的ToMgo()转换为 MongoDB 过滤条件再与关系过滤、归属过滤util.SetQueryOwner合并为最终的$and查询条件执行。5.4 参数校验边界综合 src/common/metadata/hostserver.go 的ListHostsParameter.Validate()与处理器中的前置校验可归纳出以下边界page.start不能为负page.limit必须大于 0若传了bk_set_ids则不能再传set_condbk_module_ids与module_cond同理二者互斥bk_set_ids最多 200 个bk_module_ids最多 500 个超出返回参数非法错误host_property_filter中数组操作符in/not_in的数组元素类型必须一致嵌套深度不得超过 2 层MaxDeep 3。需要留意的是本接口的处理器直接复用listBizHosts其内部通过parameter.Page.IsIllegal()校验分页参数见 src/scene_server/host_server/service/findhost.go非法时会以CCErrCommParamsInvalid报错。六、使用建议与注意事项优先使用fields裁剪返回字段资源池主机数量通常较大按需取字段可显著降低响应体积与传输耗时不传fields会返回全部含自定义属性字段。控制单页limit与翻页方式单页上限 500需要全量拉取时可采用start递增的方式循环请求或配合sort保证分页顺序稳定如按bk_host_id排序。善用嵌套过滤但不要超过 2 层host_property_filter的 AND/OR 组合足够表达绝大多数筛选需求超过 2 层嵌套会直接触发exceed max query condition deepth: 3校验错误。保持in/not_in数组元素类型一致混合类型数组会被校验拒绝。权限准备调用方需具备资源池主机的查看权限view_resource_pool_host否则请求会被网关拦截返回无权限错误。理解自定义字段响应中的data.info除系统内置字段外还会包含业务自定义的主机属性字段解析时不要对字段集合做硬编码假设。赞分享后端企业应用运维【免费下载链接】bk-cmdb蓝鲸智云配置平台(BlueKing CMDB)项目地址https://gitcode.com/gh_mirrors/bk/bk-cmdb点击查看免费下载相关推荐蓝鲸 CMDB 主机身份查询接口 search_hostidentifier 全面解析参数、实现原理与实战示例蓝鲸 CMDB 主机身份查询接口 search_hostidentifier 全面解析参数、实现原理与实战示例 导读 search_hostidentif后端企业应用运维bk-cmdb 蓝鲸配置平台「添加主机到资源池」接口详解参数、源码实现与批量处理语义bk cmdb 蓝鲸配置平台「添加主机到资源池」接口详解参数、源码实现与批量处理语义 导读 本文围绕蓝鲸智云配置平台bk cmdb开放 API 中的 ad后端企业应用运维telepresence compose stats 命令详解在 Kubernetes 本地开发中实时监控 Docker 容器资源占用telepresence compose stats 命令详解在 Kubernetes 本地开发中实时监控 Docker 容器资源占用 telepresenc后端企业应用运维创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考