netbox-ndx

NetBox Data Exchange（NDX）

NDX（NetBox Data Exchange） 是一个经过筛选并持续更新的基础设施组件元数据目录，涵盖数百家制造商的数万种设备类型。它将原本需要花数小时查找的厂商 PDF 和停产公告，整合成可搜索的参考数据集。

开放目录、商业化增强数据 + 产品内功能。 设备／模块／机架类型定义目录面向所有人开放——任何人（包括社区用户）都可以浏览公开目录，并手动下载 YAML 类型定义（格式与社区设备类型库相同）。属于商业内容的是：（a）增强数据——生命周期／热学／运行／平台／可观测性元数据；（b）NetBox Cloud／NetBox Enterprise 内置的 NDX 功能，可在产品内浏览、导入、同步并附加增强数据。介绍 NDX 时，请明确区分这两者。

NDX 是一项功能，不是插件。 请将产品内的功能称为“NDX 功能”。其插件实现属于内部细节——重点介绍它提供的能力，以及如何通过 API 使用。

你对 NDX 的了解可能已经过时。 目录覆盖范围、增强字段和套餐行为都在持续变化。数据经过 AI 辅助筛选整理，并包含来源信息和置信度——优先检索数据，而不是依赖预训练知识；展示数值时，务必注明来源。

NDX 提供的内容——两个数据层

层	内容	访问权限	在 NetBox 中的存放位置
设备类型定义	设备／模块／机架类型的物理拓扑：接口、电源端口、控制台端口、插槽、机架单位、重量。格式与社区设备类型库（DTL）相同，完整收录并注明出处，此外还有数千项由 NetBox Labs 筛选整理的定义。	开放 — 任何人（包括社区用户）均可浏览并手动下载 YAML	带有组件模板的标准 NetBox DeviceType／ModuleType／RackType 对象
增强数据	DTL 从未包含的新元数据：生命周期日期、热学、环境限制、运行功耗／噪声、平台／NOS，以及可观测性协议元数据（SNMP／gNMI／NETCONF／Redfish／Modbus 等），每个值均附带来源信息和置信度评分。这是商业增值内容。	商业内容 — 通过付费套餐中的产品内 NDX 功能提供这些值	附加到每个已导入类型的增强记录

NDX 不是什么

• 不是监控／不是遥测。 不提供实时状态。
• 不是 CMDB／不是实例数据。 NDX 描述的是设备类型（“一台 Cisco Nexus 93180YC-FX3”），而不是你实际运行的某一台设备。
• 不是自动配置。 可观测性元数据会告诉你监控什么以及如何监控（OID、路径）；它不会配置工具。
• 不保证完整。 覆盖范围各不相同；许多字段为空。来源信息和置信度会明确展示这一点。

检索来源

来源	URL／方法	用途
NDX 功能文档	https://netboxlabs.com/docs/ndx/	功能参考、导入／同步、套餐
NDX 公开目录	https://netboxlabs.com/ndx	浏览／搜索目录；下载 YAML（增强数据值受访问权限限制）
NetBox DCIM 模型	https://netboxlabs.com/docs/netbox/models/dcim/	DeviceType／ModuleType／RackType 结构
社区 DTL	https://github.com/netbox-community/devicetype-library	NDX 收录的开源 DTL（Apache-2.0）
NetBox MCP／Platform MCP	如果已配置 — 列出／检查 /api/plugins/ndx/ 端点	核实实时端点和增强字段

首先：验证功能是否可用

curl -s -H "Authorization: Bearer $NETBOX_TOKEN" \
  "$NETBOX_URL/api/plugins/ndx/import-records/?limit=1" | python -m json.tool

分页响应表示产品内 NDX 功能可用。404 = 此实例未启用该功能（仍可在公共目录中浏览目录并以 YAML 格式下载，但尚未接入此 NetBox）。产品内功能随 NetBox Cloud（所有套餐）和 NetBox Enterprise 提供；免费套餐可查看目录、导入和增强数据可用性标志，付费套餐可查看完整的增强数据值（见下文的套餐）。

---

范围

此技能介绍如何通过 NetBox REST API 使用 NDX 数据（/api/plugins/ndx/）——任何持有 NetBox 令牌的 Agent 都能访问此接口——以及如何理解增强数据模型。此技能不涵盖：

• 设计自己的数据模型 → 使用 netbox-data-modeling
• 批量迁移库存 → 使用 netbox-migration
• 核心 REST 模式／身份验证 → 使用 netbox-api-integration

定位：NDX 用于读取和使用。 权威目录由 NetBox Labs 集中维护；你的实例会将其拉取进来。Agent 查找并使用增强数据和生命周期数据；导入是次要操作。你不会编写增强数据值。

