netbox-custom-objects

NetBox 自定义对象

你对自定义对象的了解可能已经过时。 字段类型、关系选项、分支行为和 API 功能都会随着插件版本更新而变化（0.5 → 0.7 新增了多态字段、可移植架构、分支、GraphQL、配置上下文、coordinates、display_expression）。请优先检索，而非依赖预训练知识。

检索来源

来源	URL / 方法	用途
Custom Objects 文档	https://netboxlabs.com/docs/custom-objects/	概述、工作流、配置上下文、配置模板
字段属性	https://netboxlabs.com/docs/custom-objects/field-attributes/	各类型的属性
REST API	https://netboxlabs.com/docs/custom-objects/rest-api/	端点、负载
GraphQL	https://netboxlabs.com/docs/custom-objects/graphql/	查询字段命名、类型映射
分支	https://netboxlabs.com/docs/custom-objects/branching/	版本门槛、分支行为
可移植架构	https://netboxlabs.com/docs/custom-objects/portable-schema/	导出／预览／应用
发行说明	https://github.com/netboxlabs/netbox-custom-objects/blob/main/docs/releases.md	已安装版本的变更内容
NetBox MCP server	如果已配置 — 列出现有的自定义对象类型和实例	架构发现
NetBox Platform MCP	如果已配置 — 对自定义对象执行完整的 CRUD 操作	创建类型、管理实例

首先：验证连接和版本

# Plugin installed? (404 = not installed; 403 = token lacks custom_objects permissions)
curl -s -H "Authorization: Bearer $NETBOX_TOKEN" "$NETBOX_URL/api/plugins/custom-objects/custom-object-types/" | python -m json.tool

# Which plugin version? (core /api/status/ lists installed plugins and versions)
curl -s -H "Authorization: Bearer $NETBOX_TOKEN" "$NETBOX_URL/api/status/" | python -c "import sys,json; d=json.load(sys.stdin); print(d['netbox-version'], d['plugins'].get('netbox_custom_objects'))"

版本说明： 此技能针对插件 v0.7.x（最新版本为 v0.7.0，2026-09-15），支持 NetBox 4.5.2 到 4.7.x。随插件版本变化的行为会以内联标签标注（v0.5+、v0.6+、v0.6.1+、v0.7+）；需要 NetBox 4.7 的功能会标注为 NetBox 4.7+。请始终先检查已安装的版本 — 分支模型在 0.6.0 中发生了彻底变化。

---

无需编写代码即可扩展 NetBox 数据模型。自定义对象允许管理员通过 UI、REST API、GraphQL（只读）或可移植架构文档定义具有类型化字段、验证规则和关系的新对象类型。

何时使用此技能

• 在 NetBox 中创建新的对象类型（例如，DHCP 范围、合同、应用程序）
• 为自定义对象类型添加字段（文本、数值、对象引用、坐标等）
• 构建通过 REST、GraphQL 或 pynetbox 创建或使用自定义对象的集成
• 在 CI/CD 中自动配置自定义对象类型（可移植架构导出／预览／应用）
• 查询关联对象（从核心对象反向查找自定义对象）
• 在分支、配置上下文或设备配置模板中使用自定义对象

快速参考

核心概念

概念	描述
自定义对象类型（COT）	新的模型定义 — 类似数据库表。包含 name（内部名称）、slug（URL/API 路径）、显示名称和字段。
自定义对象类型字段（COTF）	COT 上的列 — 具有类型、验证规则、排序和分组。
自定义对象	COT 的一个实例 — 类似表中的一行。
主字段	值会成为对象显示名称的 COTF（默认名称为 <Type> <id>）。
显示表达式 (v0.6.1+)	COT 上的 Jinja2 模板（display_expression），用于组合多个字段以生成显示名称；设置后会覆盖主字段。
上下文字段	带有 context: true 的 COTF — 在其他对象引用它的位置以及 REST _context 键中，都会同时显示其值。
组名	在导航侧栏中对相关 COT 进行分组（在 COT 上），或在表单中对字段进行分组（在 COTF 上）。

