README

一个PHP类，提供了访问Ubiquiti官方UniFi Cloud API的接口。

简介

此客户端提供了使用PHP与官方UniFi Cloud API交互的现代便捷方式。它使用Guzzle进行HTTP请求，并支持各种操作，以便通过编程方式与UniFi部署交互。

此客户端支持官方UniFi Cloud API的版本至 0.1。

重要提示

这不是我们原始API客户端的替代品，原始API客户端提供了更多功能和端点，但不支持通过unifi.ui.com进行连接：https://github.com/Art-of-WiFi/UniFi-API-client

要求

• 一个服务器，
  • PHP 8.1 或更高版本
  • 已安装并启用php-curl模块
• 此服务器与https://api.ui.com之间有直接网络连接
• 以下方式可以获得的API密钥
  • 在https://unifi.ui.com登录UniFi Site Manager。
  • 在左侧导航栏中点击API。
  • 点击创建API密钥。
  • 复制密钥并安全存储，因为它只会显示一次。
  • 点击“完成”以确保密钥已哈希并安全存储。

安装

需要使用Composer/packagist来安装此包，以便可以从您的项目目录中执行以下命令轻松包含它

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

如果您尚未安装Composer，请遵循安装说明。

开发者文档

用法

以下是如何使用UniFi Cloud API客户端的基本示例

<?php

require 'vendor/autoload.php';

use UniFiCloudApiClient\Client\UniFiClient;

$apiKey = 'your_api_key_here';

try {
    // Initialize the UniFi Cloud API client, optionally you can pass a different base URI
    $unifiClient = UniFiClient::getInstance($apiKey);
    
    // Enable debug mode, optional
    $unifiClient->setDebug(true);
    
    // Set a custom timeout to override the default value of 10 seconds, optional
    $unifiClient->setTimeout(5);
    
    // Fetch and echo the version
    echo 'UniFi Cloud API client version: ' . $unifiClient->getVersion() . PHP_EOL;
    
    // List all hosts
    $hosts = $unifiClient->hosts->list();
    print_r($hosts);
    
    // Get host by ID
    $hostId = 'your_host_id_here';
    $host = $unifiClient->hosts->get($hostId);
    print_r($host);
    
    // List all sites
    $sites = $unifiClient->sites->list();
    print_r($sites);
    
    // List all devices with optional filter parameters
    $devices = $unifiClient->devices->list(
        ['900A6F00301100000000074A6BA90000000007A3387E0000000063EC9853:123456789', '900A6F00301100000000074A6BA90000000007A3387E0000000063EC9853:987654321'], 
        '2024-07-15T07:01:13Z'
    );
    print_r($devices);
} catch (Exception $e) {
    echo "Error: " . $e->getMessage() . "\n";
}

echo 'Effective URI:   ' . $unifiClient->getEffectiveUri() . PHP_EOL;
echo 'Transfer time:   ' . $unifiClient->getTransferTime() . ' seconds' . PHP_EOL;
echo 'Response status: ' . $unifiClient->getResponseStatusCode() . PHP_EOL;

获取器和设置器方法

有几种获取器和设置器方法可用于与UniFi Cloud API客户端交互

API参考

列出主机

API路由

GET /ea/hosts

描述

检索与发起API调用的UI帐户关联的所有主机的列表。

用法

$hosts = $unifiClient->hosts->list();

示例响应

[
  "data" => [
    [
      "hardwareId" => "eae0f123-0000-5111-b111-f833f56eade5",
      "id" => "900A6F00301100000000074A6BA90000000007A3387E0000000063EC9853:123456789",
      "ipAddress" => "192.168.220.114",
      "isBlocked" => false,
      "lastConnectionStateChange" => "2024-06-23T03:59:52Z",
      "latestBackupTime" => "2024-06-22T11:55:10Z",
      "owner" => true,
      "registrationTime" => "2024-04-17T07:27:14Z",
      "reportedState" => [...], // Replace [...] with actual data structure
      "type" => "console",
      "userData" => [...], // Replace [...] with actual data structure
    ]
  ],
  "httpStatusCode" => 200,
  "traceId" => "a7dc15e0eb4527142d7823515b15f87d"
]

通过ID获取主机

API路由

GET /ea/hosts/{id}

描述

通过ID检索特定主机的详细信息。

用法

$hostId = 'your_host_id_here';
$host = $unifiClient->hosts->get($hostId);

示例响应

