UniFi API client
1.1.101
Uma classe PHP que fornece acesso à API de aplicativos de rede UniFi da Ubiquiti.
Esta classe é usada pela nossa ferramenta API Browser, que pode ser encontrada aqui.
O pacote pode ser instalado manualmente ou usando o compositor/packagist para facilitar a inclusão em seus projetos. Consulte as instruções de instalação abaixo para obter mais detalhes.
| Programas | Versões |
|---|---|
| Aplicativo/controlador de rede UniFi | 5.XX, 6.XX, 7.XX, 8.XX ( 8.5.6 está confirmado ) |
| SO UniFi | 3.X, 4.X ( 4.1.15 está confirmado ) |
um servidor com:
PHP 7.4.0 ou superior (use a versão 1.1.83 para PHP 7.3.x e inferior)
Módulos PHP json e PHP cURL
testado no Apache 2.4 com PHP 7.4.27 e cURL 7.60.0 e com PHP 8.3.11 e cURL 7.81.0
conectividade de rede direta entre este servidor e o host e a porta (geralmente porta TCP 8443 ou porta 443 para UniFi OS) onde o controlador UniFi está sendo executado
você deve usar uma conta com permissões de acesso local para acessar a API UniFi Controller por meio desta classe
não use contas UniFi Cloud e não habilite 2FA para as contas que você usa com esta classe
O suporte para controladores baseados em UniFi OS foi adicionado a partir da versão 1.1.47. Estes dispositivos/serviços foram verificados para funcionar:
Roteador UniFi Dream (UDR)
Máquina de Sonhos UniFi (UDM)
UniFi Dream Machine Pro (UDM PRO)
UniFi Cloud Key Gen2 (UCK G2), versão de firmware 2.0.24 ou superior
UniFi Cloud Key Gen2 Plus (UCK G2 Plus), versão de firmware 2.0.24 ou superior
UniFi Express (UX)
Parede de sonho UniFi (UDW)
UniFi Cloud Gateway Ultra (UCG-Ultra)
UniFi CloudKey Enterprise (CK-Enterprise)
Gateway UniFi Enterprise Fortress (EFG)
Hospedagem oficial UniFi, detalhes aqui
A classe detecta automaticamente consoles UniFi OS e ajusta os URLs e várias funções/métodos de acordo.
Os controladores baseados no UniFi OS exigem que você se conecte usando a porta 443 em vez da 8443 , que é usada para controladores "baseados em software". Se seu próprio código implementa validação estrita da URL que é passada para o construtor, adapte sua lógica para permitir URLs sem sufixo de porta ou com porta 443 ao trabalhar com um controlador baseado em UniFi OS.
Ao conectar-se a um gateway baseado em UniFi OS através da interface WAN, você precisa criar uma regra de firewall específica para permitir isso. Veja esta postagem do blog no site Art of WiFi para mais detalhes: https://artofwifi.net/blog/how-to-access-the-unifi-controller-by-wan-ip-or-hostname-on-a- udm-pro
A abordagem de "regra de firewall personalizada" descrita é o método recomendado.
Ao atualizar de uma versão anterior a 1.1.84 , por favor:
certifique-se de estar usando PHP 7.4 ou superior
teste o cliente com seu código para quaisquer alterações significativas; os métodos de classe agora têm dicas estritas de tipo de parâmetro e tipos de resposta que podem quebrar seu código em certos casos onde o tipo errado é passado ou um tipo de resposta diferente é esperado de volta
Use Composer, Git ou simplesmente baixe o Release para instalar a classe cliente API.
O método de instalação preferido é através do compositor. Siga estas instruções de instalação se você ainda não tiver o compositor instalado.
Depois que o compositor estiver instalado, simplesmente execute este comando no shell no diretório do seu projeto:
compositor requer arte de wifi/unifi-api-client
Ou adicione manualmente o pacote ao seu arquivo compositor.json:
{"require": {"art-of-wifi/unifi-api-client": "^1.1"}}Por fim, certifique-se de incluir o autoloader do compositor em seu código se sua estrutura ainda não fizer isso para você:
/** * carrega a classe usando o autoloader do compositor */require_once 'vendor/autoload.php';
Execute o seguinte comando git no shell no diretório do seu projeto:
clone do git https://github.com/Art-of-WiFi/UniFi-API-client.git
Quando o git terminar a clonagem, inclua o arquivo que contém a classe assim no seu código:
/** * carrega a classe diretamente em vez de usar o autoloader do compositor */require_once 'path/to/src/Client.php';
Se você preferir não usar o compositor ou o git, basta baixar o pacote, descompactar o arquivo zip e incluir o arquivo que contém a classe em seu código, assim:
/** * carrega a classe diretamente em vez de usar o autoloader do compositor */require_once 'path/to/src/Client.php';
Um exemplo básico de como usar a classe:
/** * carrega a classe usando o autoloader do compositor */require_once 'vendor/autoload.php';/** * inicializa a classe de conexão da API UniFi, faz login no controlador e solicita a coleta de alarmes * (este exemplo pressupõe que você tenha já atribuídos os valores corretos às variáveis utilizadas) */$unifi_connection = new UniFi_APIClient($controller_user, $controller_password, $controller_url, $site_id, $controller_version, true);$login = $unifi_connection->login();$resultados = $unifi_connection->list_alarms(); // retorna um array PHP contendo objetos de alarme
Consulte o diretório examples/ para obter alguns exemplos mais detalhados que podem ser usados como ponto de partida para seu próprio código PHP.
No exemplo acima, $site_id é o “nome” abreviado do site (geralmente com 8 caracteres) que é visível na URL ao gerenciar o site no UniFi Network Controller. Por exemplo com este URL:
https://<controller IP address or FQDN>:8443/manage/site/jl3z2shm/dashboard
jl3z2shm é o "nome" abreviado do site e o valor a ser atribuído a $site_id.
O sexto parâmetro opcional que é passado ao construtor no exemplo acima ( true ), permite a validação do certificado SSL do controlador que, de outra forma, é desabilitado por padrão. É altamente recomendável habilitar esse recurso em ambientes de produção onde você possui um certificado SSL válido instalado no UniFi Controller associado ao FQDN no parâmetro controller_url . Esta opção foi adicionada com o cliente API versão 1.1.16.
Usar uma conta de administrador ( $controller_user no exemplo acima) com permissões somente leitura pode limitar a visibilidade em determinadas propriedades de coleção/objeto. Consulte este problema e este problema para obter um exemplo em que a senha WPA2 não é visível para contas de administrador somente leitura .
A classe atualmente suporta as seguintes funções/métodos para acessar a API UniFi Controller. Esta lista é classificada em ordem alfabética. Consulte os comentários no código-fonte para obter mais detalhes sobre cada uma das funções/métodos, sua finalidade e seus respectivos parâmetros.
adotar_dispositivo()
advanced_adopt_device()
arquivo_alarme()
atribuir_existente_admin()
autorizar_convidado()
bloco_sta()
cancel_rolling_upgrade()
check_controller_update()
check_firmware_update()
cmd_stat()
contagem_alarmes()
create_apgroup()
criar_dynamicdns()
create_firewallgroup()
create_hotspotop()
criar_rede()
create_radius_account()
criar_usuário()
criar_usergroup()
criar_voucher()
criar_wlan()
custom_api_request()
delete_apgroup()
delete_device()
delete_firewallgroup()
delete_network()
delete_radius_account()
excluir_site()
delete_usergroup()
deletar_wlan()
desativar_ap()
desativar_wlan()
edit_apgroup()
edit_client_fixedip()
editar_nome_cliente()
edit_firewallgroup()
editar_usergroup()
extend_guest_validity()
esquecer_sta()
gerar_backup()
gerar_backup_site()
get_class_version()
get_cookie()
get_cookies()
get_curl_connection_timeout()
get_curl_http_versão()
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()
convite_admin()
led_override()
list_admins()
list_all_admins()
lista_alarmes()
lista_aps()
lista_backups()
lista_clientes()
list_country_codes()
list_current_channels()
list_dashboard()
list_device_name_mappings()
list_device_states()
lista_dispositivos()
list_devices_basic()
lista_dynamicdns()
lista_eventos()
extensão_lista()
list_firewallgroups()
lista_firmware()
lista_convidados()
lista_saúde()
list_hotspotop()
list_known_rogueaps()
list_networkconf()
list_portconf()
list_portforward_stats()
list_portforwarding()
list_radius_accounts()
list_radius_profiles()
lista_self()
lista_configurações()
lista_sites()
lista_tags()
lista_usuários()
list_wlan_groups()
list_wlanconf()
localizar_ap()
Conecte-se()
sair()
mover_dispositivo()
power_cycle_switch_port()
reiniciar_cloudkey()
renomear_ap()
revogar_admin()
revogar_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() (obsoleto, mas ainda disponível como alias)
set_networksettings_base()
set_radius_account_base()
set_request_method()
set_request_timeout()
set_site()
set_site_connectivity()
set_site_país()
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()
espectro_scan()
espectro_scan_state()
start_rolling_upgrade()
stat_5minutos_aps()
stat_5minutos_gateway()
stat_5minutos_site()
stat_5minutos_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_pagamento()
stat_sessions()
stat_sites()
stat_speedtest_results()
stat_sta_sessions_latest()
status_status()
stat_sysinfo()
stat_voucher()
desautorizar_convidado()
desbloquear_sta()
unset_locate_ap() (obsoleto, mas ainda disponível como alias)
dispositivo_atualização()
atualizar_device_external()
Ainda há trabalho a ser feito para adicionar funcionalidades e melhorar ainda mais a usabilidade desta classe, portanto todas as sugestões/comentários são bem-vindos. Por favor, use a seção GitHub Issues ou os fóruns da comunidade Ubiquiti (https://community.ubnt.com/t5/UniFi-Wireless/PHP-class-to-access-the-UniFi-controller-API-updates-and/td- p/1512870) para compartilhar suas sugestões e dúvidas.
Ao encontrar problemas com a API UniFi usando outras bibliotecas, cURL ou Postman, não abra um problema. Tais questões serão encerradas imediatamente. Por favor, use a seção Discussões.
Se você gostaria de contribuir com código (melhorias), abra um problema e inclua seu código lá ou então crie uma solicitação pull.
Esta classe é baseada no trabalho inicial dos seguintes desenvolvedores:
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
e a API publicada pela Ubiquiti:
https://dl.ui.com/unifi/8.0.26/unifi_sh_api
Muitas das funções nesta classe de cliente API não são oficialmente suportadas pela Ubiquiti e, como tal, podem não ser suportadas em versões futuras da API UniFi Controller.