API 端点

端点	用途
/api/plugins/custom-objects/custom-object-types/	对类型定义执行 CRUD 操作（支持 ?slug= 过滤，v0.5.2+）
/api/plugins/custom-objects/custom-object-type-fields/	对字段定义执行 CRUD 操作
/api/plugins/custom-objects/{slug}/	对实例执行 CRUD 操作（每种类型对应一个端点，以 slug 为键）
/api/plugins/custom-objects/linked-objects/	反向查找：哪些自定义对象引用了指定对象
/api/plugins/custom-objects/schema/preview/	将可移植架构文档与实时数据库进行差异比较（只读）
/api/plugins/custom-objects/schema/apply/	应用可移植架构文档（原子操作；需要 COT 的 add+change 权限）
/graphql/ (v0.6+)	以 custom_objects_<slug> / custom_objects_<slug>_list 的形式读取自定义对象

字段类型（14 种）

类型	描述	特定于类型的选项
text	短文本	validation_regex
longtext	多行文本（文本区域）	validation_regex
integer	整数，64 位（v0.6+）	validation_minimum、validation_maximum
decimal	小数	validation_minimum、validation_maximum
boolean	真/假	—（不支持 unique）
date	ISO 8601 日期（YYYY-MM-DD）	—
datetime	ISO 8601 日期时间	—
url	URL，可附带链接标题 (v0.7+：REST 会公开 <name> 和 <name>_title)	validation_regex
json	任意 JSON	—
select	从选项集单选	choice_set（必需）
multiselect	从选项集多选	choice_set（必需）
object	引用一个对象	app_label+model 或 is_polymorphic+related_object_types_input；related_object_filter、related_name、on_delete_behavior
multiobject	引用多个对象	与 object 相同，但不含 on_delete_behavior；不支持 unique
coordinates (v0.6+)	纬度/经度对；REST 会公开 <name>_latitude 和 <name>_longitude（必须同时提供或同时不提供）	—（不支持 unique，也不支持 default）

发行说明将坐标类型称为“location”；API 的 type 值为 coordinates。

相较于 v0.5.1 的变化

版本	变化
0.5.2	related_name 在多态字段上生效（反向访问器）；COT 列表支持 ?slug= 过滤；POST/PATCH 中的标签现在会持久化；选择字段显示标签而非原始键；可选对象字段接受 null
0.6.0	分支支持：COT、字段和实例均支持分支（受限条件：NetBox ≥ 4.6.2，netbox-branching ≥ 1.0.4）；支持 GraphQL 读取；支持配置上下文（config_context_enabled）；对象/多对象表单字段支持快速添加；联系人；所有权（owner）；64 位整数；coordinates 类型
0.6.1	display_expression；NetBox 4.7+ 配置模板访问（custom_objects.<name>、'<name>' | custom_objects）；批量编辑中的“设为 null”；实例过滤器中的 ?id= 和查找后缀（__gt、__ic 等）已修复；支持 NetBox 4.7
0.7.0	每个被引用对象上新增“Custom Objects”相关选项卡（按权限过滤）；URL 链接标题；架构预览/应用接受并返回 YAML；全局搜索中显示上下文字段

创建自定义对象类型

步骤 1：创建类型

POST /api/plugins/custom-objects/custom-object-types/

{
  "name": "dhcp_scope",
  "slug": "dhcp-scopes",
  "description": "DHCP address scopes",
  "verbose_name": "DHCP Scope",
  "verbose_name_plural": "DHCP Scopes",
  "group_name": "IPAM Extensions",
  "version": "1.0.0",
  "display_expression": "{{ scope_name }}{% if vlan %} (VLAN {{ vlan }}){% endif %}",
  "config_context_enabled": false
}

类型属性：

