UniFi API client
1.1.101
Eine PHP-Klasse, die Zugriff auf die UniFi Network Application API von Ubiquiti bietet.
Diese Klasse wird von unserem API-Browser-Tool verwendet, das Sie hier finden.
Das Paket kann manuell oder mithilfe von Composer/Packagist installiert werden, um es einfach in Ihre Projekte einzubinden. Weitere Einzelheiten finden Sie in den Installationsanweisungen unten.
| Software | Versionen |
|---|---|
| UniFi-Netzwerkanwendung/Controller | 5.XX, 6.XX, 7.XX, 8.XX ( 8.5.6 ist bestätigt ) |
| UniFi-Betriebssystem | 3.X, 4.X ( 4.1.15 ist bestätigt ) |
ein Server mit:
PHP 7.4.0 oder höher (verwenden Sie Version 1.1.83 für PHP 7.3.x und niedriger)
PHP-JSON- und PHP-CURL-Module
Getestet auf Apache 2.4 mit PHP 7.4.27 und cURL 7.60.0 sowie mit PHP 8.3.11 und cURL 7.81.0
direkte Netzwerkverbindung zwischen diesem Server und dem Host und Port (normalerweise TCP-Port 8443 oder Port 443 für UniFi OS), auf dem der UniFi-Controller ausgeführt wird
Sie müssen ein Konto mit lokalen Zugriffsberechtigungen verwenden, um über diese Klasse auf die UniFi Controller-API zuzugreifen
Verwenden Sie keine UniFi Cloud-Konten und aktivieren Sie 2FA nicht für die Konten, die Sie mit dieser Klasse verwenden
Unterstützung für UniFi OS-basierte Controller wurde ab Version 1.1.47 hinzugefügt. Diese Geräte/Dienste funktionieren nachweislich:
UniFi Dream Router (UDR)
UniFi Dream Machine (UDM)
UniFi Dream Machine Pro (UDM PRO)
UniFi Cloud Key Gen2 (UCK G2), Firmware-Version 2.0.24 oder höher
UniFi Cloud Key Gen2 Plus (UCK G2 Plus), Firmware-Version 2.0.24 oder höher
UniFi Express (UX)
UniFi Dream Wall (UDW)
UniFi Cloud Gateway Ultra (UCG-Ultra)
UniFi CloudKey Enterprise (CK-Enterprise)
UniFi Enterprise Fortress Gateway (EFG)
Offizielles UniFi-Hosting, Details hier
Die Klasse erkennt UniFi OS-Konsolen automatisch und passt die URLs und verschiedene Funktionen/Methoden entsprechend an.
Bei UniFi OS-basierten Controllern müssen Sie die Verbindung über Port 443 statt 8443 herstellen, der für „softwarebasierte“ Controller verwendet wird. Wenn Ihr eigener Code eine strikte Validierung der an den Konstruktor übergebenen URL implementiert, passen Sie bitte Ihre Logik an, um URLs ohne Portsuffix oder mit Port 443 zuzulassen, wenn Sie mit einem UniFi OS-basierten Controller arbeiten.
Wenn Sie über die WAN-Schnittstelle eine Verbindung zu einem UniFi OS-basierten Gateway herstellen, müssen Sie eine bestimmte Firewall-Regel erstellen, um dies zu ermöglichen. Weitere Informationen finden Sie in diesem Blogbeitrag auf der Art of WiFi-Website: https://artofwifi.net/blog/how-to-access-the-unifi-controller-by-wan-ip-or-hostname-on-a- udm-pro
Der dort beschriebene Ansatz „benutzerdefinierte Firewall-Regel“ ist die empfohlene Methode.
Wenn Sie von einer Version vor 1.1.84 aktualisieren, gehen Sie bitte wie folgt vor:
Stellen Sie sicher, dass Sie PHP 7.4 oder höher verwenden
Testen Sie den Client mit Ihrem Code auf wichtige Änderungen. Die Klassenmethoden verfügen jetzt über strenge Parametertyphinweise und Antworttypen, die Ihren Code in bestimmten Fällen beschädigen können, wenn der falsche Typ übergeben wird oder ein anderer Antworttyp zurückerwartet wird
Verwenden Sie Composer, Git oder laden Sie einfach die Version herunter, um die API-Client-Klasse zu installieren.
Die bevorzugte Installationsmethode ist Composer. Befolgen Sie diese Installationsanweisungen, wenn Sie Composer noch nicht installiert haben.
Sobald Composer installiert ist, führen Sie einfach diesen Befehl über die Shell in Ihrem Projektverzeichnis aus:
Komponist benötigt Art-of-Wifi/Unifi-API-Client
Oder fügen Sie das Paket manuell zu Ihrer Composer.json-Datei hinzu:
{"require": {"art-of-wifi/unifi-api-client": "^1.1"}}Stellen Sie abschließend sicher, dass Sie den Composer-Autoloader in Ihren Code einbinden, falls Ihr Framework dies nicht bereits für Sie erledigt:
/** * die Klasse mit dem Composer-Autoloader laden */require_once 'vendor/autoload.php';
Führen Sie den folgenden git -Befehl von der Shell in Ihrem Projektverzeichnis aus:
Git-Klon https://github.com/Art-of-WiFi/UniFi-API-client.git
Wenn Git mit dem Klonen fertig ist, fügen Sie die Datei mit der Klasse wie folgt in Ihren Code ein:
/** * die Klasse direkt laden, anstatt den Composer-Autoloader zu verwenden */require_once 'path/to/src/Client.php';
Wenn Sie weder Composer noch Git verwenden möchten, laden Sie einfach das Paket herunter, entpacken Sie die ZIP-Datei und fügen Sie dann die Datei mit der Klasse wie folgt in Ihren Code ein:
/** * die Klasse direkt laden, anstatt den Composer-Autoloader zu verwenden */require_once 'path/to/src/Client.php';
Ein einfaches Beispiel für die Verwendung der Klasse:
/** * die Klasse mit dem Composer-Autoloader laden */require_once 'vendor/autoload.php';/** * die UniFi-API-Verbindungsklasse initialisieren, sich beim Controller anmelden und die Alarmsammlung anfordern * (in diesem Beispiel wird davon ausgegangen, dass Sie dies getan haben den verwendeten Variablen bereits die richtigen Werte zugewiesen) */$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(); // gibt ein PHP-Array zurück, das Alarmobjekte enthält
Weitere detaillierte Beispiele finden Sie im Verzeichnis examples/ , die als Ausgangspunkt für Ihren eigenen PHP-Code verwendet werden können.
Im obigen Beispiel ist $site_id der kurze Site-„Name“ (normalerweise 8 Zeichen lang), der in der URL sichtbar ist, wenn die Site im UniFi Network Controller verwaltet wird. Zum Beispiel mit dieser URL:
https://<controller IP address or FQDN>:8443/manage/site/jl3z2shm/dashboard
jl3z2shm ist der kurze Site-Name und der Wert, der $site_id zugewiesen werden soll.
Der 6. optionale Parameter, der im obigen Beispiel an den Konstruktor übergeben wird ( true ), ermöglicht die Validierung des SSL-Zertifikats des Controllers, das ansonsten standardmäßig deaktiviert ist. Es wird dringend empfohlen, diese Funktion in Produktionsumgebungen zu aktivieren, in denen auf dem UniFi-Controller ein gültiges SSL-Zertifikat installiert ist, das dem FQDN im Parameter controller_url zugeordnet ist. Diese Option wurde mit der API-Client-Version 1.1.16 hinzugefügt.
Die Verwendung eines Administratorkontos ( $controller_user im obigen Beispiel) mit schreibgeschützten Berechtigungen kann die Sichtbarkeit bestimmter Sammlungs-/Objekteigenschaften einschränken. In diesem Problem und diesem Problem finden Sie ein Beispiel, bei dem das WPA2-Kennwort für schreibgeschützte Administratorkonten nicht sichtbar ist.
Die Klasse unterstützt derzeit die folgenden Funktionen/Methoden für den Zugriff auf die UniFi Controller API. Diese Liste ist alphabetisch sortiert. Weitere Einzelheiten zu den einzelnen Funktionen/Methoden, ihrem Zweck und ihren jeweiligen Parametern finden Sie in den Kommentaren im Quellcode.
adopt_device()
advanced_adopt_device()
archive_alarm()
zuweisen_vorhandener_admin()
Authorize_guest()
block_sta()
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_site()
delete_usergroup()
delete_wlan()
deaktivieren_ap()
deaktivieren_wlan()
edit_apgroup()
edit_client_fixedip()
edit_client_name()
edit_firewallgroup()
edit_usergroup()
extend_guest_validity()
Vergiss_sta()
generate_backup()
generate_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()
einladen_admin()
led_override()
list_admins()
list_all_admins()
list_alarms()
list_aps()
list_backups()
list_clients()
list_country_codes()
list_current_channels()
list_dashboard()
list_device_name_mappings()
list_device_states()
list_devices()
list_devices_basic()
list_dynamicdns()
list_events()
list_extension()
list_firewallgroups()
list_firmware()
list_guests()
list_health()
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_sites()
list_tags()
list_users()
list_wlan_groups()
list_wlanconf()
locate_ap()
Login()
abmelden()
move_device()
power_cycle_switch_port()
reboot_cloudkey()
rename_ap()
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() (veraltet, aber immer noch als Alias verfügbar)
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_5minutes_aps()
stat_5minutes_gateway()
stat_5minutes_site()
stat_5minutes_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_zahlung()
stat_sessions()
stat_sites()
stat_speedtest_results()
stat_sta_sessions_latest()
stat_status()
stat_sysinfo()
stat_voucher()
unauthorize_guest()
unblock_sta()
unset_locate_ap() (veraltet, aber immer noch als Alias verfügbar)
upgrade_device()
upgrade_device_external()
Es gibt noch viel zu tun, um Funktionen hinzuzufügen und die Benutzerfreundlichkeit dieser Klasse weiter zu verbessern. Daher sind alle Vorschläge/Kommentare willkommen. Bitte nutzen Sie den GitHub-Problembereich oder die Ubiquiti-Community-Foren (https://community.ubnt.com/t5/UniFi-Wireless/PHP-class-to-access-the-UniFi-controller-API-updates-and/td- p/1512870), um Ihre Vorschläge und Fragen mitzuteilen.
Wenn Sie Probleme mit der UniFi-API bei der Verwendung anderer Bibliotheken, cURL oder Postman haben, öffnen Sie bitte kein Problem. Solche Probleme werden sofort geschlossen. Bitte nutzen Sie stattdessen den Abschnitt „Diskussionen“.
Wenn Sie Code (Verbesserungen) beisteuern möchten, öffnen Sie bitte ein Problem und fügen Sie dort Ihren Code ein oder erstellen Sie eine Pull-Anfrage.
Dieser Kurs basiert auf der ersten Arbeit der folgenden Entwickler:
domwo: https://community.ui.com/questions/little-php-class-for-unifi-api/933d3fb3-b401-4499-993a-f9af079a4a3a
fbagnol: https://github.com/fbagnol/class.unifi.php
und die von Ubiquiti veröffentlichte API:
https://dl.ui.com/unifi/8.0.26/unifi_sh_api
Viele der Funktionen in dieser API-Client-Klasse werden von Ubiquiti nicht offiziell unterstützt und werden daher möglicherweise in zukünftigen Versionen der UniFi Controller-API nicht unterstützt.
