Как получить доступ к открытому API в контроллере Omada и использовать его

База знаний
Руководство по настройке
11-19-2026
574
Данная статья применяется к

Содержание

Введение

Требования

Настройка

Создание учётных данных Open API

Аутентификация запросов 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).

Global View Omada Controller с путём Settings > Platform Integration > 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 (Применить).

Окно Add New Credential в Global View с режимами аутентификации, разрешениями и сроками действия.

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

Всплывающие окна создания учётных данных с Client ID и Client Secret или сгенерированным API Key.

Создание учётных данных в MSP View

Если включён режим MSP, учётные данные Open API также можно создать в MSP View для доступа к ресурсам MSP и ресурсам нескольких авторизованных клиентов.

Шаг 1. Войдите в Omada Controller, откройте MSP View и перейдите в Settings > Platform Integration > Open API (Настройки > Интеграция с платформой > Open API).

MSP View Omada Controller с путём к Open API в разделе Platform Integration.

Шаг 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 (Применить).

Окно Add New Credential в MSP View с правами на клиентов и параметрами учётных данных.

Шаг 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.

Страница Open API Omada Controller с выделенной ссылкой Online API Document в правом верхнем углу.

Аутентификация по 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.

Список учётных данных Open API с выделенным действием View для учётных данных Authorization Code.

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

Терминал Linux с успешным ответом Login API Open API, содержащим csrfToken и sessionId.

Примечание:

  • Команда 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

Терминал Linux с успешным ответом авторизации, содержащим код авторизации.

Примечание. Код авторизации действителен в течение 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

Терминал Linux с Access Token и Refresh Token, полученными через аутентификацию по Authorization Code.

Аутентификация по 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

Терминал Linux с успешным ответом Client Credentials, содержащим accessToken и refreshToken.

Срок действия и обновление токена

В обоих режимах — 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

Терминал Linux с успешным обновлением токена: новые accessToken, refreshToken и expiresIn.

Шаг 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

Терминал Linux с успешной настройкой канала обнаружения прошивки с использованием Access Token.

Пример 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

Терминал Linux с успешной настройкой канала обнаружения прошивки с использованием API Key.

После успешного выполнения 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

Терминал Linux со статистикой Wi-Fi, полученной через OpenAPI.

Примечание. 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

Терминал Linux с успешным PUT-запросом для настройки DPI и журналирования трафика.

Удаление привязки 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

Терминал Linux с успешным DELETE-запросом для удаления привязки IP-MAC.

Примечание. 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

Терминал Linux с успешным POST-запросом для запуска онлайн-обновления прошивки устройства.

Заключение

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 этого клиента.

API Credential Details в MSP View и Global View клиента с выделенными полями MSP ID и Omada ID соответственно.

В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-запросов в секунду. Этот лимит применяется к организации в целом, а не к отдельным учётным данным.

Пожалуйста, оцените этот документ

Сопутствующие документы