属性	说明
name	内部名称：^[a-z0-9]+(_[a-z0-9]+)*$ — 小写字母、下划线，且不能以下划线开头或结尾，也不能包含连续下划线。必须唯一。配置模板会使用此名称。
slug	URL 安全标识符。用于 REST 路径、GraphQL 字段名、CUSTOM_VALIDATORS 键和跨 COT 引用。必须唯一。
verbose_name / verbose_name_plural	显示名称。默认分别使用首字母大写的 name / verbose_name + "s"。
group_name	可选。将此类型与其他类型归为一组，显示在侧边栏中。
version	可选的 PEP 440 字符串；供可移植架构功能使用。
display_expression (v0.6.1+)	可选的 Jinja2 模板，使用字段名及其值进行渲染。未定义的字段会渲染为空字符串；渲染出错时会静默回退到主字段。UI 表单会验证 Jinja 语法；REST API 不会。
config_context_enabled (v0.6+)	仅限创建时设置。 为每个实例添加 local_context_data 和 Config Context 标签页。之后无法切换（API 会返回验证错误）。

步骤 2：添加字段

POST /api/plugins/custom-objects/custom-object-type-fields/

{
  "custom_object_type": 1,
  "name": "scope_name",
  "label": "Scope Name",
  "type": "text",
  "required": true,
  "unique": true,
  "primary": true,
  "validation_regex": "^[a-zA-Z0-9_-]+$"
}

关键字段属性：

属性	用途	说明
primary	将此字段的值用作对象的显示名称	每种类型只能有一个；COT 上的 display_expression 会覆盖此设置
context	在对象被引用的任何位置显示此值作为额外上下文	在 REST 中显示为 _context；也会显示在全局搜索中（v0.7+）
required	字段必须有值	创建和更新时均会强制执行（API 和 UI）
unique	所有实例中的值必须唯一	不适用于 boolean、multiobject、coordinates
weight	显示顺序（值越小，位置越靠前）	默认值：100
group_name	表单中的视觉分组	group_name 相同的字段会显示在一起
search_weight	搜索排名（100=高，500=中，1000=低，0=排除）	默认值：500
filter_logic	loose（子字符串）、exact、disabled	默认值：loose；影响类文本字段的 REST 筛选器
ui_visible / ui_editable	always/if-set/hidden 和 yes/no/hidden	隐藏字段仍可通过 API 写入
default	默认值，以 JSON 格式存储	**REST：**直接发送 JSON 值（"default": "active"、"default": 86400、"default": true）。**UI 表单：**输入 JSON 字面量（字符串需要加引号）。不适用于 coordinates。
is_cloneable	克隆对象时是否包含此字段	默认值：false
deprecated、deprecated_since、scheduled_removal	在迁移宽限期内将字段标记为只读	PEP 440 字符串；由可移植架构使用
schema_id	可移植架构使用的稳定只读 ID	自动分配

步骤 3：创建实例

POST /api/plugins/custom-objects/dhcp-scopes/

{
  "scope_name": "office-floor-2",
  "ip_range": 5,
  "vlan": 100,
  "tags": [{"name": "production"}],
  "owner": 3
}

端点路径使用 COT 的 slug（而非 name）。每个实例还包含 id、url、display、owner (v0.6+，NetBox 所有权 — 未使用时可省略)、tags、created、last_updated；如果类型包含上下文字段，还会包含 _context；如果启用了配置上下文，还会包含 local_context_data。

对象引用字段

使用 object 和 multiobject 字段引用 NetBox 核心对象、插件模型或其他自定义对象。

引用核心对象

{
  "custom_object_type": 1,
  "name": "site",
  "label": "Site",
  "type": "object",
  "app_label": "dcim",
  "model": "site",
  "related_name": "dhcp_scopes",
  "on_delete_behavior": "protect"
}

