README

一个 PHP 类，提供对 Ubiquiti 的 UniFi 网络应用程序 API 的访问。

UniFi 网络应用程序软件版本 5.X.X、6.X.X、7.X.X 和 8.X.X（已确认版本 8.1.104 可用）以及基于 UniFi OS 的控制台应用程序（已确认 UniFi OS 3.2.12 可用）都受支持。此类由我们的 API 浏览器工具使用，可在此处找到。

该软件包可以手动安装或通过使用 composer/packagist 来轻松包含到您的项目中。

要求

一个服务器
- PHP 7.4.0 或更高版本（对于 PHP 7.3.x 和更低版本，请使用版本 1.1.83）
- PHP json 和 PHP cURL 模块
- 在 Apache 2.4、PHP 7.4.27 和 cURL 7.60.0 以及 PHP 8.2.12 和 cURL 7.81.0 上进行过测试
此服务器与运行 UniFi 控制器的主机和端口（通常是 TCP 端口 8443 或 UniFi OS 的 443 端口）之间的直接网络连接
您必须使用具有本地访问权限的账户通过此类访问 UniFi 控制器 API
不要使用 UniFi 云账户，并且不要为使用此类的账户启用 2FA

UniFi OS 支持

自版本 1.1.47 以来，已添加对基于 UniFi OS 控制器的支持。这些设备已验证可以正常工作

