UniFi API client
1.1.101
Une classe PHP qui donne accès à l'API d'application réseau UniFi d'Ubiquiti.
Cette classe est utilisée par notre outil API Browser, qui peut être trouvé ici.
Le package peut être installé manuellement ou en utilisant composer/packagist pour une inclusion facile dans vos projets. Voir les instructions d'installation ci-dessous pour plus de détails.
| Logiciel | Versions |
|---|---|
| Application/contrôleur réseau UniFi | 5.XX, 6.XX, 7.XX, 8.XX ( 8.5.6 est confirmé ) |
| Système d'exploitation UniFi | 3.X, 4.X ( 4.1.15 est confirmé ) |
un serveur avec :
PHP 7.4.0 ou supérieur (utilisez la version 1.1.83 pour PHP 7.3.x et inférieur)
Modules PHP json et PHP cURL
testé sur Apache 2.4 avec PHP 7.4.27 et cURL 7.60.0 et avec PHP 8.3.11 et cURL 7.81.0
connectivité réseau directe entre ce serveur et l'hôte et le port (généralement le port TCP 8443 ou le port 443 pour UniFi OS) sur lequel le contrôleur UniFi est exécuté
vous devez utiliser un compte avec des autorisations d'accès local pour accéder à l'API UniFi Controller via cette classe
n'utilisez pas de comptes UniFi Cloud et n'activez pas 2FA pour les comptes que vous utilisez avec cette classe
La prise en charge des contrôleurs basés sur UniFi OS a été ajoutée à partir de la version 1.1.47. Il a été vérifié que ces appareils/services fonctionnent :
Routeur UniFi Dream (UDR)
Machine de rêve UniFi (UDM)
UniFi Dream Machine Pro (UDM PRO)
UniFi Cloud Key Gen2 (UCK G2), version du firmware 2.0.24 ou supérieure
UniFi Cloud Key Gen2 Plus (UCK G2 Plus), version du firmware 2.0.24 ou supérieure
UniFi Express (UX)
Mur de rêve UniFi (UDW)
UniFi Cloud Gateway Ultra (UCG-Ultra)
UniFi CloudKey Enterprise (CK-Enterprise)
Passerelle UniFi Enterprise Fortress (EFG)
Hébergement UniFi officiel, détails ici
La classe détecte automatiquement les consoles UniFi OS et ajuste les URL et plusieurs fonctions/méthodes en conséquence.
Les contrôleurs basés sur UniFi OS nécessitent que vous vous connectiez en utilisant le port 443 au lieu du 8443 qui est utilisé pour les contrôleurs « basés sur logiciel ». Si votre propre code implémente une validation stricte de l'URL transmise au constructeur, veuillez adapter votre logique pour autoriser les URL sans suffixe de port ou avec le port 443 lorsque vous travaillez avec un contrôleur basé sur UniFi OS.
Lors de la connexion à une passerelle basée sur UniFi OS via l'interface WAN, vous devez créer une règle de pare-feu spécifique pour autoriser cela. Consultez cet article de blog sur le site Web Art of WiFi pour plus de détails : https://artofwifi.net/blog/how-to-access-the-unifi-controller-by-wan-ip-or-hostname-on-a- udm-pro
L’approche « règle de pare-feu personnalisée » décrite ici est la méthode recommandée.
Lors d'une mise à niveau à partir d'une version antérieure à 1.1.84 , veuillez :
assurez-vous que vous utilisez PHP 7.4 ou supérieur
testez le client avec votre code pour détecter toute modification importante ; les méthodes de classe ont désormais des indications strictes sur les types de paramètres et des types de réponse qui peuvent casser votre code dans certains cas où le mauvais type est transmis ou où un type de réponse différent est attendu en retour
Utilisez Composer, Git ou téléchargez simplement la version pour installer la classe client API.
La méthode d'installation préférée consiste à utiliser Composer. Suivez ces instructions d'installation si Composer n'est pas déjà installé.
Une fois composer installé, exécutez simplement cette commande depuis le shell dans le répertoire de votre projet :
le compositeur nécessite art-of-wifi/unifi-api-client
Ou ajoutez manuellement le package à votre fichier composer.json :
{"require": {"art-of-wifi/unifi-api-client": "^1.1"}}Enfin, assurez-vous d'inclure le chargeur automatique composer dans votre code si votre framework ne le fait pas déjà pour vous :
/** * charge la classe à l'aide du chargeur automatique du compositeur */require_once 'vendor/autoload.php';
Exécutez la commande git suivante à partir du shell dans le répertoire de votre projet :
clone git https://github.com/Art-of-WiFi/UniFi-API-client.git
Lorsque git a terminé le clonage, incluez le fichier contenant la classe comme ceci dans votre code :
/** * charger la classe directement au lieu d'utiliser le chargeur automatique du compositeur */require_once 'path/to/src/Client.php';
Si vous préférez ne pas utiliser composer ou git, téléchargez simplement le package, décompressez le fichier zip, puis incluez le fichier contenant la classe dans votre code comme ceci :
/** * charger la classe directement au lieu d'utiliser le chargeur automatique du compositeur */require_once 'path/to/src/Client.php';
Un exemple simple d'utilisation de la classe :
/** * charger la classe à l'aide du chargeur automatique composer */require_once 'vendor/autoload.php';/** * initialiser la classe de connexion API UniFi, se connecter au contrôleur et demander la collecte des alarmes * (cet exemple suppose que vous avez déjà attribué les valeurs correctes aux variables utilisées) */$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(); // renvoie un tableau PHP contenant des objets d'alarme
Veuillez vous référer au répertoire examples/ pour des exemples plus détaillés qui peuvent être utilisés comme point de départ pour votre propre code PHP.
Dans l'exemple ci-dessus, $site_id est le « nom » court du site (généralement de 8 caractères) qui est visible dans l'URL lors de la gestion du site dans le contrôleur de réseau UniFi. Par exemple avec cette URL :
https://<controller IP address or FQDN>:8443/manage/site/jl3z2shm/dashboard
jl3z2shm est le "nom" court du site et la valeur à attribuer à $site_id.
Le 6ème paramètre facultatif transmis au constructeur dans l'exemple ci-dessus ( true ) permet la validation du certificat SSL du contrôleur qui est autrement désactivé par défaut. Il est fortement recommandé d'activer cette fonctionnalité dans les environnements de production où vous disposez d'un certificat SSL valide installé sur le contrôleur UniFi associé au nom de domaine complet dans le paramètre controller_url . Cette option a été ajoutée avec la version 1.1.16 du client API.
L'utilisation d'un compte administrateur ( $controller_user dans l'exemple ci-dessus) avec des autorisations en lecture seule peut limiter la visibilité sur certaines propriétés de collection/objet. Consultez ce problème et ce problème pour un exemple dans lequel le mot de passe WPA2 n'est pas visible pour les comptes d'administrateur en lecture seule .
La classe prend actuellement en charge les fonctions/méthodes suivantes pour accéder à l'API UniFi Controller. Cette liste est triée par ordre alphabétique. Veuillez vous référer aux commentaires dans le code source pour plus de détails sur chacune des fonctions/méthodes, leur objectif et leurs paramètres respectifs.
adopter_device()
avancé_adopt_device()
archive_alarme()
assign_existing_admin()
autoriser_guest()
block_sta()
annuler_rolling_upgrade()
check_controller_update()
check_firmware_update()
cmd_stat()
nombre_alarmes()
créer_apgroup()
create_dynamicdns()
créer_firewallgroup()
créer_hotspotop()
créer_réseau()
créer_radius_account()
créer_utilisateur()
créer_groupe d'utilisateurs()
créer_voucher()
créer_wlan()
custom_api_request()
supprimer_apgroup()
supprimer_appareil()
delete_firewallgroup()
supprimer_réseau()
delete_radius_account()
supprimer_site()
delete_usergroup()
supprimer_wlan()
désactiver_ap()
désactiver_wlan()
edit_apgroup()
edit_client_fixedip()
modifier_nom_client()
edit_firewallgroup()
edit_usergroup()
extend_guest_validity()
oublier_sta()
générer_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()
invite_admin()
led_override()
liste_admins()
list_all_admins()
liste_alarmes()
liste_aps()
liste_backups()
liste_clients()
list_country_codes()
list_current_channels()
liste_dashboard()
list_device_name_mappings()
list_device_states()
list_devices()
list_devices_basic()
list_dynamicdns()
liste_events()
liste_extension()
liste_firewallgroups()
liste_firmware()
liste_invités()
liste_santé()
liste_hotspotop()
list_known_rogueaps()
list_networkconf()
liste_portconf()
list_portforward_stats()
list_portforwarding()
list_radius_accounts()
list_radius_profiles()
liste_self()
liste_settings()
liste_sites()
liste_tags()
liste_utilisateurs()
list_wlan_groups()
list_wlanconf()
localiser_ap()
se connecter()
déconnexion()
move_device()
power_cycle_switch_port()
reboot_cloudkey()
renommer_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() (obsolète mais toujours disponible en tant qu'alias)
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()
spectre_scan()
spectre_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_paiement()
stat_sessions()
sites_stat()
stat_speedtest_results()
stat_sta_sessions_latest()
statut_stat()
stat_sysinfo()
stat_voucher()
unauthorize_guest()
débloquer_sta()
unset_locate_ap() (obsolète mais toujours disponible en tant qu'alias)
mise à niveau_device()
mise à niveau_device_external()
Il y a encore du travail à faire pour ajouter des fonctionnalités et améliorer encore la convivialité de cette classe, donc toutes les suggestions/commentaires sont les bienvenus. Veuillez utiliser la section Problèmes GitHub ou les forums de la communauté Ubiquiti (https://community.ubnt.com/t5/UniFi-Wireless/PHP-class-to-access-the-UniFi-controller-API-updates-and/td- p/1512870) pour partager vos suggestions et questions.
Lorsque vous rencontrez des problèmes avec l'API UniFi utilisant d'autres bibliothèques, cURL ou Postman, veuillez ne pas ouvrir de problème. Ces problèmes seront immédiatement résolus. Veuillez plutôt utiliser la section Discussions.
Si vous souhaitez contribuer au code (améliorations), veuillez ouvrir un ticket et y inclure votre code ou bien créer une pull request.
Cette classe est basée sur les travaux initiaux des développeurs suivants :
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
et l'API telle que publiée par Ubiquiti :
https://dl.ui.com/unifi/8.0.26/unifi_sh_api
De nombreuses fonctions de cette classe de client API ne sont pas officiellement prises en charge par Ubiquiti et, en tant que telles, pourraient ne pas être prises en charge dans les futures versions de l'API UniFi Controller.