常见的 app_label.model 组合：dcim.device、dcim.site、dcim.rack、dcim.interface、ipam.prefix、ipam.ipaddress、ipam.vlan、ipam.iprange、tenancy.tenant、circuits.circuit、virtualization.virtualmachine。

• on_delete_behavior (v0.5+)：set_null（默认）、cascade 或 protect——删除被引用对象时，自定义对象会发生什么。仅适用于 object 字段；在 multiobject 上会被忽略。
• related_name：目标对象上的反向访问器（例如，在导出／配置模板中使用 site.dhcp_scopes.all()）。多态字段也适用 (v0.5.2+)。对每种目标类型都必须唯一。
• 响应会返回 related_object_type（只读嵌套对象 {id, app_label, model}）；app_label／model 仅可写。

引用其他自定义对象

将 app_label 设为 "custom-objects"，并将 model 设为目标 COT 的 slug：

{
  "custom_object_type": 2,
  "name": "parent_scope",
  "label": "Parent Scope",
  "type": "object",
  "app_label": "custom-objects",
  "model": "dhcp-scopes"
}

允许字段引用自身（COT 指向自身）。不同 COT 之间的循环引用会被检测并拒绝，返回 400——多态字段也包括在内 (v0.5.2+)。

多态引用字段

object／multiobject 字段可以引用多种对象类型 (v0.5+)。设置 is_polymorphic: true，并在 related_object_types_input 中列出允许的类型，而不是使用 app_label／model：

{
  "custom_object_type": 9,
  "name": "linked_resource",
  "label": "Linked Resource",
  "type": "object",
  "is_polymorphic": true,
  "related_object_types_input": [
    {"app_label": "dcim", "model": "device"},
    {"app_label": "custom-objects", "model": "servers"}
  ]
}

实例值应写为字典：{"app_label": "dcim", "model": "device", "object_id": 7}（content_type_id 和 id 也可用作别名，因此读取表示形式可直接往返）。对于多态 multiobject，传入这类字典组成的列表。创建后，is_polymorphic 和允许的类型不可更改——如需修改字段，必须先删除再重新创建。

筛选对象选项

使用 related_object_filter（一个 query_params 字典）缩小 UI 下拉列表中的选项范围：

{"type": "object", "app_label": "dcim", "model": "device", "related_object_filter": {"status": "active"}}

(v0.6+) 对象和 multiobject 表单字段支持 NetBox 快速添加，因此用户可以直接在表单中创建被引用的对象。

关联对象（反向查找）

查找引用给定对象（核心对象或自定义对象）的所有自定义对象：

GET /api/plugins/custom-objects/linked-objects/?object_type=dcim.device&object_id=42

{
  "count": 1,
  "results": [
    {
      "custom_object_type": {"id": 1, "name": "server", "slug": "servers"},
      "field_name": "primary_device",
      "object": {"id": 7, "display": "web-server-01"}
    }
  ]
}

两个参数均为必填项。在 UI 中 (v0.7+)，每个被引用对象都会显示一个 自定义对象选项卡，列出所有类型的相同关联关系，并提供搜索、类型／标签筛选以及数量徽标；结果会根据查看者对各类型的查看权限进行筛选（如果没有任何可查看的内容，该选项卡会隐藏）。max_multiobject_display（插件配置，默认值为 3）限制每行显示的 multiobject 目标数量。

筛选实例

GET /api/plugins/custom-objects/dhcp-scopes/?scope_name=office        # text: substring (filter_logic=loose)
GET /api/plugins/custom-objects/dhcp-scopes/?lease_time__gte=3600       # numeric/date lookups (v0.6.1+)
GET /api/plugins/custom-objects/dhcp-scopes/?site=5&site_id=5          # object fields: either form
GET /api/plugins/custom-objects/dhcp-scopes/?target_dcim_device=7      # polymorphic: <field>_<app>_<model>
GET /api/plugins/custom-objects/dhcp-scopes/?id=1&id=2&tag=production&q=office

