Как получить доступ к открытому API в контроллере Omada и использовать его
Содержание
Создание учётных данных Open API
Аутентификация запросов Open API
Введение
Omada Open API предоставляет RESTful-интерфейсы, которые позволяют сторонним приложениям программно отслеживать сети и управлять ими через Omada Controller. Поддерживается интеграция с внешними системами и инструментами автоматизации для получения сетевой статистики, управления конфигурациями и настройки параметров управления прошивкой. Эти возможности помогают оптимизировать сетевые операции и повысить эффективность управления в крупномасштабных и многосайтовых развёртываниях.
Omada Open API поддерживает стандартные HTTP-методы, включая GET, POST, PUT, PATCH и DELETE, и возвращает ответы в формате JSON.
Open API уровня организации предоставляет доступ к ресурсам и API в рамках конкретного Omada Controller. Он поддерживает три метода аутентификации: API Key, OAuth 2.0 Client Credentials и Authorization Code, что позволяет охватить сценарии интеграции, такие как запланированные задачи, взаимодействие «сервер-сервер» и приложения, требующие авторизации пользователя.
Требования
- Omada Hardware Controller, Omada Software Controller, Omada Cloud-Based Controller или ER7212PC с версией контроллера 6.4 или выше.
Настройка
Создание учётных данных Open API
Omada Controller поддерживает создание учётных данных Open API как в Global View (глобальном представлении), так и в режиме MSP.
Создание учётных данных в Global View
Шаг 1. Войдите в Omada Controller, откройте Global View и перейдите в Settings > Platform Integration > Open API (Настройки > Интеграция с платформой > Open API).

Шаг 2. Нажмите Add New Credential (Добавить учётные данные) и настройте следующие параметры:
- Name (Имя): введите имя для идентификации учётных данных.
- Description (Описание, необязательно): опишите назначение учётных данных.
- Mode (Режим): выберите метод аутентификации в зависимости от требований приложения:
- API Key:
- Permission (Разрешение): выберите View (Просмотр) для доступа только для чтения или Full Access (Полный доступ) для чтения и изменения конфигураций.
- Site Privileges (Права на сайты): выберите All Sites (including newly created sites) (Все сайты, включая новые) или Sites (Сайты), чтобы определить доступные сайты.
-
- Client:
- Role (Роль): выберите роль для определения прав доступа приложения.
- Site Privileges (Права на сайты): выберите All Sites (including newly created sites) (Все сайты, включая новые) или Sites (Сайты), чтобы определить доступные сайты.
-
- Authorization Code:
- Redirect URL (URL перенаправления, необязательно): укажите URL, на который будет отправлен код авторизации после успешной авторизации пользователя. Если оставить поле пустым, код авторизации можно получить без перенаправления.
Примечание:
- В режиме Authorization Code доступ к API соответствует правам учётной записи пользователя Omada Controller, использованной для авторизации.
- Чтобы использовать Redirect URL, обратитесь в техническую поддержку TP-Link для добавления домена в список доверенных доменов системы Omada.
- Validity Period (Срок действия): задайте дату истечения срока действия учётных данных или выберите Permanent (Бессрочно).
После завершения настройки нажмите Apply (Применить).

Шаг 3. После создания учётных данных во всплывающем окне отображается API Key (режим API Key) либо Client ID и Client Secret (режимы Client и Authorization Code). Скопируйте и надёжно сохраните API Key или Client Secret, поскольку эти значения отображаются только один раз и не могут быть получены позже. Client ID остаётся доступным в сведениях об учётных данных.

Создание учётных данных в MSP View
Если включён режим MSP, учётные данные Open API также можно создать в MSP View для доступа к ресурсам MSP и ресурсам нескольких авторизованных клиентов.
Шаг 1. Войдите в Omada Controller, откройте MSP View и перейдите в Settings > Platform Integration > Open API (Настройки > Интеграция с платформой > Open API).

Шаг 2. Нажмите Add New Credential (Добавить учётные данные). Настройте Name, Description, Mode и Validity Period так же, как описано для Global View. Настройте специфичные для MSP права доступа следующим образом:
API Key:
- Customer Privileges (Права на клиентов): выберите All Customers (including newly created customers) (Все клиенты, включая новых), Customer (Клиент — выберите конкретных клиентов в поле Applicable Customer) или None (Нет), чтобы определить область доступа к клиентам.
Client:
- MSP Role: выберите роль для определения прав на уровне MSP.
- Customer Privileges (Права на клиентов): выберите All Customers (including newly created customers) (Все клиенты, включая новых), Customer (Клиент — выберите конкретных клиентов в поле Applicable Customer) или None (Нет).
- Customer Role (Роль клиента): выберите роль для определения прав авторизованных клиентов.
Authorization Code: конфигурация такая же, как в Global View.
После завершения настройки нажмите Apply (Применить).

