UniFi API client
1.1.101
Класс PHP, который обеспечивает доступ к API сетевых приложений Ubiquiti UniFi .
Этот класс используется нашим инструментом API-браузера, который можно найти здесь.
Пакет можно установить вручную или с помощью композитора/пакетщика для удобного включения в ваши проекты. Более подробную информацию смотрите в инструкциях по установке ниже.
| Программное обеспечение | Версии |
|---|---|
| Сетевое приложение/контроллер UniFi | 5.XX, 6.XX, 7.XX, 8.XX ( 8.5.6 подтверждено ) |
| UniFi ОС | 3.X, 4.X ( 4.1.15 подтверждено ) |
сервер с:
PHP 7.4.0 или выше (используйте версию 1.1.83 для PHP 7.3.x и ниже)
Модули PHP json и PHP cURL
протестировано на Apache 2.4 с PHP 7.4.27 и cURL 7.60.0 и с PHP 8.3.11 и cURL 7.81.0
прямое сетевое соединение между этим сервером и хостом и портом (обычно TCP-порт 8443 или порт 443 для ОС UniFi), на котором работает UniFi-контроллер
вы должны использовать учетную запись с правами локального доступа для доступа к API контроллера UniFi через этот класс.
не используйте учетные записи UniFi Cloud и не включайте 2FA для учетных записей, которые вы используете с этим классом.
Поддержка контроллеров на базе ОС UniFi добавлена с версии 1.1.47. Эти устройства/сервисы были проверены на работоспособность:
Маршрутизатор UniFi Dream (UDR)
Машина мечты UniFi (UDM)
UniFi Dream Machine Pro (UDM PRO)
UniFi Cloud Key Gen2 (UCK G2), версия прошивки 2.0.24 или выше
UniFi Cloud Key Gen2 Plus (UCK G2 Plus), версия прошивки 2.0.24 или выше
ЮниФи Экспресс (UX)
UniFi Dream Wall (UDW)
UniFi Cloud Gateway Ultra (UCG-Ultra)
UniFi CloudKey Enterprise (CK-Предприятие)
UniFi Enterprise Fortress Gateway (EFG)
Официальный хостинг UniFi, подробности здесь.
Класс автоматически определяет консоли ОС UniFi и соответствующим образом настраивает URL-адреса и несколько функций/методов.
Контроллеры на базе ОС UniFi требуют подключения через порт 443 вместо 8443 , который используется для «программных» контроллеров. Если ваш собственный код реализует строгую проверку URL-адреса, передаваемого в конструктор, адаптируйте свою логику, чтобы разрешить URL-адреса без суффикса порта или с портом 443 при работе с контроллером на базе ОС UniFi.
При подключении к шлюзу на базе ОС UniFi через WAN-интерфейс вам необходимо создать специальное правило межсетевого экрана, позволяющее это разрешить. Дополнительную информацию см. в этом сообщении в блоге на веб-сайте Art of WiFi: https://artofwifi.net/blog/how-to-access-the-unifi-controller-by-wan-ip-or-hostname-on-a-. удм-про
Описанный там подход с использованием «пользовательских правил брандмауэра» является рекомендуемым методом.
При обновлении с версии до 1.1.84 , пожалуйста:
убедитесь, что вы используете PHP 7.4 или выше
протестируйте клиент с вашим кодом на наличие критических изменений; методы класса теперь имеют строгие подсказки по типам параметров и типам ответов, которые могут сломать ваш код в определенных случаях, когда передается неправильный тип или ожидается ответ другого типа.
Используйте Composer, Git или просто загрузите релиз, чтобы установить клиентский класс API.
Предпочтительный метод установки — через композитор. Следуйте этим инструкциям по установке, если у вас еще не установлен композитор.
После установки композитора просто выполните эту команду из оболочки в каталоге вашего проекта:
композитору требуется art-of-wifi/unifi-api-client
Или вручную добавьте пакет в файл композитора.json:
{"require": {"art-of-wifi/unifi-api-client": "^1.1"}}Наконец, обязательно включите автозагрузчик композитора в свой код, если ваша платформа еще не делает этого за вас:
/** * загружаем класс с помощью автозагрузчика композитора */require_once 'vendor/autoload.php';
Выполните следующую команду git из оболочки в каталоге вашего проекта:
git-клон https://github.com/Art-of-WiFi/UniFi-API-client.git
Когда git завершит клонирование, включите файл, содержащий класс, в свой код:
/** * загружаем класс напрямую, вместо использования автозагрузчика композитора */require_once 'path/to/src/Client.php';
Если вы предпочитаете не использовать композитор или git, просто загрузите пакет, распакуйте zip-файл, а затем включите файл, содержащий класс, в свой код следующим образом:
/** * загружаем класс напрямую, вместо использования автозагрузчика композитора */require_once 'path/to/src/Client.php';
Базовый пример использования класса:
/** * загружаем класс с помощью автозагрузчика композитора */require_once 'vendor/autoload.php';/** * инициализируем класс подключения UniFi API, войдите в контроллер и запросите сбор сигналов тревоги * (в этом примере предполагается, что у вас есть уже присвоены правильные значения используемым переменным) */$unifi_connection = new UniFi_APIClient($controller_user, $controller_password, $controller_url, $site_id, $controller_version, true);$login = $unifi_connection->login();$results = $unifi_connection->list_alarms(); // возвращает массив PHP, содержащий объекты сигналов тревоги
Пожалуйста, обратитесь к каталогу examples/ для получения более подробных примеров, которые можно использовать в качестве отправной точки для вашего собственного кода PHP.
В приведенном выше примере $site_id — это короткое «имя» сайта (обычно длиной 8 символов), которое отображается в URL-адресе при управлении сайтом в сетевом контроллере UniFi. Например, с этим URL-адресом:
https://<controller IP address or FQDN>:8443/manage/site/jl3z2shm/dashboard
jl3z2shm — это короткое «имя» сайта и значение, присваиваемое $site_id.
Шестой необязательный параметр, передаваемый конструктору в приведенном выше примере ( true ), включает проверку SSL-сертификата контроллера, который в противном случае отключен по умолчанию. Настоятельно рекомендуется включить эту функцию в производственных средах, где на контроллере UniFi установлен действительный сертификат SSL, связанный с полным доменным именем в параметре controller_url . Эта опция была добавлена в клиенте API версии 1.1.16.
Использование учетной записи администратора ( $controller_user в приведенном выше примере) с разрешениями только для чтения может ограничить видимость определенных свойств коллекции/объекта. См. эту проблему и эту проблему для примера, когда пароль WPA2 не отображается для учетных записей администратора, доступных только для чтения .
В настоящее время класс поддерживает следующие функции/методы для доступа к API контроллера UniFi. Этот список отсортирован в алфавитном порядке. Пожалуйста, обратитесь к комментариям в исходном коде для получения более подробной информации о каждой из функций/методов, их назначении и соответствующих параметрах.
принять_устройство()
Advanced_adopt_device()
archive_alarm()
Assign_existing_admin()
авторизовать_гость()
блок_ста()
cancel_rolling_upgrade()
check_controller_update()
check_firmware_update()
cmd_stat()
count_alarms()
create_apgroup()
create_dynamicdns()
create_firewallgroup()
create_hotspotop()
create_network()
create_radius_account()
create_user()
create_usergroup()
create_voucher()
create_wlan()
custom_api_request()
delete_apgroup()
delete_device()
delete_firewallgroup()
delete_network()
delete_radius_account()
удалить_сайт()
delete_usergroup()
delete_wlan()
отключить_ап()
отключить_wlan()
edit_apgroup()
edit_client_fixedip()
edit_client_name()
edit_firewallgroup()
edit_usergroup()
Extend_guest_validity()
забыть_ста()
генерировать_резервную копию()
генерировать_backup_site()
get_class_version()
get_cookie()
get_cookies()
get_curl_connection_timeout()
get_curl_http_version()
get_curl_method()
get_curl_request_timeout()
get_curl_request_timeout()
get_curl_ssl_verify_host()
get_curl_ssl_verify_peer()
get_debug()
get_is_unifi_os()
get_last_error_message()
get_last_results_raw()
get_site()
приглашение_admin()
светодиод_override()
list_admins()
list_all_admins()
list_alarms()
list_aps()
list_backups()
список_клиентов()
list_country_codes()
list_current_channels()
list_dashboard()
list_device_name_mappings()
list_device_states()
список_устройств()
list_devices_basic()
list_dynamicdns()
list_events()
list_extension()
list_firewallgroups()
список_прошивка()
list_guests()
список_здоровье()
list_hotspotop()
list_known_rogueaps()
list_networkconf()
list_portconf()
list_portforward_stats()
list_portforwarding()
list_radius_accounts()
list_radius_profiles()
list_self()
list_settings()
список_сайтов()
list_tags()
список_пользователей()
list_wlan_groups()
list_wlanconf()
locate_ap()
авторизоваться()
выход из системы()
move_device()
power_cycle_switch_port()
перезагрузка_cloudkey()
переименовать_ап()
revoke_admin()
revoke_voucher()
set_ap_radiosettings()
set_ap_wlangroup()
set_connection_timeout()
set_cookies()
set_curl_http_version()
set_curl_request_timeout()
set_curl_ssl_verify_host()
set_curl_ssl_verify_peer()
set_debug()
set_device_settings_base()
set_dynamicdns()
set_element_adoption()
set_guestlogin_settings()
set_guestlogin_settings_base()
set_ips_settings_base()
set_is_unifi_os()
set_locate_ap() (устарело, но все еще доступно как псевдоним)
set_networksettings_base()
set_radius_account_base()
set_request_method()
set_request_timeout()
set_site()
set_site_connectivity()
set_site_country()
set_site_guest_access()
set_site_locale()
set_site_mgmt()
set_site_name()
set_site_ntp()
set_site_snmp()
set_sta_name()
set_sta_note()
set_super_identity_settings_base()
set_super_mgmt_settings_base()
set_super_smtp_settings_base()
set_usergroup()
set_wlan_mac_filter()
set_wlansettings()
set_wlansettings_base()
site_leds()
Spectrum_scan()
Spectrum_scan_state()
start_rolling_upgrade()
stat_5MINUT_APS()
stat_5MINUT_GATEWAY()
стат_5минут_сайт()
stat_5MINUT_user()
stat_allusers()
stat_auths()
stat_client()
stat_daily_aps()
stat_daily_gateway()
stat_daily_site()
stat_daily_user()
stat_full_status()
stat_hourly_aps()
stat_hourly_gateway()
stat_hourly_site()
stat_hourly_user()
stat_ips_events()
stat_monthly_aps()
stat_monthly_gateway()
stat_monthly_site()
stat_monthly_user()
stat_pay()
stat_sessions()
stat_sites()
stat_speedtest_results()
stat_sta_sessions_latest()
stat_status()
stat_sysinfo()
stat_voucher()
unauthorize_guest()
unblock_sta()
unset_locate_ap() (устарело, но все еще доступно как псевдоним)
обновление_устройства()
update_device_external()
Еще предстоит проделать работу по добавлению функциональности и дальнейшему улучшению удобства использования этого класса, поэтому все предложения/комментарии приветствуются. Пожалуйста, используйте раздел «Проблемы GitHub» или форумы сообщества Ubiquiti (https://community.ubnt.com/t5/UniFi-Wireless/PHP-class-to-access-the-UniFi-controller-API-updates-and/td- p/1512870), чтобы поделиться своими предложениями и вопросами.
При возникновении проблем с API UniFi при использовании других библиотек, cURL или Postman, не открывайте проблему. Такие вопросы будут немедленно закрыты. Вместо этого используйте раздел «Обсуждения».
Если вы хотите внести свой код (улучшения), откройте проблему и включите туда свой код или создайте запрос на включение.
Этот класс основан на первоначальной работе следующих разработчиков:
домво: https://community.ui.com/questions/little-php-class-for-unifi-api/933d3fb3-b401-4499-993a-f9af079a4a3a
фбагнол: https://github.com/fbagnol/class.unifi.php
и API, опубликованный Ubiquiti:
https://dl.ui.com/unifi/8.0.26/unifi_sh_api
Многие функции этого клиентского класса API официально не поддерживаются Ubiquiti и поэтому могут не поддерживаться в будущих версиях API контроллера UniFi.