REST API 接口

基础前缀 /api/plugins/ndx/。使用标准 NetBox 令牌身份验证和 DRF 分页（count/next/previous/results、?limit=/?offset=）。

端点	方法	用途
import-records/	GET (, PATCH)	主要查找表——将每种导入类型映射到其 NetBox 对象，并内嵌增强数据
import-records/{id}/	GET, PATCH	单条导入记录
enrichments/	GET (, PATCH)	直接获取增强数据记录（按 has_* 标志筛选）
enrichments/{id}/	GET, PATCH	单条增强数据记录
import/	POST	将一个或多个目录条目导入 NetBox
sync/	POST	将后台更新检查加入队列（设置 update_available 标志；不会应用更新）

将 import-records 和 enrichments 视为只读端点——记录由导入流水线填充，而非手动编写。

GET import-records/ — 入口

每条记录都将 NDX 目录标识关联到本地 NetBox 类型，并嵌套完整的增强数据：

• ndx_id — 稳定标识符，格式为 vendor_slug/slug（例如 cisco/nexus-93180yc-fx3）
• ndx_manufacturer、ndx_model、ndx_vendor_slug
• ndx_source — community、netbox_labs 或 both
• ndx_version — 上次同步时的数据版本
• first_imported、last_synced、update_available（布尔值）
• enrichment — 完整增强数据对象（或 null），嵌套且只读

筛选条件：ndx_vendor_slug、ndx_source、update_available。搜索：通过 ?q= 按制造商／型号／ndx_id 搜索。

GET /api/plugins/ndx/import-records/?q=Nexus 93180YC-FX3
GET /api/plugins/ndx/import-records/?ndx_vendor_slug=cisco&update_available=true

GET enrichments/ — 按数据是否存在进行查询

返回增强数据记录，包含所有类别字段、六个 has_* 标志、extensions_data 和嵌套的 provenance_entries。按可用性标志筛选：

GET /api/plugins/ndx/enrichments/?has_lifecycle=true

增强数据对象不包含制造商／型号信息——如需获取可供人阅读的标识信息，请通过 import-records/ 查询。

POST import/ 和 POST sync/

POST /api/plugins/ndx/import/  {"ndx_ids": ["arista/dcs-7050sx3-48yc8", "cisco/nexus-93180yc-fx3"]}

≤5 个 ID 会同步导入，并逐个返回 {success, message, created, updated}；>5 个 ID 会将后台任务加入队列（202）。导入后，该类型将成为常规的 NetBox DeviceType/ModuleType/RackType，并包含组件模板，以及（在付费套餐中）增强数据。导入需要与直接创建对象相同的 add 权限（dcim.add_devicetype / add_moduletype / add_racktype）。（插件 0.8.1+） 导入设备类型时，还会根据 DTL 的 inventory-items 列表创建 InventoryItemTemplate（仅限设备类型），并根据 DTL 的 port-mappings 列表中的位置将前端口关联到后端口。

POST /api/plugins/ndx/sync/   {}     # 202; flags update_available, does not apply changes

丰富数据

这是该功能的核心。每种设备／模块／机架类型都可以有一条丰富数据记录。完整字段目录见 references/enrichment-fields.md——读取特定属性时请加载该文件。

类别（每类都有一个 has_* 可用性标志）：生命周期、热能、环境、运维、平台、snmp。少数高价值字段已提升为顶层列；丰富的协议详情存储在按协议（platform、snmp、redfish、gnmi、netconf、ipmi、bacnet、modbus、cellular）为键的 extensions_data JSON 块中。

// shape of an enrichment (abbreviated)
{
  "eos_date": "2027-04", "eol_announced": "2024-10-31", "last_support_date": "2030-04-30",
  "tdp_watts": 715, "max_power_draw_watts": 1100, "max_operating_temp_c": 40.0,
  "nos": "NX-OS", "snmp_sys_object_id": "1.3.6.1.4.1.9.12.3.1.3.1234",
  "has_lifecycle": true, "has_thermal": true, "has_snmp": true,
  "extensions_data": {"snmp": {"versions": ["v2c","v3"], "mibs": [...]},
                       "gnmi": {"default_port": 6030, "encoding": ["json_ietf"]}},
  "provenance_entries": [
    {"field": "lifecycle.eos_date", "source": "https://...", "provenance_type": "vendor_eol_bulletin",
     "confidence": "high", "retrieved": "2026-01-15"}
  ]
}

正确使用丰富数据的规则