• 类文本字段（text、longtext、url、json）默认使用 icontains；设置 filter_logic: "exact" 可启用精确匹配以及 NetBox 的后缀查找（__ic、__isw、__n，等等）。filter_logic: "disabled" 会移除筛选器。
• 标准 NetBox 参数（q、tag、created__gte、limit／offset、ordering）均适用。请参阅 /api/schema/swagger-ui/，了解每种类型生成的筛选器列表。

GraphQL（v0.6+，只读）

query {
  custom_objects_dhcp_scopes_list { id display scope_name site { id name region { name } } }
  custom_objects_dhcp_scopes(id: 42) { id display }
}

• 根字段为 custom_objects_<slug> 和 custom_objects_<slug>_list，slug 中的非标识符字符会替换为 _。不提供仅使用 slug 的名称（dhcp_scopes_list）。
• 关联字段会解析为目标的原生 NetBox GraphQL 类型（可继续遍历）；多态字段为联合类型——请使用 ... on DeviceType { } 片段。
• GraphQL 不公开 coordinates 字段和 URL 标题；请使用 REST。
• 0.7.0 架构中没有变更操作和服务器端字段筛选——请通过 REST 写入和筛选。
• 详情：references/graphql-and-branching.md。

分支

模型在 v0.6.0 发生了变化。提供建议前，请检查已安装的插件版本。

插件	分支上的 COT / 字段更改	分支上的实例写入	分支上的架构应用
v0.6+	支持分支：可跟踪、合并、还原（添加/重命名/删除字段、删除类型）	允许，并像任何 NetBox 对象一样跟踪	允许；DDL 会写入分支架构
v0.4–v0.5	直接写入 main，在分支差异中不可见	拒绝	被阻止

**版本门槛（v0.6+）：**当 netbox_branching 位于 PLUGINS 中时，插件要求 NetBox ≥ 4.6.2 和 netbox-branching ≥ 1.0.4；否则启动会因系统检查 netbox_custom_objects.E001 / E002 而失败。未安装分支插件时，适用常规兼容性矩阵（NetBox 4.5.2–4.7.x）。使用 pip install "netboxlabs-netbox-custom-objects[branching]" 安装，以满足分支插件的最低版本要求。在 NetBox 4.7 上使用 netbox-branching 1.2.x；在 4.4–4.6 上使用 1.1.x（参见 netbox-branching）。

exempt_models 警告：已发布的分支文档页面仍展示 v0.6 之前的 PLUGINS_CONFIG['netbox_branching']['exempt_models'] 代码片段（豁免 customobjecttype / customobjecttypefield），以及“禁止实例写入”的说明。v0.6+ 集成经过测试时未设置任何豁免。在 v0.6+ 上豁免架构模型会使类型/字段更改写入 main，而实例则位于分支中——除非你所用版本的发行说明要求，否则不要沿用该代码片段。请根据正在运行的版本进行确认。

更多信息：references/graphql-and-branching.md。

配置上下文和配置模板

• 配置上下文 （v0.6+）：创建 COT 时设置 config_context_enabled: true。实例会获得 local_context_data（可通过 REST 写入的 JSON）和“配置上下文”选项卡。源 ConfigContext 根据字段命名约定聚合：指向匹配模型的非多态 object 字段，若其名称为 site、tenant、role、platform、location、device_type 或 cluster，就会提供相应维度的数据。没有这些字段的类型只能使用本地数据（不会应用全局上下文）。
• 配置模板 （v0.6.1+，NetBox 4.7+）：在设备/VM 配置模板中，通过 COT 的内部 name（而不是 slug）引用自定义对象：

