netbox-integration-best-practices

NetBox 統合ベストプラクティス Skill

この Skill は、NetBox の REST API および GraphQL API を使用した統合と自動化を構築するためのベストプラクティス ガイダンスを提供します。

対象読者

• NetBox API 上に統合を構築するエンジニア
• Claude を使用した新しい自動化を計画しているチーム
• NetBox API のベストプラクティスを学ぶ開発者

スコープ: この Skill は API 統合パターンを扱います。プラグイン開発、カスタムスクリプト、NetBox の運用管理は対象外です。

NetBox のバージョン要件

機能	必要なバージョン
REST API	すべてのバージョン
GraphQL API	2.9+
v2 トークン	4.5+ (これを使用してください!)
v1 トークンの非推奨化	4.7+ (これより前に移行してください)

主要なターゲット: NetBox 4.4+、v2 トークン機能には 4.5+。

この Skill を適用すべき場面

次の場合にこれらのプラクティスを適用してください:

• 新しい NetBox API 統合を構築するとき
• 既存の統合コードをレビューするとき
• パフォーマンスの問題をトラブルシューティングするとき
• 自動化アーキテクチャを計画するとき
• NetBox とやり取りするスクリプトを作成するとき

優先度レベル

レベル	説明	対応
CRITICAL	セキュリティ脆弱性、データ損失、深刻なパフォーマンス問題	直ちに修正する必要があります
HIGH	パフォーマンス/信頼性への重大な影響	早急に修正すべきです
MEDIUM	注目すべき改善、ベストプラクティス	対応を計画してください
LOW	軽微な改善、任意	都合のよいときに検討してください

クイックリファレンス

認証

• NetBox 4.5+ では v2 トークンを使用: Bearer nbt_<key>.<token>
• NetBox 4.7 より前に v1 から移行 (非推奨化が計画されています)

REST API

• 常にページネーション: ?limit=100 (最大 1000)
• 部分更新には PUT ではなく PATCH を使用
• リスト操作には ?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 を除外
• 大規模なリストには brief モードを使用
• 独立したリクエストを並列化

データ取り込み (Diode)

• 大量のデータ取り込みには、直接 API ではなく Diode を使用
• 依存関係は ID ではなく名前で指定—Diode が解決または作成します
• 依存関係の順序は不要—Diode がオブジェクト作成順を処理します
• Python では pip install netboxlabs-diode-sdk を使用
• 読み取りには REST/GraphQL API を使用し、書き込み/投入には Diode を使用

ブランチング (プラグイン)

netbox-branching プラグインが必要です。

• ライフサイクル: 作成 → 待機 (PROVISIONING→READY) → 作業 → 同期 → マージ
• コンテキストヘッダー: X-NetBox-Branch: {schema_id} (名前ではなく 8 文字の ID)
• 非同期操作: 同期/マージ/リバートは Job オブジェクトを返します—完了をポーリングしてください
• ドライラン: すべての非同期操作は検証用に {"commit": false} を受け付けます

カテゴリ別のルール

認証ルール

ルール	影響	説明
auth-use-v2-tokens	CRITICAL	NetBox 4.5+ では v2 トークンを使用
auth-provisioning-endpoint	MEDIUM	トークンの自動作成にはプロビジョニングエンドポイントを使用

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	ordering パラメータを使用する
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	リストには brief モードを使用する

データモデリングルール

ルール	影響度	説明
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 Documentation
• REST API Guide
• GraphQL API Guide

必須ツール

• pynetbox - 公式 Python クライアント
• netbox-graphql-query-optimizer - クエリ分析（GraphQL に必須）
• Diode - データ取り込みサービス（大量書き込み向け）
• Diode Python SDK - Diode 用 Python クライアント
• NetBox Branching - 変更管理プラグイン（オプション）

コミュニティ

• NetBox GitHub
• NetBox Discussions

リファレンスドキュメント

ドキュメント	目的
HUMAN.md	エンジニア向けの人間が読めるガイド
netbox-integration-guidelines.md	包括的な技術リファレンス