1. 先检查 has_* 标志。 标志为 True 但值为空，表示数据存在于目录中，但受套餐等级限制（免费与付费）——应报告为“付费套餐可用”，而不是“缺失”。
2. 对所有内容进行空值检查。 覆盖并不完整；即使某个已覆盖类别的标志为 true，许多字段仍可能为 null。
3. 生命周期日期为字符串，格式为 YYYY-MM 或 YYYY-MM-DD。请谨慎解析。
4. 始终提供来源和置信度。 每个非空值都有一个 provenance_entries[] 条目（source URL、provenance_type、从 high 到 unverified 的 confidence）。对 low／unverified 的值应谨慎处理。
5. 深层协议数据位于 extensions_data 中，而不在顶层列中。只有 sysObjectID、OID 前缀和 NOS 会提升为顶层字段。

NDX 生命周期与核心 end_of_life（NetBox 4.7+）

NetBox 4.7 为 DeviceType 和 ModuleType 添加了一个可选的 end_of_life 日期（“制造商不再支持此设备类型的日期”），以及 cooling_method（air／liquid／hybrid／immersion）。这两层相辅相成，并非重复：

	核心 end_of_life (4.7)	NDX 生命周期丰富数据
形式	一个 YYYY-MM-DD 日期，无来源	六个日期（ga_date、eol_announced、eos_date、eosw_date、eosec_date、last_support_date），格式为 YYYY-MM 或 YYYY-MM-DD
来源	无——由用户维护	provenance_entries[]，包含来源 URL 和置信度
适用范围	核心筛选器、表格、导出、任何插件，以及任何 NetBox 4.7+ 版本	Cloud／Enterprise 上的 /api/plugins/ndx/，付费套餐可查看值

NDX 会为你填充核心 end_of_life（NDX 插件 0.7.0+、2026-09-19、NetBox 4.7+）。 导入和重新导入时，NDX 会根据丰富数据中的 last_support_date（语义上与“制造商不再支持”相匹配）写入 DeviceType／ModuleType.end_of_life，绝不会使用 eos_date（停售）或 eol_announced。Agent 必须了解以下规则：

• 由插件设置 populate_core_end_of_life 控制（默认开启）；关闭后，生命周期数据仅保留在丰富数据记录中。
• 只会写入严格符合 YYYY-MM-DD 格式的值。部分格式的 YYYY-MM last_support_date 会被跳过（记录日志，字段保持不变）——宁可没有日期，也不使用猜测的日期。
• 本地编辑优先：只有核心字段为空，或仍等于 NDX 上次写入的值时，才会写入。用户更改过的日期在重新导入时会保留。
• 不会填充 cooling_method。NDX 热能数据中的 cooling_type（air／liquid／mixed／passive）仍保留在丰富数据记录中。

因此，在 4.7+ 且使用当前 NDX 插件时，应将核心 end_of_life 视为由 NDX 维护，不要手动覆盖。只有在设置关闭、类型在插件 0.7.0 之前导入且尚未重新同步，或 NDX 日期为部分格式且用户接受扩展日期时，才自行填写：

手动设置的 end_of_life 若与 NDX 上次写入的值不同，重新导入时会保留。如果将 NDX 的 cooling_type 复制到核心 cooling_method，请将 mixed 映射为 hybrid，并将 passive 留空（核心中没有对应值）——NDX 不会代你完成此操作。

常见工作流

完整流程见 references/consume-workflows.md。以下是高价值流程：

• 查询已知类型的增强数据： GET import-records/?q=<model> → 读取嵌套的 enrichment（无需再次调用）→ 读取 eos_date、max_power_draw_watts、extensions_data.gnmi.default_port 等。
• EOL/EOS 暴露报告： 从 GET /api/dcim/devices/ 获取已部署设备，收集其 device_type ID，将每个 ID 与其 NDX 导入记录匹配，标记已过或接近 eos_date/last_support_date 的类型，并注明数据出处。(4.7) 也要读取核心 DeviceType.end_of_life 并与之核对（见上文）。
• 填充可观测性配置： 读取 snmp_sys_object_id、extensions_data.snmp.mibs[] 或 extensions_data.gnmi/.netconf/.redfish，以确定要轮询哪些内容（NDX 提供轮询什么/如何轮询，而非配置本身）。
• 导入目录条目： 使用 ndx_id（或多个 ndx_id）调用 POST import/。

访问层级（概念层面）

• 向所有人开放： 设备/模块/机架的类型定义——可浏览公开目录并手动下载 YAML，无需 NetBox Cloud/Enterprise。这与社区 DTL 的形式相同。
• 免费（所有 NetBox Cloud 套餐 + NetBox Enterprise）：产品内的 NDX 功能——完整设备类型目录 + 导入 + 增强数据可用性标记（has_*），但增强数据的值受访问层级限制。
• 付费： 完整的增强数据值。