{% for iface in custom_objects.ospf_interface.filter(device=device) %}
interface {{ iface.name }}
 ip ospf area {{ iface.area }}
{% endfor %}
{# equivalent filter form: #}
{% for peer in 'bgp_peer' | custom_objects %}...{% endfor %}
{# names starting with a digit: #} {% for o in custom_objects['123foo'].all() %}...{% endfor %}

未知名称会记录警告，并渲染为空的、可链式调用的占位对象（无行、无错误）。在 NetBox < 4.7 上，custom_objects 变量不会出现。

可移植架构（v0.5+）

将 COT 定义导出为 YAML/JSON，进行版本管理，并应用到其他实例。POST schema/preview/ 会返回差异（is_new、has_destructive_changes、field_changes[]）；使用 {"allow_destructive": false, "schema": {...}} 调用 POST schema/apply/ 会原子性地应用架构；如果存在未获准的列删除，则返回 409 destructive_changes。两者都接受 Content-Type: application/yaml 或 application/json （YAML v0.7+），并默认返回 JSON，除非 Accept: application/yaml。字段通过稳定的 schema_id 匹配；删除字段需要使用 removed_fields 墓碑记录。完整工作流：references/api-workflow.md。

程序化访问（脚本和插件）

自定义脚本和插件的文档示例：

from netbox_custom_objects.models import CustomObjectType

DHCPScope = CustomObjectType.objects.get(name="dhcp_scope").get_model()
scope = DHCPScope.objects.filter(scope_name="office-floor-2").first()

返回的类行为与标准 Django 模型一致（filter、create、update、delete、annotate）。使用 pynetbox 7.8+ 时，请注册 CustomObjectsExtension，以便 JSON 列能够往返传递，并让每种类型的端点返回类型化记录——示例见 references/api-workflow.md。

继承的 NetBox 功能

每个自定义对象都会自动获得：标签、书签、日志记录、变更日志、联系人 （v0.6+）、所有权 （v0.6+）、列表/详情视图、导入/导出、全局搜索（按字段 search_weight）、事件规则和通知、自定义链接、克隆、指向该类型的 NetBox 自定义字段、REST 筛选/分页/ETag（NetBox 4.6+）以及对象权限。

重要限制

1. 删除具有破坏性：删除 COT 会删除表；删除 COTF 会删除列。无法撤销。
2. 实例 API 不支持批量创建/更新/删除 — POST 数组会失败；请逐个处理对象（或使用 UI 批量导入/编辑）。
3. API 写入时会执行验证 （v0.5+）：required、validation_regex、validation_minimum/maximum，以及以 netbox_custom_objects.<cot-slug> 为键的 CUSTOM_VALIDATORS。
4. 类型上限：默认值为 50（max_custom_object_types；0/None 表示不限制）。
5. 保留字段名（32 个）：id、pk、tags、owner、contacts、local_context_data、created、last_updated、custom_object_type、custom_field_data、bookmarks、journal_entries、model、objects、save、delete、clean、clone、snapshot、… — API 错误会列出所有名称。
6. 无法对 boolean、multiobject 或 coordinates 字段强制执行唯一性。
7. 名称格式：COT 和 COTF 名称必须匹配 ^[a-z0-9]+(_[a-z0-9]+)*$。
8. 创建后不可更改：is_polymorphic + 允许的类型；config_context_enabled；字段类型不能更改为多列类型，也不能从多列类型更改（coordinates、url）。
9. CSV 导入只会填充 URL 值，无法设置 <name>_title 或 coordinates 后备列。
10. 最低 NetBox 版本：v0.5.x–v0.7.x 要求 NetBox 4.5.2+；v0.6.1+ 适用于 4.7.x。分支版本的最低要求提高至 4.6.2 / 1.0.4。

反模式

反模式	为什么会失败	替代做法
对经纬度字段使用 "type": "location"	不是有效类型；该值应为 coordinates（发行说明中使用了“location”一词）	使用 "type": "coordinates"，然后将 <name>_latitude 和 <name>_longitude 一起填写
通过 REST 使用 "default": "\"active\""	default 是 JSON；转义后的形式会存储一个包含引号的字符串	使用 "default": "active"（带引号的字面值应在 UI 表单中输入）
向 /custom-objects/<slug>/ POST JSON 数组	此端点不接受批量数组	对每个对象循环处理；每次应返回 201
认为分支上的实例写入会被拒绝	这只适用于 v0.4–v0.5	在 v0.6+ 中，实例写入会被跟踪到分支中；检查 /api/status/ 中的插件版本
将 exempt_models 代码片段复制到 v0.6+ 安装中	会导致架构（主分支）与实例（分支）分离；v0.6+ 的测试无需此配置即可运行	除非你所用版本的文档另有说明，否则不要将 COT/COTF 设为豁免
GraphQL dhcp_scopes_list / dhcpScopesList	根字段带有前缀，且使用 snake_case	custom_objects_dhcp_scopes_list
发送 GraphQL mutation 或 filters:	0.7.0 架构中不支持	写入使用 REST，服务端筛选使用服务端筛选器
display_expression 引用了标签形式的字段名或拼写错误的字段名	未定义的名称会渲染为空；渲染错误会静默回退到主字段；API 不会进行语法检查	引用字段的 name；使用 {% if field %} 进行保护；在 UI 表单中测试
配置模板 custom_objects.dhcp-scopes	根据内部 name 解析，且连字符不是有效的 Jinja 语法	使用 custom_objects.dhcp_scope（或 custom_objects['123foo']）
PATCH config_context_enabled	仅可在创建时设置	重新创建类型，或保持原样
在 multiobject 字段上使用 on_delete_behavior	会被忽略	仅对 object 字段有意义
将字段命名为 owner、contacts 或 local_context_data	这些名称是保留名称（v0.6+ 新增）	选择其他名称（如 owning_team）
CUSTOM_VALIDATORS['netbox_custom_objects.dhcp_scope']	键是 slug	netbox_custom_objects.dhcp-scopes
使用 "model": "table3model" 引用另一个 COT	这是内部名称，已在 v0.5 中移除	使用 "app_label": "custom-objects", "model": "<target-slug>"
对 slug 为 my_type 的类型使用 pynetbox nb.plugins.custom_objects.my_type	属性访问会将 _ 转换为 -	nb.plugins.custom_objects.endpoint("my_type")
添加字段后依赖 GraphiQL 自动补全	Explorer 会按页面加载缓存架构	点击“重新获取 GraphQL 架构”；服务端已是最新状态

参考资料

按需加载：

• references/field-type-guide.md — 在以下情况下加载：配置字段时，了解各类型的属性、coordinates/url 的多列行为、验证矩阵和选项集。
• references/api-workflow.md — 在以下情况下加载：构建端到端 REST 集成时，了解完整的 DHCP 范围操作流程、筛选、错误表、可移植的架构预览/应用，以及 pynetbox 扩展。
• references/graphql-and-branching.md — 在以下情况下加载：通过 GraphQL 读取数据，或在 netbox-branching 旁运行 Custom Objects 时，了解字段命名、类型映射、联合类型、版本限制、是否支持分支感知，以及配置上下文聚合规则。
• references/modeling-patterns.md — 在以下情况下加载：设计新类型时，了解查找表、桥接、层级结构、显示表达式和配置上下文约定。

相关技能

• netbox-data-modeling — 创建自定义对象前，检查是否已有适用的内置模型
• netbox-api-integration — 身份验证、分页、批量处理模式、pynetbox 基础知识
• netbox-branching — 分支生命周期、版本线（NetBox ≤ 4.6 使用 1.1.x，4.7 使用 1.2.x）
• netbox-plugin-development — 自定义对象无法满足需求时
• netbox-custom-scripts — 在脚本中使用自定义对象

资源

• GitHub 仓库（源代码可用，采用 NetBox Limited Use License）
• 发行说明
• 兼容性矩阵
• pynetbox Custom Objects 扩展