[
  "data" => [
    "hardwareId" => "eae0f123-0000-5111-b111-f833f56eade5",
    "id" => "900A6F00301100000000074A6BA90000000007A3387E0000000063EC9853:123456789",
    "ipAddress" => "192.168.220.114",
    "isBlocked" => false,
    "lastConnectionStateChange" => "2024-06-23T03:59:52Z",
    "latestBackupTime" => "2024-06-22T11:55:10Z",
    "owner" => true,
    "registrationTime" => "2024-04-17T07:27:14Z",
    "reportedState" => [...], // Replace [...] with actual data structure
    "type" => "console",
    "userData" => [...], // Replace [...] with actual data structure
  ],
  "httpStatusCode" => 200,
  "traceId" => "a7dc15e0eb4527142d7823515b15f87d"
]

列出站点

API路由

GET /ea/sites

描述

列出与发起API调用的UI帐户关联的站点。

用法

$sites = $unifiClient->sites->list();

示例响应

[
  "data" => [
    [
      "hostId" => "900A6F00301100000000074A6BA90000000007A3387E0000000063EC9853:123456789",
      "isOwner" => true,
      "meta" => [
      "desc" => "Default",
      "gatewayMac" => "f4:e2:c6:c2:3f:13",
      "name" => "default",
      "timezone" => "Europe/Riga"
    ],
      "permission" => "admin",
      "siteId" => "661900ae6aec8f548d49fd54",
      "statistics" => [...], // Replace [...] with actual data structure
      "subscriptionEndTime" => "2024-06-27T13:09:46Z"
    ]
  ],
  "httpStatusCode" => 200,
  "traceId" => "a7dc15e0eb4527142d7823515b15f87d"
]

列出设备

API路由

GET /ea/devices

描述

列出与发起API调用的UI帐户关联的UniFi设备。

用法

$devices = $unifiClient->devices->list(
    ['900A6F00301100000000074A6BA90000000007A3387E0000000063EC9853:123456789', '900A6F00301100000000074A6BA90000000007A3387E0000000063EC9853:987654321'], 
    '2024-07-15T07:01:13Z'
);

参数

• hostIds[]（数组，可选）：主机ID列表。
• time（字符串，可选）：设备的最后处理时间戳。

示例响应

[
  "data" => [
    [
      "devices" => [
        [
          "adoptionTime" => null,
          "firmwareStatus" => "upToDate",
          "id" => "F4E2C6C23F13",
          "ip" => "192.168.1.226",
          "isConsole" => true,
          "isManaged" => true,
          "mac" => "F4E2C6C23F13",
          "model" => "UDM SE",
          "name" => "unifi.yourdomain.com",
          "note" => null,
          "productLine" => "network",
          "shortname" => "UDMPROSE",
          "startupTime" => "2024-06-19T13:41:43Z",
          "status" => "online",
          "uidb" => [
            "guid" => "0fd8c390-a0e8-4cb2-b93a-7b3051c83c46",
            "id" => "e85485da-54c3-4906-8f19-3cef4116ff02",
            "images" => [
              "default" => "3008400039c483c496f4ad820242c447",
              "nopadding" => "67b553529d0e523ca9dd4826076c5f3f",
              "topology" => "8371ecdda1f00f1636a2eefadf0d7d47"
            ]
          ],
          "updateAvailable" => null,
          "version" => "4.0.6"
        ]
      ],
      "hostId" => "900A6F00301100000000074A6BA90000000007A3387E0000000063EC9853:123456789",
      "hostName" => "unifi.yourdomain.com",
      "updatedAt" => "2024-07-15T07:01:13Z"
    ]
  ],
  "httpStatusCode" => 200,
  "traceId" => "a7dc15e0eb4527142d7823515b15f87d"
]

速率限制

API速率限制设置为每分钟100个请求。如果您超过此限制，服务器将返回一个状态码为 429 Too Many Requests 的响应。如果发生这种情况，客户端将抛出异常。

关于一般API支持的注意事项

在使用其他库（如cURL或Postman）遇到官方UniFi Cloud API问题时，请勿在此处打开问题。此类问题将立即关闭。请改用讨论部分。

贡献

如果您想为这个仓库做贡献，请打开一个issue并在其中包含您的代码，或者创建一个pull request。

致谢

此类基于Ubiquiti为其UniFi Cloud API提供的文档： https://developer.ui.com/unifi-api/

重要免责声明

此PHP类提供“原样”且不提供任何保证或保修。使用风险自担。作者不对使用或误用此类造成的任何损害或损失承担责任。