Шаг 3. После создания учётных данных скопируйте и надёжно сохраните API Key или Client Secret из всплывающего окна.
Аутентификация запросов Open API
После создания учётных данных Open API используйте соответствующий метод аутентификации для доступа к API Omada Controller. Режим API Key поддерживает прямую аутентификацию, тогда как режимы Client и Authorization Code требуют Access Token.
Примечание. Подробные процедуры аутентификации, конечные точки API и параметры запросов см. в Online API Document (онлайн-документации по API) в правом верхнем углу страницы Open API.

Аутентификация по API Key
Режим API Key не требует Access Token. При вызове интерфейса OpenAPI включите API Key в HTTP-заголовок Authorization в следующем формате:
|
Authorization: Bearer AK-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx |
Аутентификация по Authorization Code
Режим Authorization Code позволяет авторизовать доступ к API с помощью учётной записи пользователя Omada Controller.
Шаг 1. На странице Open API найдите учётные данные типа Authorization Code и нажмите View (Просмотр) в столбце Action (Действие). В окне API Credential Details найдите Client ID, Interface Access Address и Omada ID.


Шаг 2. Вызовите Login API, чтобы получить csrfToken и sessionId.
Следующий пример curl для Linux предполагает, что Redirect URL не настроен, а двухфакторная аутентификация (2FA) для учётной записи пользователя отключена.
|
curl -sSk -X POST '<Interface Access Address>/openapi/authorize/login?client_id=<Client ID>&omadac_id=<Omada ID>' \ -H 'Content-Type: application/json' -d '{"username":"<Username>","password":"<Password>"}' \ | python3 -m json.tool |

Примечание:
- Команда python3 -m json.tool форматирует JSON-ответ для удобства чтения, не изменяя его содержимое.
- Сохраните полученные csrfToken и sessionId для последующих запросов.
- Если для учётной записи включена 2FA или она принудительно применяется контроллером, Login API вернёт код ошибки, связанный с 2FA, вместо csrfToken и sessionId. Дальнейшие инструкции см. в разделе Section 3.2.1.3, 2FA Login документа Organization Level Open API Access Guide.
Шаг 3. Вызовите интерфейс Obtain Authorization Code (Получить код авторизации), используя csrfToken и sessionId, полученные на Шаге 2.
|
curl -sSk -X POST '<Interface Access Address>/openapi/authorize/code?client_id=<Client ID>&omadac_id=<Omada ID>&response_type=code' \ -H 'Content-Type: application/json' -H 'Csrf-Token: <csrfToken>' \ -H 'Cookie: TPOMADA_SESSIONID=<sessionId>' | python3 -m json.tool |

Примечание. Код авторизации действителен в течение 2 минут. Если он истёк, получите новый код авторизации.
Шаг 4. Вызовите интерфейс Obtain Access Token (Получить Access Token), используя Authorization Code, полученный на Шаге 3, Client ID и Client Secret, сохранённый при создании учётных данных.
|
curl -sSk -X POST '<Interface Access Address>/openapi/authorize/token?grant_type=authorization_code&code=<Authorization Code>' \ -H 'Content-Type: application/json' \ -d '{"client_id":"<Client ID>","client_secret":"<Client Secret>"}' | python3 -m json.tool |

Аутентификация по Client Credentials
Режим Client позволяет приложениям получать Access Token напрямую с использованием своих учётных данных API, без участия пользователя.
Шаг 1. На странице Open API найдите учётные данные типа Client и нажмите View в столбце Action, чтобы получить Client ID, Interface Access Address и Omada ID, как показано на Шаге 1 раздела «Аутентификация по Authorization Code».
Шаг 2. Вызовите интерфейс Obtain Access Token, используя Client ID и Client Secret, сохранённый при создании учётных данных.
|
curl -sSk -X POST '<Interface Access Address>/openapi/authorize/token?grant_type=client_credentials' \ -H 'Content-Type: application/json' \ -d '{"omadacId":"<Omada ID>","client_id":"<Client ID>","client_secret":"<Client Secret>"}' | python3 -m json.tool |

