omada-controller

Omada SDN コントローラー API

Open API（OpenAPI 3.0.1）を使用して、TP-Link Omada SDN コントローラーを管理します。

互換性

Open API は Omada SDN Controller v5.9 以降（Software Controller と Cloud-Based Controller の両方）で利用できます。それ以前のバージョンには、Cookie ベースのセッション認証を使用する、ドキュメント化されていない内部 API しかありません。このスキルでは、そのレガシー API は対象外です。

Open API 機能は、使用前に管理者が明示的に有効にする必要があります。

環境のセットアップ

API 呼び出しを行う前に、3 つの環境変数が必要です。ユーザーがこれらを指定しておらず、.env ファイルも存在しない場合は、セットアップを案内してください。

1. コントローラーの URL を確認する — Omada Controller のアドレスをユーザーに尋ねます。Software Controller の場合、通常は https://<host>:8043 です。インストール時に変更されている場合、ポートが異なることがあります。

2. API 認証情報を作成する — ユーザーを次の手順に沿って案内します。

   • Omada Controller の Web UI にログインする
   • Global View > Settings > Platform Integration > Open API に移動する
   • Add New App をクリックする
   • タイプを Client（Gateway ではなく）に設定する
   • 生成された Client ID と Client Secret をコピーする

3. .env ファイルを作成する — プロジェクトのルートに .env ファイルを作成するようユーザーに案内します。

   OMADA_URL=https://omada.example.com:8043
   OMADA_CLIENT=your-client-id
   OMADA_SECRET=your-client-secret
   

.env を git にコミットしないでください。 .gitignore に含まれていることを確認してください。

リクエストを行う前に変数を読み込みます。

export $(grep -v '^#' .env | xargs)

source .env は使用しないでください。変数はサブシェルや curl に引き継がれません。

認証に失敗する場合、よくある原因は次のとおりです。

• コントローラーで Open API 機能が有効になっていない
• クライアントアプリのタイプが Client ではなく Gateway に設定されている
• コントローラーの URL が間違っている、またはポートが指定されていない
• UI でクライアントシークレットを再生成した後、.env を更新していない

ラッパースクリプトの場所

API ラッパースクリプトは、このスキルのディレクトリからの相対パス scripts/omada-api.sh にあります。セッションで初めて使用するときは、Glob を使って **/omada-controller/scripts/omada-api.sh を検索し、スクリプトのパスを確認してください。以降のすべての呼び出しには、見つかった絶対パスを使用します。たとえば、スキルが .claude/skills/omada-controller/ にインストールされている場合、スクリプトのパスは .claude/skills/omada-controller/scripts/omada-api.sh です。

API 呼び出し

すべての Omada API 呼び出しには、必ずラッパースクリプトを使用してください。環境変数の読み込み、認証、URL の構築が自動的に処理されます。

アンチパターン： bash <script> ... 以外のコマンドを使うと、追加の権限確認が表示されます。スクリプトの出力を、他のコマンドにパイプしたり、コマンドを連結したり、後処理したりしないでください。フィルタリングには --jq FILTER を使用し、それ以外は JSON 出力を自分で読み取ってください。curl、変数のプレフィックス指定、シェル変数は絶対に使用しないでください。よくあるアンチパターンは次のとおりです。

• bash <script> ... | jq ... — 代わりに --jq FILTER フラグを使用する
• bash <script> ... | python3 -c "..." — --jq を使うか、出力を自分で読み取る
• cat saved-response.txt | python3 -c "..." — JSON を自分で読み取り、シェルから別のコマンドを実行しない
• curl -sk "${OMADA_URL}/api/info" — curl ではなくスクリプトを使用する
• SITE="123" && bash <script> ... — 値をパスに直接記述する
• SITE="123"; for mac in ... — シェル変数やループは使用しない

セッションで初めて使用するときは、引数なしでヘルスチェックを実行します。これにより接続を確認し、以降のすべての呼び出しでスクリプトを使用できるよう、ユーザーが一度だけ許可できます。

bash <script>

続いて、API 呼び出しを行います。

bash <script> <METHOD> <PATH> [JSON_BODY] [--raw] [--jq FILTER]

パスは /openapi/v1/{omadacId} からの相対パスです。完全な URL の構築やトークンの管理は不要です。

例

