netbox-integration-best-practices

NetBox 集成最佳实践技能

此技能为使用 NetBox REST 和 GraphQL API 构建集成与自动化提供最佳实践指南。

目标受众

• 基于 NetBox API 构建集成的工程师
• 计划使用 Claude 开展新自动化工作的团队
• 学习 NetBox API 最佳实践的开发者

范围： 此技能涵盖 API 集成模式。不涵盖插件开发、自定义脚本或 NetBox 管理。

NetBox 版本要求

功能	所需版本
REST API	所有版本
GraphQL API	2.9+
v2 Tokens	4.5+（请使用这些！）
v1 Token 弃用	4.7+（请在此之前迁移）

主要目标： NetBox 4.4+；如需使用 v2 token 功能，则需 4.5+。

何时应用此技能

在以下情况下应用这些实践：

• 构建新的 NetBox API 集成
• 审查现有集成代码
• 排查性能问题
• 规划自动化架构
• 编写与 NetBox 交互的脚本

优先级

级别	说明	操作
CRITICAL	安全漏洞、数据丢失、严重性能问题	必须立即修复
HIGH	对性能或可靠性有显著影响	应尽快修复
MEDIUM	值得关注的改进、最佳实践	计划处理
LOW	细微改进、可选项	方便时考虑

快速参考

身份验证

• 在 NetBox 4.5+ 上使用 v2 tokens：Bearer nbt_<key>.<token>
• 在 NetBox 4.7 弃用 v1 之前迁移（计划弃用）

REST API

• 始终进行分页：?limit=100（最大值为 1000）
• 部分更新使用 PATCH，而不是 PUT
• 列表操作使用 ?brief=True
• 排除 config_context：?exclude=config_context（对性能影响很大）
• 大规模操作时避免使用 ?q= 搜索过滤器；改用具体过滤器
• 批量操作使用带 JSON 数组的列表端点（而非单独的端点）

GraphQL

• 使用查询优化器：netbox-graphql-query-optimizer
• 始终为每个列表查询分页
• 在每一层嵌套中进行分页
• 注意大规模场景下的偏移量分页：深层偏移速度很慢；在 4.5.x 中使用 ID 范围过滤，在 4.6.0+ 中使用基于游标的分页（#21110）
• 仅请求所需字段
• 深度保持在 ≤3，绝不超过 5

性能

• 从设备列表中排除 config_context
• 对大型列表使用简要模式
• 并行执行互不依赖的请求

数据摄取（Diode）

• 对于大批量数据摄取，请使用 Diode，而不是直接调用 API
• 按名称指定依赖项，而非 ID——Diode 会解析或创建依赖项
• 无需按依赖顺序排列——Diode 会处理对象创建顺序
• Python 使用 pip install netboxlabs-diode-sdk
• 使用 REST/GraphQL API 读取；使用 Diode 写入或填充数据

分支（插件）

需要 netbox-branching 插件。

• 生命周期：创建 → 等待（PROVISIONING→READY）→ 操作 → 同步 → 合并
• 上下文标头：X-NetBox-Branch: {schema_id}（8 字符 ID，而非名称）
• 异步操作：sync/merge/revert 会返回 Job 对象——轮询以等待完成
• 试运行：所有异步操作都接受 {"commit": false} 以进行验证

按类别划分的规则

身份验证规则

规则	影响	说明
auth-use-v2-tokens	CRITICAL	在 NetBox 4.5+ 上使用 v2 tokens
auth-provisioning-endpoint	MEDIUM	使用配置端点自动创建 token

REST API 规则

规则	影响	描述
rest-list-endpoint-bulk-ops	CRITICAL	使用列表端点执行批量操作
rest-pagination-required	HIGH	始终为列表请求分页
rest-patch-vs-put	HIGH	使用 PATCH 进行部分更新
rest-brief-mode	HIGH	列表使用 ?brief=True
rest-field-selection	HIGH	使用 ?fields= 选择字段
rest-exclude-config-context	HIGH	从设备列表中排除 config_context
rest-avoid-search-filter-at-scale	HIGH	大型数据集中避免使用 q=
rest-filtering-expressions	MEDIUM	使用查找表达式
rest-custom-field-filters	MEDIUM	按自定义字段筛选
rest-nested-serializers	LOW	了解嵌套序列化器
rest-ordering-results	LOW	使用排序参数
rest-options-discovery	LOW	使用 OPTIONS 进行发现

GraphQL 规则

规则	影响	描述
graphql-use-query-optimizer	CRITICAL	使用查询优化器
graphql-always-paginate	CRITICAL	为每个列表查询分页
graphql-pagination-at-each-level	HIGH	为嵌套列表分页
graphql-select-only-needed	HIGH	仅请求所需字段
graphql-calibrate-optimizer	HIGH	根据生产环境进行校准
graphql-max-depth	HIGH	将深度保持在 ≤3
graphql-prefer-filters	MEDIUM	在服务端筛选
graphql-vs-rest-decision	MEDIUM	选择合适的 API
graphql-complexity-budgets	LOW	制定复杂度预算

性能规则

规则	影响	描述
perf-exclude-config-context	HIGH	排除 config_context
perf-brief-mode-lists	HIGH	列表使用简要模式

数据建模规则

规则	影响	描述
data-dependency-order	CRITICAL	按依赖顺序创建对象
data-site-hierarchy	MEDIUM	了解站点层级结构
data-ipam-hierarchy	MEDIUM	了解 IPAM 层级结构
data-custom-fields	MEDIUM	正确使用自定义字段
data-tags-usage	MEDIUM	使用标签进行分类
data-tenant-isolation	MEDIUM	使用租户进行隔离
data-natural-keys	MEDIUM	使用自然键

集成规则

规则	影响	描述
integ-diode-ingestion	HIGH	使用 Diode 进行高容量数据摄取
integ-pynetbox-client	HIGH	Python 使用 pynetbox
integ-branch-api-workflow	HIGH	完成分支生命周期（插件）
integ-branch-context-header	HIGH	使用 X-NetBox-Branch 标头传递分支上下文（插件）
integ-branch-async-operations	MEDIUM	为同步／合并／还原轮询作业（插件）
integ-webhook-configuration	MEDIUM	配置 Webhook
integ-change-tracking	LOW	查询对象变更

外部参考资料

官方文档

• NetBox 文档
• REST API 指南
• GraphQL API 指南

必备工具

• pynetbox - 官方 Python 客户端
• netbox-graphql-query-optimizer - 查询分析（GraphQL 必备）
• Diode - 数据摄取服务（适用于高容量写入）
• Diode Python SDK - Diode 的 Python 客户端
• NetBox Branching - 变更管理插件（可选）

社区

• NetBox GitHub
• NetBox 讨论区

参考文档

文档	用途
HUMAN.md	面向工程师的易读指南
netbox-integration-guidelines.md	全面的技术参考资料