Срок действия и обновление токена
В обоих режимах — Client и Authorization Code — Access Token действителен в течение 2 часов, а Refresh Token — в течение 14 дней.
Примечание. Существующие токены становятся недействительными при копировании или импорте сайтов, а также при изменении в контроллере настроек учётных данных, связанных с правами доступа (например, ролей, прав на сайты или прав на клиентов). В таких случаях необходимо пройти аутентификацию заново.
Шаг 1. Вызовите интерфейс Refresh Access Token (Обновить Access Token), используя refreshToken, полученный ранее.
|
curl -sSk -X POST '<Interface Access Address>/openapi/authorize/token?grant_type=refresh_token&refresh_token=<refreshToken>' \ -H 'Content-Type: application/json' \ -d '{"client_id":"<Client ID>","client_secret":"<Client Secret>"}' | python3 -m json.tool |

Шаг 2. После успешного обновления используйте возвращённый Access Token для последующих запросов API, а новый Refresh Token надёжно сохраните для будущих запросов обновления.
Вызов интерфейсов Open API
Следующие примеры демонстрируют использование пяти HTTP-методов — PATCH, GET, PUT, DELETE и POST — через Omada Open API. Выбранные интерфейсы иллюстрируют практические операции с управлением устройствами, мониторингом сети, изменением конфигурации и управлением прошивкой. Примеры PATCH также демонстрируют аутентификацию запросов API с использованием Access Token или API Key.
Изменение информации о канале try-beta (PATCH)
Следующие примеры демонстрируют вызов интерфейса Modify try-beta channel info с использованием Access Token или API Key для аутентификации.
Параметр channel поддерживает три значения: 0 — Stable, 1 — Release Candidate (RC), 2 — Beta.
Пример 1: с использованием Access Token
|
curl -sSk -X PATCH '<Interface Access Address>/openapi/v1/<Omada ID>/upgrade/overview/try-beta/channel' \ -H 'Content-Type: application/json' \ -H 'Authorization: AccessToken=<accessToken>' \ -d '{"channel":0}' | python3 -m json.tool |

Пример 2: с использованием API Key
Примечание. Этот пример выполняет операцию записи, поэтому убедитесь, что для этих учётных данных API Key установлено разрешение Full Access.
|
curl -sSk -X PATCH '<Interface Access Address>/openapi/v1/<Omada ID>/upgrade/overview/try-beta/channel' \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer <API Key>' \ -d '{"channel":1}' | python3 -m json.tool |

После успешного выполнения API возвращает errorCode: 0, что означает успешную обработку запроса.
Получение сводки Wi-Fi (GET)
Вызовите интерфейс Get wifi summary, чтобы получить статистику Wi-Fi для указанного сайта и временного диапазона.
|
curl -sSk -X GET '<Interface Access Address>/openapi/v1/<Omada ID>/sites/<Site ID>/dashboard/wifi-summary?start=<Start Timestamp>&end=<End Timestamp>' \ -H 'Authorization: AccessToken=<accessToken>' | python3 -m json.tool |

Примечание. Site ID можно получить через интерфейс Get Site List. Параметры start и end задают временной диапазон запроса с использованием Unix-временных меток в секундах.
Изменение общих настроек контроля приложений (PUT)
Вызовите интерфейс Modify application control general settings, чтобы обновить настройки контроля приложений.
|
curl -sSk -X PUT '<Interface Access Address>/openapi/v1/<Omada ID>/sites/<Site ID>/application-control/status' \ -H 'Content-Type: application/json' \ -H 'Authorization: AccessToken=<accessToken>' \ -d '{"dpi":true,"loggingTraffic":true}' | python3 -m json.tool |

Удаление привязки IP-MAC (DELETE)
Вызовите интерфейс Delete IP-MAC binding, чтобы удалить существующую запись привязки IP-MAC.
|
curl -sSk -X DELETE '<Interface Access Address>/openapi/v1/<Omada ID>/sites/<Site ID>/ip-mac-binds/<Bind ID>' \ -H 'Authorization: AccessToken=<accessToken>' | python3 -m json.tool |

Примечание. Bind ID можно получить через интерфейс Get IP-MAC binding list.
Запуск онлайн-обновления (POST)
Вызовите интерфейс Start online upgrade, чтобы инициировать онлайн-обновление прошивки указанного устройства.
|
curl -sSk -X POST '<Interface Access Address>/openapi/v1/<Omada ID>/sites/<Site ID>/devices/AA-BB-CC-DD-EE-FF/start-online-upgrade' \ -H 'Authorization: AccessToken=<accessToken>' \ | python3 -m json.tool |