UniFi Dream Router (UDR)
UniFi Dream Machine (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 或更高
UniFi Cloud Console，详细信息此处
UniFi Express (UX)

该类会自动检测基于 UniFi OS 的控制台，并根据需要调整 URL 和几个函数/方法。

基于 UniFi OS 的控制台要求您使用端口 443 而不是用于“基于软件”控制器的 8443。如果您自己的代码实现了对构造函数传递的 URL 的严格验证，请在与基于 UniFi OS 的控制器一起工作时，调整您的逻辑以允许不带端口号或带有端口 443 的 URL。

基于 UniFi OS 控制器的远程 API 访问

当通过 WAN 接口连接到 UniFi OS 网关时，您需要创建一个特定的防火墙规则来允许此操作。有关更多详细信息，请参阅 Art of WiFi 网站的这篇博客文章：https://artofwifi.net/blog/how-to-access-the-unifi-controller-by-wan-ip-or-hostname-on-a-udm-pro

其中描述的“自定义防火墙规则”方法是推荐的方法。

从先前版本升级

当从 1.1.84 之前的版本升级时，请

确保您使用的是PHP 7.4 或更高版本
使用您的代码测试客户端，以检查任何破坏性变更；类方法现在具有严格的参数类型提示和响应类型，这可能在传递错误类型或在期望不同响应类型的情况下破坏您的代码

安装

使用 Composer、Git 或直接下载发行版来安装API客户端类。

Composer

首选的安装方法是使用 composer。如果您尚未安装composer，请按照以下安装说明进行操作。

一旦安装了composer，只需在项目目录的shell中执行此命令即可

composer require art-of-wifi/unifi-api-client

或者手动将包添加到您的composer.json文件中

{
    "require": {
        "art-of-wifi/unifi-api-client": "^1.1"
    }
}

最后，如果您的框架没有这样做，请确保在您的代码中包含composer自动加载器

/**
 * load the class using the composer autoloader
 */
require_once 'vendor/autoload.php';

Git

从项目目录的shell中执行以下 git 命令

git clone https://github.com/Art-of-WiFi/UniFi-API-client.git

当git完成克隆后，将包含类的文件按如下方式包含到您的代码中

/**
 * load the class directly instead of using the composer autoloader
 */
require_once 'path/to/src/Client.php';

下载发行版

如果您不想使用composer或git，只需下载包，解压zip文件，然后将包含类的文件按如下方式包含到您的代码中

/**
 * load the class directly instead of using the composer autoloader
 */
require_once 'path/to/src/Client.php';

示例用法

一个基本示例，说明如何使用类

/**
 * load the class using the composer autoloader
 */
require_once 'vendor/autoload.php';

/**
 * initialize the UniFi API connection class, log in to the controller and request the alarms collection
 * (this example assumes you have already assigned the correct values to the variables used)
 */
$unifi_connection = new UniFi_API\Client($controller_user, $controller_password, $controller_url, $site_id, $controller_version, true);
$login            = $unifi_connection->login();
$results          = $unifi_connection->list_alarms(); // returns a PHP array containing alarm objects

请参阅 examples/ 目录中的更多详细示例，这些示例可以用作您自己PHP代码的起点。

重要提示

在上面的示例中，$site_id 是短站点 "名称"（通常长度为8个字符），在UniFi Network Controller中管理站点时可见。例如，使用此URL

https://<控制器IP地址或FQDN>:8443/manage/site/jl3z2shm/dashboard

jl3z2shm 是短站点 "名称"，应分配给 $site_id。
在上面的示例中传递给构造函数的第6个可选参数（true）启用了控制器SSL证书的验证，默认情况下此功能是禁用的。在具有在UniFi Controller上安装的有效SSL证书的生产环境中启用此功能是 强烈推荐 的，该SSL证书与 controller_url 参数中的FQDN相关联。此选项是在API客户端版本1.1.16中添加的。
使用具有只读权限的管理员账户（如上例中的 $controller_user）可以限制某些集合/对象属性的可见性。请参阅此问题和此问题，以了解WPA2密码对于只读管理员账户不可见的情况。

支持的函数/方法

类目前支持以下函数/方法来访问UniFi Controller API。此列表按字母顺序排序。请参阅源代码中的注释，以了解每个函数/方法、其目的以及相应的参数的更多详细信息。

adopt_device()
advanced_adopt_device()
archive_alarm()
assign_existing_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()
disable_ap()
disable_wlan()
编辑_apgroup()
编辑_client_fixedip()
编辑_client_name()
编辑_firewallgroup()
编辑_usergroup()
延长访客有效期()
忘记_sta()
生成备份()
生成备份站点()
获取_class_version()
获取_cookie()
获取_cookies()
获取_curl_connection_timeout()
获取_curl_http_version()
获取_curl_method()
获取_curl_request_timeout()
获取_curl_request_timeout()
获取_curl_ssl_verify_host()
获取_curl_ssl_verify_peer()
获取_debug()
获取_is_unifi_os()
获取_last_error_message()
获取_last_results_raw()
获取_site()
邀请管理员()
LED覆盖()
列出管理员()
列出所有管理员()
列出警报()
列出接入点()
列出备份()
列出客户端()
列出国家代码()
列出当前频道()
列出仪表板()
列出设备名称映射()
列出设备状态()
列出设备()
列出基本设备()
列出动态DNS()
列出事件()
列出扩展()
列出防火墙组()
列出固件()
列出访客()
列出健康状态()
列出热点操作()
列出已知的流氓接入点()
列出网络配置()
列出端口配置()
列出端口转发统计信息()
列出端口转发()
列出RADIUS账户()
列出RADIUS配置文件()
列出自身信息()
列出设置()
列出站点()
列出标签()
列出用户()
列出WLAN组()
列出WLAN配置()
定位接入点()
登录()
注销()
移动设备()
开关端口电源循环()
重启云密钥()
重命名接入点()
撤销管理员权限()
撤销凭证()
设置接入点无线设置()
设置接入点WLAN组()
设置连接超时()
设置_cookies()
设置_curl_http_version()
设置_curl_request_timeout()
设置_curl_ssl_verify_host()
设置_curl_ssl_verify_peer()
设置_debug()
设置设备基本设置()
设置动态DNS()
设置元素采用率()
设置访客登录设置()
设置访客登录基本设置()
设置IP设置基本()
设置_is_unifi_os()
设置_locate_ap() (已弃用但作为别名仍可用)
设置网络设置基本()
设置RADIUS账户基本()
设置请求方法()
设置请求超时()
设置_site()
设置站点连接性()
设置站点国家()
设置站点访客访问()
设置站点区域设置()
设置站点管理()
设置站点名称()
设置站点NTP()
设置站点SNMP()
设置STA名称()
设置STA备注()
设置超级身份设置基本()
设置超级管理设置基本()
设置超级SMTP设置基本()
设置用户组()
设置WLAN MAC过滤器()
设置WLAN设置()
设置WLAN设置基本()
站点LED灯()
频谱扫描()
频谱扫描状态()
启动滚动升级()
统计5分钟接入点()
统计5分钟网关()
统计5分钟站点()
统计5分钟用户()
统计所有用户()
统计认证()
统计客户端()
统计每日接入点()
统计每日网关()
统计每日站点()
统计每日用户()
统计完整状态()
统计每小时接入点()
统计每小时网关()
统计每小时站点()
统计每小时用户()
统计IP事件()
统计每月接入点()
统计每月网关()
统计每月站点()
统计每月用户()
统计支付()
统计会话()
统计站点()
统计速度测试结果()
统计最近STA会话()
统计状态()
统计系统信息()
统计凭证()
取消授权访客()
取消封锁_STA()
取消_locate_ap() (已弃用但作为别名仍可用)
升级设备()
外部升级设备()

需要帮助或有建议？

为了添加功能并进一步提高此类的可用性，还需要做更多工作，因此欢迎所有建议/评论。请使用GitHub 问题部分或Ubiquiti社区论坛 (https://community.ubnt.com/t5/UniFi-Wireless/PHP-class-to-access-the-UniFi-controller-API-updates-and/td-p/1512870) 分享您的建议和问题。

重要提示

当使用其他库、cURL 或 Postman 遇到 UniFi API 问题时，请不要创建 Issue。此类问题将被立即关闭。请使用讨论区。

贡献

如果您想贡献代码（改进），请创建 Issue 并在其中包含您的代码，或者创建 pull request。

致谢

以下开发者的初始工作构成了此类的基础：

以及由 Ubiquiti 发布的 API

https://dl.ui.com/unifi/8.0.26/unifi_sh_api

重要免责声明

此 API 客户端类中的许多功能未经 Ubiquiti 正式支持，因此可能不会在未来版本的 UniFi 控制器 API 中得到支持。

art-of-wifi / unifi-api-client

维护者

详细信息

README

要求

UniFi OS 支持

基于 UniFi OS 控制器的远程 API 访问

从先前版本升级

安装

Composer

Git

下载发行版

示例用法

重要提示

支持的函数/方法

需要帮助或有建议？

重要提示

贡献

致谢

重要免责声明