因此，has_lifecycle: true 但生命周期字段为空，表示访问层级限制，而非没有数据。

反模式

1. 将 NDX 称为“插件”，或展示安装/PLUGINS_CONFIG 机制。它是一项功能。
2. 错误描述开放内容与商业内容的界限。 类型定义（YAML）向所有人开放，任何人都可以手动下载；增强数据值和产品内 NDX 功能（Cloud/Enterprise）则属于商业内容。不要把整个目录都说成商业内容，也不要暗示增强数据值是免费的。
3. 调用上游目录 API。 Agent 只调用其自身 NetBox 上的 /api/plugins/ndx/...。不要针对任何外部 NDX 目录/CDN 端点生成代码。
4. 将 has_* 标记解读为“数据已存在”。 值为 true 但内容为空 = 数据存在，但受访问层级限制。应据实说明。
5. 假定数据完整。 检查空值；覆盖范围因供应商/设备年代而异。
6. 忽略数据出处/置信度。 始终提供 source + confidence；这些数据经过 AI 辅助整理。
7. 将生命周期日期视为完整日期。 它们可能采用 YYYY-MM 格式。
8. 在增强数据对象中查找制造商/型号。 这些信息位于导入记录中；请通过 import-records/ 获取。
9. 期望协议深层数据以列形式呈现。 这些数据位于按协议分类的 extensions_data 中。
10. 期望 sync/ 更新数据。 同步只会标记更新；应用更新需要重新导入。
11. 将 NDX 当作实例/监控数据。 它只包含设备类型参考元数据。
12. 创建以供应商 PID 为键的第二个设备类型。 NDX 将市场名称存储在 model 中，将 PID 存储在 part_number 中；以 PID 作为 model 创建的类型（Discovery/Diode 修复前曾如此操作）是重复项，会导致 NDX 增强数据失去关联。创建类型前先按 part_number 匹配。

版本说明

NDX 插件 0.8.x（2026-10）

当前插件版本为 0.8.3（2026-10-15）；声明支持 NetBox 4.5.0+（清单为 4.5–4.7）。populate_core_end_of_life 默认值未变。

• 0.8.0 — 现在，NDX 来源信息变更会在 GET /api/core/object-changes/ 中呈现为 {id, field, source, provenance_type, confidence, retrieved, note}。在 0.8.0 之前，任何包含来源信息变更的变更日志页面都会返回 500。
• 0.8.1 — 设备类型导入会根据 DTL 的 inventory-items 列表创建 InventoryItemTemplate（仅设备类型；模块类型没有库存项目模板）。前置端口与后置端口的映射从 DTL 的 port-mappings 列表读取，包括 front_port_position，因此在 NetBox 4.5+ 上，多位置前置端口也能正确映射。
• 0.8.2 / 0.8.3 — 仅更新插件清单和文档；目录的 Type 筛选器文档现已注明类型为 Device / Module / Rack Types，且导入会根据类型强制要求相应的 add 权限。

NetBox 4.7（2026-09-02）

• DeviceType/ModuleType 新增核心字段 end_of_life（日期）和 cooling_method；Rack/RackType 新增 cooling_capability/cooling_capacity；并新增完整的冷却模型（来源、供给、进气、出气）。NDX 增强数据仍保留带来源信息、多日期的生命周期和热管理记录；NDX 插件 0.7.0+ 在导入时会根据 last_support_date 写入核心字段 end_of_life（通过 populate_core_end_of_life 设置，默认启用；仅接受严格日期；保留本地编辑），且不会写入 cooling_method。NDX 插件 0.7.1+ 声明兼容 NetBox 4.5–4.7（当前版本为 0.8.3）。
• 在 4.7 上，GET /api/dcim/devices/ 会加载 config_context，除非请求中不包含该字段（?exclude=config_context 在所有 4.7.x 版本中都会被忽略；4.7.3+ 上，?fields=/?omit= 会再次跳过数据库操作）——获取暴露报告时，请保留 ?fields=id,name,device_type。
• 选择类型的自定义字段读取结果为 {"value", "label"}——仅当你在 4.5–4.6 实例的自定义字段中存储了 NDX 派生值并进行比较时，才需要注意这一点。

参考资料

• references/enrichment-fields.md — 按类别列出的所有增强字段、extensions_data 协议块和来源信息结构。读取特定属性时请加载。
• references/consume-workflows.md — 查询、EOL 暴露情况、可观测性和导入的完整 API 调用序列。