第6章 · 自動化とAI·v1.0.0·更新 2026/7/20·読了目安 約19分
変更要約: 初版
6.3コントローラAPIとREST応答の解釈
この節の要点
Catalyst CenterのIntent APIとSD-WAN Manager（vManage）のREST APIを、トークン取得から実際の呼び出しまでの流れとして押さえ、返ってきた応答コード——200/201/204・400/401/403/404/429・5xx——とペイロードから、次に何をすべきか（再試行するか・資格情報を直すか・URLを直すか・待つか）を判断できるようにします。
コントローラAPIの自動化で最も時間を溶かすのは、返ってきたコードの意味を取り違えて、見当違いの場所を直そうとすることです。401が返っているのにURLを何度も書き換えたり、429が返っているのに即座に再試行してさらに詰まらせたり——いずれもコードが指している「責任の所在」を読めていないことが原因です。応答コードは大きく、2xx＝成功／4xx＝呼び出し側（クライアント）の問題／5xx＝サーバ側の問題という責任の切り分けを示します。この節ではCatalyst CenterとSD-WAN Managerという実際のコントローラを題材に、認証トークンの取得→呼び出し→応答の解釈→次の一手という一連の流れを追います。
6.3.1コントローラAPIの呼び出しの型
- Catalyst Center（旧DNA Center）は企業アクセス網を統制するオンプレのコントローラで、Intent APIを公開する。呼び出しはまず
POST /dna/system/api/v1/auth/tokenにBasic認証で資格情報を送ってトークンを取得し、以後は取得したトークンをX-Auth-Tokenヘッダに載せて/dna/intent/api/v1/network-deviceのような意図ベースのエンドポイントを呼ぶ。トークンには有効期限があり、期限切れ後の呼び出しは401になる。 - SD-WAN Manager（vManage）はWANオーバーレイの管理コントローラで、デバイス在庫・テンプレート・ポリシー・統計をRESTで扱う。認証後に
/dataservice/deviceのようなエンドポイントを呼び、セッション（およびCSRF用トークン）を維持して操作する。どちらのコントローラでも「認証は別リクエストで、以降の呼び出しはヘッダで資格を提示する」型は共通である。 - HTTPメソッドは操作の種類を表す：
GET＝取得（安全・状態を変えない）／POST＝作成（新しいリソースやジョブを起こす）／PUT＝置換（送らなかった項目は消えうる）／PATCH＝部分更新／DELETE＝削除。コントローラではPOSTが即座に完了せず「タスクID」を返す非同期処理になることがあり、その場合はタスク照会のエンドポイントをGETして完了を確認する必要がある。