后端企业应用运维【免费下载链接】bk-cmdb蓝鲸智云配置平台(BlueKing CMDB)项目地址https://gitcode.com/gh_mirrors/bk/bk-cmdb点击查看免费下载本文聚焦蓝鲸智云配置平台bk-cmdb开放接口APIGateway open API中的「查询业务Search Business」接口完整讲解其请求参数、组合过滤条件biz_property_filter、分页与时间条件用法、响应结构并结合 toposerver 业务实例查询实现 与 apiserver 转发链路 剖析其底层原理与安全约束。读完本文你将能够独立构造查询业务的请求报文理解归档/非归档业务查询语义并掌握过滤条件在服务端如何被校验与转换为 MongoDB 查询。一、接口概览能力与使用场景search_business是蓝鲸 CMDB 向外部系统如 SaaS 应用、运维自动化平台开放的业务查询接口用于按业务属性如业务名称、运维人员、业务 ID检索业务列表。它在本仓库中的完整调用链为开放网关APIGateway将请求转发到 apiserverapiserver 通过 BizFilterChan 过滤器 把/biz/search/...路由转发到 toposerver 的/topo/v3/app/search见 service.go 路由注册根路径为/api/v3定义于 type.gotoposerver 的 SearchBusiness 处理请求校验参数 → 读取业务自定义属性 → 解析过滤条件 → 鉴权 → 调用BusinessOperation().FindBiz完成数据库查询。该接口支持按任意业务属性含用户自定义字段做多条件组合查询、按时间范围过滤、分页与排序是平台化资产盘点、业务权限对账等场景的基础能力。调用该接口需要具备业务查询权限Business Query Permission。二、请求参数全解析接口为 POST 请求请求体为 JSON。参数如下参数名类型必填说明bk_supplier_accountstring否开发商账号Supplier Accountfieldsarray否指定返回字段不填则返回业务全部字段conditiondict否业务任意属性的查询条件不填表示查询全部数据。该字段为历史遗留字段请勿继续使用推荐改用 biz_property_filterbiz_property_filterobject否业务属性组合查询条件time_conditionobject否按时间查询业务的条件pagedict否分页条件2.1 归档业务与非归档业务的查询语义业务分为非归档业务与归档业务两类二者在查询时的语义差异由服务端实现强制保证查询归档业务需在condition中增加bk_data_status: disabled条件查询非归档业务不要携带bk_data_status字段或显式添加bk_data_status: {$ne: disabled}服务端兜底逻辑在 SearchBusiness 实现 中当请求未显式传入bk_data_status时服务端会自动追加bk_data_status: {$ne: disabled}同时强制default 0即只返回普通业务、不返回资源池业务资源池业务的default值为 1。注意归档业务的查询依赖历史condition字段与下方biz_property_filter的限制两者不可同时生效需一并留意。2.2 关键约束biz_property_filter与condition只能有一个生效服务端在 SearchBusiness 入口 直接拒绝二者同时设置的请求返回参数非法错误CCErrCommParamsInvalid并明确提示不推荐继续使用conditionbiz_property_filter中涉及的数组元素个数不超过 500rules数量不超过 20嵌套层级不超过 3。这些数值并非文档随意约定而是硬编码于 querybuilder 常量MaxDeep 3、DefaultMaxSliceElementsCount 500、DefaultMaxConditionOrRulesCount 20服务端通过Validate(option)与GetDeep()双重校验强制实施。三、biz_property_filter业务属性组合过滤条件biz_property_filter是本接口推荐使用的组合查询条件结构上是一棵由聚合条件 规则数组递归组成的过滤树。3.1 结构定义biz_property_filter顶层为聚合条件名称类型必填说明conditionstring是聚合条件取值AND/ORrulesarray是聚合条件下的规则数组每个rules元素原子规则定义名称类型必填说明fieldstring是业务属性字段名operatorstring是操作符valueobject是操作值rules中的元素既可以是原子规则也可以是嵌套的聚合条件conditionrules由此形成最多 3 层即最多嵌套 2 层的过滤树。3.2 可用操作符根据 querybuilder 操作符文档 与 types.go 校验表operator支持以下取值通用equal、not_equal值为数值 / bool / 字符串数组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_empty、is_not_empty字段状态exist、not_exist不接受参数3.3 服务端处理链路在 SearchBusiness 中biz_property_filter依次经过Validate(option)校验规则合法性、数组元素类型一致性、元素个数与规则数量上限GetDeep() querybuilder.MaxDeep校验嵌套深度不超过 3ToMgo()将过滤树转换为 MongoDB 查询条件替换原condition作为最终查询条件。这一套规则树 → 校验 → Mongo 条件的通用机制由 querybuilder 模块 提供AtomRule表示原子规则CombinedRule表示组合规则RuleParser负责从map[string]interface{}解析规则实例并已在 types_test.go 等测试中对深度超限等场景做了验证。3.4 组合过滤示例以下示例同时满足bk_biz_maintainer admin且bk_biz_name ∈ [test]或bk_biz_id 1{ biz_property_filter: { condition: AND, rules: [ { field: bk_biz_maintainer, operator: equal, value: admin }, { condition: OR, rules: [ { field: bk_biz_name, operator: in, value: [test] }, { field: bk_biz_id, operator: equal, value: 1 } ] } ] } }四、time_condition按时间范围查询time_condition用于按业务的时间字段如create_time做范围过滤结构与biz_property_filter类似字段类型必填说明operstring是操作符当前仅支持andrulesarray是时间查询条件数组rules中每个时间项包含field时间字段名、start起始时间、end截止时间。底层实现在 TimeCondition 结构体 与 MergeTimeCondition服务端校验oper必须为and、rules非空并将bk_created_at归一化为create_time、bk_updated_at归一化为last_time后合入查询条件。示例time_condition: { oper: and, rules: [ { field: create_time, start: 2021-05-13 01:00:00, end: 2021-05-14 01:00:00 } ] }五、page分页与排序名称类型必填说明startint是记录起始位置limitint是每页条数最大 200sortstring否排序字段字段前加-如sort: -field表示按该字段降序排列limit的上限与 BasePage 结构体 的校验逻辑一致start与limit不得小于 0limit超过系统最大页大小BKMaxPageSize时将直接报错。六、请求示例完整报文{ fields: [bk_biz_id, bk_biz_name], biz_property_filter: { condition: AND, rules: [ { field: bk_biz_maintainer, operator: equal, value: admin }, { condition: OR, rules: [ { field: bk_biz_name, operator: in, value: [test] }, { field: bk_biz_id, operator: equal, value: 1 } ] } ] }, time_condition: { oper: and, rules: [ { field: create_time, start: 2021-05-13 01:00:00, end: 2021-05-14 01:00:00 } ] }, page: { start: 0, limit: 10, sort: } }七、响应示例与字段说明成功响应{ result: true, code: 0, message: , permission: null, data: { count: 1, info: [ { bk_biz_id: 1, bk_biz_name: esb-test, default: 0 } ] } }响应通用字段名称类型说明resultbool请求是否成功true 成功false 失败codeint错误码0 表示成功0 表示失败messagestring请求失败时返回的错误信息dataobject返回数据permissionobject权限信息data字段名称类型说明countint记录总数infoarray业务实际数据info中系统内置属性字段名称类型说明bk_biz_idint业务 IDbk_biz_namestring业务名称bk_biz_maintainerstring运维人员bk_biz_productorstring产品人员bk_biz_developerstring开发人员bk_biz_testerstring测试人员time_zonestring时区languagestring语言1 中文2 英文bk_supplier_accountstring开发商账号create_timestring创建时间last_timestring更新时间defaultint业务类型operatorstring主要维护人life_cyclestring业务生命周期bk_created_atstring创建时间bk_updated_atstring更新时间bk_created_bystring创建者注意上表仅列出系统内置属性字段其余返回字段取决于用户自定义的业务属性。八、权限与数据安全源码级实现要点SearchBusiness在完成参数解析后还会执行两层安全收敛见 inst_business.go#L674-L744IAM 鉴权收敛当鉴权组件AuthManager.Enabled()开启时服务端调用ListAuthorizedResources获取当前用户被授权的业务资源。若用户拥有全部业务权限IsAny则按请求中的bk_biz_id收敛否则只允许查询已授权业务 ID 列表内的数据无权限时直接返回count: 0的空结果数据默认约束强制过滤归档业务bk_data_status ! disabled与资源池业务default 0避免外部系统误触数据边界。此外服务端还会调用 ReadModelAttr 读取业务模型的用户类型字段并通过 handleSpecialBusinessFieldSearchCond 对用户类字段做精确匹配正则转换保证人员字段的查询语义正确。九、常见问题排查建议biz_property_filter与condition同时传参请求会被直接拒绝condition and biz_property_filter cannot be set at the same time请只使用其中一种优先使用biz_property_filter过滤树过深/规则过多超过 3 层嵌套、500 个数组元素或 20 条规则上限时服务端返回参数非法错误请拆分查询或简化条件查询不到已归档业务默认查询只返回非归档业务如需归档业务请在condition中显式携带bk_data_status: disabled返回字段不符预期fields未指定时返回全部字段含用户自定义属性指定后仅返回所列字段部分字段如create_time只在显式查询时出现。赞分享后端企业应用运维【免费下载链接】bk-cmdb蓝鲸智云配置平台(BlueKing CMDB)项目地址https://gitcode.com/gh_mirrors/bk/bk-cmdb点击查看免费下载相关推荐蓝鲸配置平台 bk-cmdb 查询项目Search Project接口完全指南参数详解、过滤规则与源码实现蓝鲸配置平台 bk cmdb 查询项目Search Project接口完全指南参数详解、过滤规则与源码实现 本文围绕 bk cmdb蓝鲸智云配置平台开后端企业应用运维蓝鲸 CMDB 集群查询接口 search_set 实战指南参数详解、filter 过滤与源码实现蓝鲸 CMDB 集群查询接口 search_set 实战指南参数详解、filter 过滤与源码实现 导读 本文围绕蓝鲸智云配置平台BlueKing CMDB后端企业应用运维蓝鲸 CMDB 全量同步缓存条件查询接口 list_full_sync_cond_for_cache 使用详解蓝鲸 CMDB 全量同步缓存条件查询接口 list_full_sync_cond_for_cache 使用详解 本文面向需要在蓝鲸智云配置平台bk cmdb后端企业应用运维创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考