UniFi API client
1.1.101
Una clase PHP que proporciona acceso a la API de aplicación de red UniFi de Ubiquiti.
Esta clase es utilizada por nuestra herramienta API Browser, que se puede encontrar aquí.
El paquete se puede instalar manualmente o utilizando Composer/Packagist para incluirlo fácilmente en sus proyectos. Consulte las instrucciones de instalación a continuación para obtener más detalles.
| Software | Versiones |
|---|---|
| Aplicación/controlador de red UniFi | 5.XX, 6.XX, 7.XX, 8.XX ( se confirma 8.5.6 ) |
| Sistema operativo UniFi | 3.X, 4.X ( 4.1.15 está confirmado ) |
un servidor con:
PHP 7.4.0 o superior (use la versión 1.1.83 para PHP 7.3.x y versiones anteriores)
Módulos PHP json y PHP cURL
probado en Apache 2.4 con PHP 7.4.27 y cURL 7.60.0 y con PHP 8.3.11 y cURL 7.81.0
conectividad de red directa entre este servidor y el host y el puerto (generalmente el puerto TCP 8443 o el puerto 443 para UniFi OS) donde se ejecuta el controlador UniFi
debe usar una cuenta con permisos de acceso local para acceder a la API del controlador UniFi a través de esta clase
no use cuentas de UniFi Cloud y no habilite 2FA para las cuentas que usa con esta clase
Se agregó soporte para controladores basados en UniFi OS a partir de la versión 1.1.47. Se ha verificado que estos dispositivos/servicios funcionan:
Enrutador UniFi Dream (UDR)
Máquina de sueños UniFi (UDM)
UniFi Dream Machine Pro (UDM PRO)
UniFi Cloud Key Gen2 (UCK G2), versión de firmware 2.0.24 o superior
UniFi Cloud Key Gen2 Plus (UCK G2 Plus), versión de firmware 2.0.24 o superior
UniFi Express (UX)
Muro de ensueño UniFi (UDW)
UniFi Cloud Gateway Ultra (UCG-Ultra)
UniFi CloudKey Enterprise (CK-Enterprise)
Puerta de enlace UniFi Enterprise Fortress (EFG)
Hosting oficial de UniFi, detalles aquí
La clase detecta automáticamente las consolas UniFi OS y ajusta las URL y varias funciones/métodos en consecuencia.
Los controladores basados en UniFi OS requieren que usted se conecte usando el puerto 443 en lugar del 8443 que se usa para los controladores "basados en software". Si su propio código implementa una validación estricta de la URL que se pasa al constructor, adapte su lógica para permitir URL sin un sufijo de puerto o con el puerto 443 cuando trabaje con un controlador basado en el sistema operativo UniFi.
Al conectarse a una puerta de enlace basada en el sistema operativo UniFi a través de la interfaz WAN, debe crear una regla de firewall específica para permitirlo. Consulte esta publicación de blog en el sitio web Art of WiFi para obtener más detalles: https://artofwifi.net/blog/how-to-access-the-unifi-controller-by-wan-ip-or-hostname-on-a- udm-pro
El enfoque de "regla de firewall personalizada" que se describe allí es el método recomendado.
Al actualizar desde una versión anterior a la 1.1.84 , por favor:
asegúrese de estar utilizando PHP 7.4 o superior
pruebe el cliente con su código para detectar cambios importantes; Los métodos de clase ahora tienen sugerencias estrictas de tipos de parámetros y tipos de respuesta que pueden romper su código en ciertos casos en los que se pasa el tipo incorrecto o se espera un tipo de respuesta diferente.
Utilice Composer, Git o simplemente descargue la versión para instalar la clase de cliente API.
El método de instalación preferido es a través de Composer. Siga estas instrucciones de instalación si aún no tiene Composer instalado.
Una vez que Composer esté instalado, simplemente ejecute este comando desde el shell en el directorio de su proyecto:
El compositor requiere art-of-wifi/unifi-api-client
O agregue manualmente el paquete a su archivo compositor.json:
{"require": {"arte-de-wifi/unifi-api-client": "^1.1"}}Finalmente, asegúrese de incluir el cargador automático del compositor en su código si su marco aún no lo hace por usted:
/** * carga la clase usando el autocargador del compositor */require_once 'vendor/autoload.php';
Ejecute el siguiente comando git desde el shell en el directorio de su proyecto:
clon de git https://github.com/Art-of-WiFi/UniFi-API-client.git
Cuando git termine de clonar, incluya el archivo que contiene la clase así en su código:
/** * carga la clase directamente en lugar de usar el cargador automático del compositor */require_once 'path/to/src/Client.php';
Si prefiere no utilizar Composer o Git, simplemente descargue el paquete, descomprima el archivo zip y luego incluya el archivo que contiene la clase en su código de esta manera:
/** * carga la clase directamente en lugar de usar el cargador automático del compositor */require_once 'path/to/src/Client.php';
Un ejemplo básico de cómo utilizar la clase:
/** * carga la clase usando el cargador automático del compositor */require_once 'vendor/autoload.php';/** * inicializa la clase de conexión API UniFi, inicia sesión en el controlador y solicita la recopilación de alarmas * (este ejemplo supone que tienes ya se han asignado los valores correctos a las variables utilizadas) */$unifi_connection = new UniFi_APIClient($controller_user, $controller_password, $controller_url, $site_id, $controller_version, verdadero);$login = $unifi_connection->login();$resultados = $unifi_connection->list_alarms(); // devuelve una matriz PHP que contiene objetos de alarma
Consulte el directorio de examples/ para ver algunos ejemplos más detallados que pueden usarse como punto de partida para su propio código PHP.
En el ejemplo anterior, $site_id es el "nombre" corto del sitio (generalmente de 8 caracteres) que es visible en la URL cuando se administra el sitio en el controlador de red UniFi. Por ejemplo con esta URL:
https://<controller IP address or FQDN>:8443/manage/site/jl3z2shm/dashboard
jl3z2shm es el "nombre" corto del sitio y el valor para asignar a $site_id.
El sexto parámetro opcional que se pasa al constructor en el ejemplo anterior ( true ) habilita la validación del certificado SSL del controlador que, de lo contrario, está deshabilitado de forma predeterminada. Se recomienda encarecidamente habilitar esta función en entornos de producción donde tenga un certificado SSL válido instalado en el controlador UniFi asociado con el FQDN en el parámetro controller_url . Esta opción se agregó con la versión 1.1.16 del cliente API.
El uso de una cuenta de administrador ( $controller_user en el ejemplo anterior) con permisos de solo lectura puede limitar la visibilidad de ciertas propiedades de colección/objeto. Consulte este problema y este problema para ver un ejemplo en el que la contraseña WPA2 no es visible para cuentas de administrador de solo lectura .
Actualmente, la clase admite las siguientes funciones/métodos para acceder a la API del controlador UniFi. Esta lista está ordenada alfabéticamente. Consulte los comentarios en el código fuente para obtener más detalles sobre cada una de las funciones/métodos, su propósito y sus respectivos parámetros.
adoptar_dispositivo()
dispositivo_adoptado_avanzado()
alarma_archivo()
asignar_admin_existente()
autorizar_invitado()
bloque_sta()
cancelar_rolling_upgrade()
check_controller_update()
check_firmware_update()
cmd_stat()
contar_alarmas()
crear_apgroup()
crear_dinámicodns()
crear_grupo de cortafuegos()
crear_hotspotop()
crear_red()
crear_radio_cuenta()
crear_usuario()
crear_grupo de usuarios()
crear_vale()
crear_wlan()
solicitud_api_personalizada()
eliminar_apgroup()
eliminar_dispositivo()
eliminar_grupo de cortafuegos()
eliminar_red()
eliminar_radio_cuenta()
eliminar_sitio()
eliminar_grupo de usuarios()
eliminar_wlan()
desactivar_ap()
desactivar_wlan()
editar_apgrupo()
edit_client_fixedip()
editar_nombre_cliente()
edit_firewallgroup()
editar_grupo de usuarios()
extender_guest_validity()
olvidar_sta()
generar_copia de seguridad()
generar_backup_site()
get_class_version()
obtener_cookie()
obtener_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()
obtener_sitio()
invitación_admin()
led_override()
lista_admins()
lista_todos_admins()
lista_alarmas()
lista_aps()
lista_copias de seguridad()
lista_clientes()
lista_códigos_país()
lista_canales_actuales()
lista_tablero()
list_device_name_mappings()
lista_estados_dispositivos()
lista_dispositivos()
lista_dispositivos_basic()
lista_dinámicodns()
lista_eventos()
lista_extensión()
lista_grupos de firewall()
lista_firmware()
lista_invitados()
lista_salud()
lista_hotspotop()
lista_conocido_rogueaps()
lista_redconf()
lista_portconf()
lista_portforward_stats()
lista_reenvío de puertos()
lista_radio_cuentas()
lista_radio_perfiles()
lista_self()
configuración_lista()
lista_sitios()
lista_etiquetas()
lista_usuarios()
lista_wlan_groups()
lista_wlanconf()
localizar_ap()
acceso()
cerrar sesión()
mover_dispositivo()
power_cycle_switch_port()
reiniciar_cloudkey()
cambiar nombre_ap()
revocar_admin()
revocar_vale()
set_ap_radiosettings()
set_ap_wlangroup()
set_connection_timeout()
establecer_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() (obsoleto pero aún disponible como alias)
set_networksettings_base()
set_radius_account_base()
set_request_method()
set_request_timeout()
establecer_sitio()
set_site_connectivity()
set_sitio_país()
set_site_guest_access()
set_site_locale()
set_site_mgmt()
establecer_nombre_sitio()
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()
leds_sitio()
espectro_scan()
espectro_scan_state()
inicio_rolling_upgrade()
estadísticas_5minutos_aps()
stat_5minutos_gateway()
stat_5minutos_sitio()
estadística_5minutos_usuario()
estadísticas_todos los usuarios()
estadísticas_auth()
estadística_cliente()
estadísticas_diarias_aps()
stat_daily_gateway()
stat_daily_site()
stat_daily_user()
stat_full_status()
estadísticas_horas_aps()
stat_hourly_gateway()
stat_hourly_site()
stat_hourly_user()
estadísticas_ips_eventos()
estadísticas_mesuales_aps()
stat_monthly_gateway()
stat_monthly_site()
estadística_mensual_usuario()
estadística_pago()
sesiones_estadísticas()
sitios_estadísticos()
stat_speedtest_results()
stat_sta_sessions_latest()
estado_estadístico()
stat_sysinfo()
vale_estadístico()
huésped_no autorizado()
desbloquear_sta()
unset_locate_ap() (obsoleto pero aún disponible como alias)
dispositivo_actualización()
actualización_dispositivo_externo()
Todavía queda trabajo por hacer para agregar funcionalidad y mejorar aún más la usabilidad de esta clase, por lo que todas las sugerencias/comentarios son bienvenidos. Utilice la sección de problemas de GitHub o los foros de la comunidad de Ubiquiti (https://community.ubnt.com/t5/UniFi-Wireless/PHP-class-to-access-the-UniFi-controller-API-updates-and/td- p/1512870) para compartir sus sugerencias y preguntas.
Cuando tenga problemas con la API de UniFi al utilizar otras bibliotecas, cURL o Postman, no abra un problema. Estos problemas se cerrarán de inmediato. Utilice la sección Discusiones en su lugar.
Si desea contribuir con código (mejoras), abra una incidencia e incluya su código allí o cree una solicitud de extracción.
Esta clase se basa en el trabajo inicial de los siguientes desarrolladores:
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
y la API publicada por Ubiquiti:
https://dl.ui.com/unifi/8.0.26/unifi_sh_api
Muchas de las funciones de esta clase de cliente API no son compatibles oficialmente con Ubiquiti y, como tales, es posible que no sean compatibles con versiones futuras de la API del controlador UniFi.