Заключение
Omada Open API позволяет сторонним приложениям интегрировать мониторинг сети, управление конфигурацией и управление прошивкой в автоматизированные рабочие процессы. Выбирая подходящий метод аутентификации — API Key, Client Credentials или Authorization Code — приложения могут безопасно получать доступ к ресурсам контроллера и выполнять поддерживаемые операции через REST API. Это помогает сократить повторяющиеся ручные операции и повысить эффективность управления в крупномасштабных и многосайтовых сетях.
Чтобы узнать больше о каждой функции и конфигурации, посетите Support Home, чтобы загрузить или проверить руководство для вашего продукта.
Вопросы и ответы
В1: Можно ли использовать API Key или Access Token из учётных данных, созданных в MSP View, для вызова API уровня клиента (Global View) и уровня сайта?
О1: Да. Их можно использовать для вызова API уровня MSP, уровня клиента и уровня сайта. Однако для доступа к API уровня клиента и уровня сайта требуются права на доступ к соответствующим клиентам и достаточные права на просмотр или изменение запрашиваемых ресурсов.
В режимах API Key и Client эти права определяются в конфигурации учётных данных. В режиме Authorization Code доступ к API соответствует правам учётной записи пользователя Omada Controller, использованной для авторизации.
В2: В режиме MSP, какие ID следует использовать в путях API-запросов при использовании API Key или Access Token из учётных данных уровня MSP?
О2: Необходимые в пути запроса ID зависят от уровня API, как показано в таблице ниже.
|
Уровень API |
Требуемые параметры пути |
Пример пути запроса |
|
Уровень MSP |
MSP ID |
/openapi/v1/msp/{mspId}/general-setting |
|
Уровень клиента |
Omada ID целевого клиента |
/openapi/v1/{omadacId}/global/controller/setting/network/radius-server |
|
Уровень сайта |
Omada ID целевого клиента и Site ID целевого сайта |
/openapi/v1/{omadacId}/sites/{siteId}/wireless-network/ssids |
MSP ID отображается в сведениях об учётных данных в MSP View. Omada ID целевого клиента отображается в сведениях об учётных данных в Global View этого клиента.

В3: Есть ли у Access Token, Refresh Token и API Key сроки истечения?
О3: В режимах Client и Authorization Code Access Tokens действительны в течение 2 часов, а Refresh Tokens — в течение 14 дней. API Keys — это долгоживущие статические учётные данные без фиксированного срока истечения. Однако для всех трёх режимов аутентификации действует Validity Period (срок действия), заданный при создании учётных данных.
В4: Как двухфакторная аутентификация (2FA) работает с аутентификацией Open API?
О4: В режиме Authorization Code, если для учётной записи пользователя включена 2FA или она принудительно применяется контроллером, Login API возвращает код ошибки, связанный с 2FA, вместо csrfToken и sessionId. Для завершения аутентификации необходимо использовать интерфейс 2FA Login. Подробности см. в разделе 3.2.1.3 «2FA Login» документа Organization Level Open API Access Guide.
В5: В чём разница между использованием API Key и Access Token при вызове интерфейсов Open API?
О5: Оба передаются в HTTP-заголовке Authorization, но используют разные префиксы аутентификации:
- API Key: Authorization: Bearer <API Key>
- Access Token: Authorization: AccessToken=<accessToken>
В6: Сколько учётных данных Open API можно создать в Omada Controller?
О6: В каждом представлении (Global View и MSP View) можно создать до 20 учётных данных. Если лимит достигнут, перед созданием новых необходимо удалить существующие учётные данные.
В7: Где можно найти информацию об обновлениях интерфейсов Open API и совместимости версий?
О7: Online API Document содержит спецификации API, требования к версиям и API ChangeLog, в котором фиксируются добавленные, изменённые, устаревшие и удалённые интерфейсы. Обращайтесь к API ChangeLog, чтобы проверить изменения интерфейсов и совместимость с разными версиями Omada Controller.
В8: Сколько операций API можно включить в пакетный запрос?
О8: Один пакетный запрос может включать до 20 операций API с использованием интерфейсов Batch Processing OpenAPIs или Batch Processing MSP OpenAPIs.
В9: Что происходит при истечении срока действия или удалении учётных данных Open API?
О9: При истечении срока действия учётных данных связанные с ними данные аутентификации (API Key либо Client ID и Client Secret) становятся недействительными. Учётные данные можно повторно активировать, обновив их Validity Period. Удаление учётных данных безвозвратно делает связанные с ними данные аутентификации недействительными.
В10: Есть ли ограничение частоты запросов API для Omada Cloud-Based Controller?
О10: Да. Для каждой организации Omada действует ограничение — 10 API-запросов в секунду. Этот лимит применяется к организации в целом, а не к отдельным учётным данным.