目錄
目的
本指南將指引您如何透過 Open API 在 Omada Controller 中建立新站點。
環境需求
- Omada Controller(硬體控制器 / 軟體控制器 / 雲端控制器)
- Postman
簡介
Omada API 提供程式化存取 TP-Link Omada SDN Controller 的功能,能與外部系統整合並實現網路管理任務自動化。使用者無需透過 Omada 網頁介面,即可進行身分驗證、查詢網路狀態、管理設備、控制用戶端存取權限及設定各項參數。這有助於簡化自動化工作流程建立,並輕鬆將 Omada 與第三方平台或監控工具串接。
本指南將說明如何運用 Controller 的 Open API 在 Omada Controller 中建立新站點。
設定步驟
在 Controller 上建立 App
注意:Omada Open API 支援兩種模式:Authorization Code(授權碼)模式與 Client Credentials(用戶端憑證)模式。使用者可依需求建立對應的應用程式類型。Authorization Code 模式:適用於第三方平台或使用者需要透過 Controller 進行使用者身分驗證(如 TP-Link ID)登入的情境。Client 模式:適用於無需使用者互動的系統對系統(System-to-System)整合。本指南將以 Client Credentials 模式作為範例說明。
步驟 1. 登入 Controller 管理頁面,切換至 Global 檢視,前往 設定 > 平台整合 > Open API > 新增 App。

步驟 2. 輸入欲建立的 App 名稱,並選擇對應的角色(Role)與站點權限(Site Privilege)。

步驟 3. 點擊右上角的「線上 API 文件」。系統將跳轉至線上文件頁面,您可以在此查看授權流程與詳細的 API 規格說明。

註:若您是透過雲端存取 Local Controller,將不會顯示「線上 API 文件」選項。
完成 Open API 授權驗證
注意:所有 API 呼叫皆需帶入存取權杖(Access Token),作為請求已獲授權的憑證。若無有效的 Token,Controller 將直接拒絕請求。
步驟 1. 點擊眼睛圖示以顯示 Client Secret。建立應用程式後,請妥善記錄 Client ID 與 Client Secret,後續申請 Access Token 時皆需使用。

步驟 2. 點擊檢視圖示以顯示 Omada ID 與介面存取位址(Interface Access Address)。請記錄這些資訊,呼叫 API 時將會用到。

步驟 3. 請參考線上文件首頁的 2.3 節,完成 Client 模式的授權設定;若選擇 Authorization Code 模式,請參考 2.2 節。
請依據文件核對請求方法(Method)、路徑(Path)、查詢參數(Query Parameters)與標頭(Headers)。將 Body 設定為 raw JSON,並嚴格按照文件規範填入欄位。
填入 Request URL 與 Params。

加入 API 所需的 Headers。

依據 API 文件中的參數完成 Body 設定。點擊 Send 發送請求後,即可成功取得 AccessToken。

注意:取得 Access Token 後,後續存取各項 API 介面時皆需帶入此 Token。
建立新站點
步驟 1. 在 Authorization 欄位中,填入前述步驟取得的 Access Token。
注意:Authorization 標頭的前綴格式必須為 AccessToken=

步驟 2. 於 API 文件中找到欲呼叫的建立站點 API。


步驟 3. 依據文件內容填入對應的 URL 與參數。標示為 true 的參數為必填,標示為 false 的參數為選填。設定完成後點擊 Send 發送請求。若建立成功,系統將回傳 errorCode 0 及 siteID。

結果驗證
前往 Global > Dashboard。若站點清單中已顯示新建立的站點,即代表站點已成功建立。