# List sites
bash <script> GET "/sites?page=1&pageSize=100"

# List devices at a site
bash <script> GET "/sites/{siteId}/devices?page=1&pageSize=100"

# Reboot a device
bash <script> POST /sites/{siteId}/cmd/devices/reboot '{"deviceMacs":["AA-BB-CC-DD-EE-FF"]}'

# v2 endpoints — prefix path with /v2
bash <script> GET /v2/sites/{siteId}/setting/firewall/rules

# Fetch the OpenAPI spec for endpoint discovery
bash <script> GET /v3/api-docs --raw

# Filter API paths by keyword (use --jq, NEVER pipe)
bash <script> GET /v3/api-docs --raw --jq '[.paths | keys[] | select(test("port"; "i"))]'

# Extract just the data array from a paginated response
bash <script> GET "/sites/{siteId}/clients?page=1&pageSize=100" --jq '.result.data'

パスのルーティング

スクリプトがパスを自動的にルーティングします。

• /sites/... → /openapi/v1/{omadacId}/sites/...
• /v2/sites/... → /openapi/v2/{omadacId}/sites/...
• /v3/api-docs → {OMADA_URL}/v3/api-docs（認証プレフィックスなし）

推奨される権限設定

繰り返し確認を表示せずにスクリプトを実行できるよう、ユーザーは Claude Code の設定に次の内容を追加してください。

Bash(bash *omada-api.sh *)

API の検出

コントローラーは、独自の完全な OpenAPI 3.0.1 仕様（約 1,507 個のエンドポイント）をホストしています。パスをハードコードするのではなく、実行時に任意のエンドポイントを検出するために使用してください。

• Swagger UI（ブラウザー）：{OMADA_URL}/swagger-ui/index.html — 認証は不要です
• OpenAPI 仕様（JSON）：

  bash <script> GET /v3/api-docs --raw --jq '.paths | keys[]'
  

一般的なパターン

Site ID

ほとんどのエンドポイントはサイト単位です。まずサイト ID を取得してください。

bash <script> GET "/sites?page=1&pageSize=100"

以降のパスで使用します：/sites/{siteId}/devices、/sites/{siteId}/clients など。

ページネーション

ページネーションに対応したエンドポイントは、クエリパラメーター page と pageSize を受け付け、次の形式で返します。

{
  "errorCode": 0,
  "result": {
    "totalRows": 7,
    "currentPage": 1,
    "currentSize": 100,
    "data": [...]
  }
}

API バージョン

一部のエンドポイントでは、デフォルトの /v1/ ではなく /v2/ を使用します。swagger 仕様には両方が含まれています。必要に応じて、パスの先頭に /v2 を付けてください。

認証の詳細

ラッパースクリプトが認証を自動的に処理しますが、参考までに記載します。

1. コントローラー ID：GET {OMADA_URL}/api/info から取得します（OpenAPI 仕様の対象外です）
2. トークン：POST {OMADA_URL}/openapi/authorize/token?grant_type=client_credentials に omadacId、client_id、client_secret を含む JSON ボディを指定して、OAuth2 クライアント認証情報を使って取得します（grant_type はボディではなくクエリパラメーターです）
3. ヘッダー形式：Authorization: AccessToken=<token>（Bearer ではありません）
4. 有効期限：トークンの有効期限は 2 時間（7200 秒）です。スクリプトは呼び出しごとに再認証します

注意事項

• 引用符：& を含むパスは必ず引用符で囲んでください（例："/sites?page=1&pageSize=100"）。引用符で囲まれていない & は、シェルでバックグラウンド実行を指定する演算子です。
• TLS：コントローラーは通常、自己署名証明書を使用します。必ず curl -k を使用してください。
• MAC 形式：API では AA-BB-CC-DD-EE-FF（大文字、ハイフン区切り）を使用します。
• エラー処理：レスポンスの errorCode を必ず確認してください。0 は成功、負の値はエラーです。
• トークンヘッダー：Authorization: AccessToken=<token> を使用します。Bearer <token> ではありません。

参考資料

• scripts/omada-api.sh — API ラッパー（環境変数、認証、リクエストを処理します）
• references/api-categories.md — API エンドポイントのカテゴリと件数
• references/external-resources.md — ドキュメント、サンプル、インテグレーションへのリンク