NetBox Saved Filters 完全指南：UI 与 REST API 中的可复用对象过滤方案

后端网络数据建模【免费下载链接】netboxThe premier source of truth powering network automation. Open source under Apache 2. Try NetBox Cloud free: https://netboxlabs.com/products/free-netbox-cloud/项目地址https://gitcode.com/gh_mirrors/ne/netbox点击查看免费下载导读Saved Filters已保存过滤器是 NetBox 中用于把一组复杂的对象过滤条件固化为可复用实体的标准方案广泛应用于设备、IP 地址、前缀等对象列表的日常运维与自动化场景。阅读本文后你将掌握 Saved Filter 的全部字段语义、JSON 参数格式、在 UI 与 REST API 中的创建与引用方式以及其底层在 NetBox 过滤器与权限体系中的执行机制。Saved Filters 是什么把过滤条件存档复用NetBox 中几乎所有对象列表设备、站点、IP 地址、VLAN 等都支持通过 URL 查询字符串进行多维过滤。当过滤策略涉及多个离散条件例如某区域内、指定平台、状态为计划中的所有设备时每次手动拼写这些条件既繁琐又易错。Saved Filter 正是为此设计用户将已应用的一组过滤条件保存为一条记录后续在 UI 和 REST API 中通过其 slug 一键复用。从数据模型看Saved Filter 由 netbox/extras/models/models.py 中的SavedFilter模型实现其本质是一组预定义的、可复用的关键字查询参数代码注释原文为A set of predefined keyword parameters that can be reused to filter for specific objects。它属于ChangeLoggedModel变更会被记录进对象变更日志同时继承OwnerMixin支持资源归属/所有者机制与CloningMixin支持克隆复制。核心字段全解析下表汇总了 Saved Filter 的全部字段及其语义其中字段定义可对照 SavedFilter 模型源码字段类型/默认值含义与关键细节nameCharFieldmax_length100唯一过滤器的人类可读名称slugSlugFieldmax_length100唯一过滤器被引用时的唯一标识例如?filtermy-slugdescriptionCharFieldmax_length200可空可选的补充说明object_typesManyToManyField → ContentType该过滤器适用的一个或多个对象类型如 site、rack、deviceuserFK → UserSET_NULL可空过滤器所属用户。UI 创建时自动赋值为当前用户且不可修改见下方UI 操作weightPositiveSmallIntegerField默认100数值权重用于覆盖按名称的字母排序权重越小排在越前面enabledBooleanField默认True是否可用。禁用后不出现在 UI 选项中但仍包含在 API 结果中sharedBooleanField默认True是否面向所有用户共享。注意置为 False 并不会对他人隐藏该过滤器只是将其从 UI 对象列表的可用过滤器中排除见下方共享与可见性parametersJSONField过滤器生效时要应用的查询参数必须为 JSON 对象字典owner来自 OwnerMixin资源所有者用于 NetBox 的资源归属与权限模型模型层面还包含两条细节约束默认排序Meta.ordering (weight, name)并建有(weight, name)联合索引models.py即列表默认按权重升序、名称升序呈现。参数校验模型clean()强制parameters必须是 dict否则抛出校验错误Filter parameters must be stored as a dictionary of keyword argumentsmodels.py从底层杜绝了非法格式。Parameters 字段JSON 与 URL 查询串的等价转换parameters字段是整个 Saved Filter 的核心它以JSON 对象形式存储过滤器生效时将要应用的查询参数与 URL 查询字符串一一等价。例如下面这条 URL 查询字符串?statusactiveregion_id51tagalphatagbravo对应的 JSON 表示为{ tag: [alpha, bravo], status: active, region_id: 51 }转换规则非常直观查询串中出现多次的键如tagalphatagbravo在 JSON 中表示为数组[alpha, bravo]查询串中只出现一次的键如statusactive在 JSON 中表示为单值active数值型参数如region_id51在 JSON 中保持为数值。底层转换机制模型提供了url_params只读属性用于把parameters字典还原为 URL 查询串。其实现调用utilities中的dict_to_querydict()工具把字典转换为 DjangoQueryDict再urlencode()输出models.py。因此parameters与 URL 查询串之间是双向无损转换的UI 中保存过滤器时也是把当前request.GET.lists()序列化成的 JSON 直接塞进parameters字段netbox/utilities/templatetags/helpers.py。注意parameters中可用的键名与取值必须与对应对象类型过滤器Filterset支持的参数一致例如设备过滤器支持status、region_id、tag等填写不存在的参数名不会报错但不会产生任何过滤效果。UI 操作保存与使用从对象列表保存在任一支持过滤的对象列表页如设备列表应用好过滤条件后列表页会出现保存过滤器入口仅在用户拥有extras.add_savedfilter权限、且 URL 中尚不存在filter_id参数时渲染见 helpers.py。点击后跳转到 Saved Filter 新增页面并自动携带当前对象类型object_types与当前全部查询参数parameters作为预填初始数据。填写名称name与 slug可选描述提交保存。表单层面对此有专门适配SavedFilterForm在收到initial[parameters]为字符串时会自动json.loads转为 JSONnetbox/extras/forms/model_forms.py而编辑视图alter_object()会在新建无主键时把obj.user强制赋值为request.usernetbox/extras/views.py这正是文档中当前用户会被自动分配且不可更改的底层实现。应用已保存过滤器保存后在对应对象类型的列表页中即可从可用过滤器中直接选用也可直接构造 URL对象列表路径?filterslug例如?filtermy-slug。这一机制由 NetBox 基础 Filterset 统一处理见下文引用与执行原理。管理与批量操作Saved Filter 自身也是标准的 NetBox 管理对象在Extras → Saved Filters菜单下netbox/netbox/navigation/menu.py提供完整的管理页面列表/详情/编辑/删除详情页以面板展示基本属性、适用对象类型SavedFilterObjectTypesPanel与 Parameters JSON 面板netbox/extras/views.py批量导入CSV支持通过 CSV 文件批量创建可导入字段包括name, slug, object_types, description, weight, enabled, shared, parameters, ownernetbox/extras/forms/bulk_import.py批量编辑 / 批量重命名 / 批量删除分别对应SavedFilterBulkEditView、SavedFilterBulkRenameView、SavedFilterBulkDeleteViewnetbox/extras/views.py。REST API 使用Saved Filter 通过 REST API 完整暴露端点位于/api/extras/saved-filters/由SavedFilterViewSet提供标准的列表/详情/创建/更新/删除操作netbox/extras/api/views.py。序列化字段SavedFilterSerializer暴露的字段包括id, url, display_url, display, object_types, name, slug, description, user, weight, enabled, shared, parameters, owner, created, last_updated简报模式brief仅返回id, url, display, name, slug, descriptionnetbox/extras/api/serializers_/savedfilters.py。object_types使用ContentTypeField表达可接收对象类型标识。创建示例curl -X POST https://netbox.example.com/api/extras/saved-filters/ \ -H Authorization: Token your-token \ -H Content-Type: application/json \ -H Accept: application/json; version4.7; \ -d { name: Planned devices in region 51 with alpha tag, slug: planned-region51-alpha, object_types: [dcim.device], weight: 10, enabled: true, shared: true, parameters: { status: planned, region_id: 51, tag: [alpha, bravo] } }在其他 API 请求中引用任何支持过滤的对象列表端点都可直接通过filter参数引用已保存过滤器例如curl -H Authorization: Token your-token \ -H Accept: application/json; version4.7; \ https://netbox.example.com/api/dcim/devices/?filterplanned-region51-alpha此外API 还支持以filter_id直接指定过滤器的数据库主键多个值可重复出现。这与 UI 通过?filterslug/?filter_idpk引用的机制完全一致。GraphQL 支持Saved Filter 同样可通过 GraphQL API 查询SavedFilterType暴露了该对象类型schema 中提供saved_filter单条与saved_filter_list列表两个查询入口且查询时遵循与 UI/REST 一致的共享可见性限制netbox/extras/graphql/types.py、netbox/extras/graphql/schema.py。引用与执行原理NetBox 如何展开 Saved FilterSaved Filter 的引用发生在过滤器集Filterset初始化阶段。NetBox 基础 FiltersetNetBoxFilterSet.__init__会检查请求数据data中是否含filter或filter_id将filter_id中的值尝试转换为整数忽略非法值仅查询当前请求用户可见的 Saved Filter调用restrict_to_shared按slug或pk匹配到过滤器后遍历其parameters把每个参数合并进请求数据列表值会appendlist单值会setlist实现展开展开后的完整数据再交给父类执行常规过滤netbox/netbox/filtersets.py。这段代码filtersets.py同时展示了两个重要行为引用权限只会应用当前用户有权看到的 Saved Filterrestrict_to_shared(user)无请求上下文时回退为匿名用户可见性仅共享过滤器多值合并语义若请求 URL 中已有同名参数Saved Filter 的参数会追加appendlist而不是覆盖便于在基础过滤上叠加条件。共享与可见性Shared、Enabled 与权限边界文档特别强调了两处容易混淆的语义此处结合源码给出准确解读enabled False禁用该过滤器不会作为选项出现在 UI 对象列表中但仍然会包含在 API 结果里。也就是说禁用是一个UI 层面的软开关并不影响通过 REST API 直接按 slug/pk 引用它。shared False不共享仅仅意味着该过滤器不会出现在 UI 对象列表页的可用过滤器列表中它并不会对他人隐藏——其他用户只要知道其 slug或通过 API 查询依然可以引用。底层可见性由SharedObjectQuerySet.restrict_to_shared()统一执行并被 UI、REST API、GraphQL 三端共用netbox/extras/querysets.py超级用户可见全部匿名用户仅可见sharedTrue的过滤器普通登录用户可见sharedTrue或user自己的过滤器。这也解释了 API 侧SavedFilterViewSet继承SharedObjectQuerySetMixin、以及所有 Saved Filter 视图继承SharedObjectViewMixin的原因netbox/extras/api/views.py三端保持一致的共享/本人可见性边界。其他实用特性克隆Cloningclone_fields (object_types, weight, enabled, parameters)models.py在 UI 详情页可基于现有过滤器快速复制生成新过滤器。对象类型多选一个 Saved Filter 可同时绑定多个object_types如同时适用于 site 与 rack表单使用ContentTypeMultipleChoiceField支持多选model_forms.py。测试覆盖仓库内置了针对 Saved Filter 的完整测试套件包括过滤器集测试覆盖q/name/slug/description等过滤维度netbox/extras/tests/test_filtersets.py、API 测试SharedObjectAPITestMixin与标准视图集测试netbox/extras/tests/test_api.py以及 UI 视图测试netbox/extras/tests/test_views.py可用于验证共享可见性、批量导入等行为是否符合预期。小结与最佳实践复杂过滤策略优先保存为 Saved Filter涉及多条件组合、且会被团队反复使用的过滤逻辑应保存为命名清晰的共享过滤器避免每次手工拼 URL。区分enabled与shared前者控制是否在 UI 列表中可选后者控制是否出现在可用过滤器下拉中两者都不构成严格的数据访问控制真正决定能否被引用的是restrict_to_shared的共享或本人可见性规则。合理使用weight把最常用的过滤器设为较小权重默认 100可让它们稳定地排在过滤器列表最前面摆脱字母序限制。JSON 参数务必与目标对象类型的 Filterset 参数对齐parameters中只应包含目标类型真实支持的查询参数取值格式单值/数组、数值/字符串应与 URL 查询串保持一致。API 自动化可直接引用在脚本或 CI 流程中通过/api/.../?filterslug或filter_idpk引用 Saved Filter能让自动化逻辑与 UI 使用的过滤口径保持完全一致。赞分享后端网络数据建模【免费下载链接】netboxThe premier source of truth powering network automation. Open source under Apache 2. Try NetBox Cloud free: https://netboxlabs.com/products/free-netbox-cloud/项目地址https://gitcode.com/gh_mirrors/ne/netbox点击查看免费下载相关推荐NetBox 全局搜索与保存过滤器Saved Filters完全指南NetBox 全局搜索与保存过滤器Saved Filters完全指南 引言 NetBox 作为一个以事实来源source of truth为核心的网后端网络数据建模Mem0 Platform REST API 完全指南端点、过滤系统与 Memory 对象详解Mem0 Platform REST API 完全指南端点、过滤系统与 Memory 对象详解 本篇技术指南以仓库 skills/mem0/reference人工智能AI AgentAgent 记忆RAG5分钟快速上手使用Kronos金融大模型进行智能市场预测5分钟快速上手使用Kronos金融大模型进行智能市场预测 Kronos是首个专为金融市场K线序列设计的开源基础模型能够将复杂的金融时间序列数据转化为可预测的后端网络数据建模上一篇Keras模型加载时Rescaling层问题的分析与解决下一篇Hiring Agent贡献指南如何为开源AI简历评估项目提交代码创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考