README

注意：这是一个非常早期的版本。随着N-central更新其API以及我们对API的更好理解，它正在发生变化。有一些测试损坏并且一些代码缺失，但我们将在接下来的几周内确定这一点。

SPINEN的N-central PHP客户端

PHP包，用于与N-able的N-central服务器进行交互。我们强烈建议您审查N-central的API文档，以了解此包能做什么，因为我们只是封装了它们的API。我们基于我们的Halo PHP客户端编写了大多数代码。

我们仅在我们自己的应用程序中使用Laravel，因此这个包是用Laravel编写的。我们尝试让它在不使用Laravel的情况下工作。如果社区有要求将此包拆分为两个部分的请求，那么我们将考虑进行这项工作。

构建状态

目录

• 安装
• Laravel配置
  • 配置
• 通用PHP配置
  • 示例
• 认证
  • JWT
• 用法
  • 支持的操作
  • 使用客户端
    • 获取客户端对象
    • 模型
    • 关系
    • 集合
    • 使用“where”进行筛选
    • 搜索
    • 限制返回的记录数
    • 排序
    • 分页
  • 更多示例
• 已知问题

安装

通过Composer安装N-central PHP包

$ composer require spinen/n-central-php-rest-client

Laravel配置

1. 将适当的值添加到您的.env文件中

   密钥

   NCENTRAL_ACCESS_OVERRIDE=<Optional Override Access Token Expiration>
   NCENTRAL_JWT=<Administration → User Management → Users → Click on user → API Access → GENERATE JSON WEB TOKEN>
   NCENTRAL_REFRESH_OVERRIDE=<Optional Override Refresh Token Expiration>
   NCENTRAL_URL=<Server URL i.e. https://some.domain.tld/api/>

2. [可选] 如果您希望将客户端与您的应用程序中的每个用户的API调用一起使用，则需要让您的User对象实现包含Spinen\Ncentral\Concerns\HasNcentral特质，这将允许它像这样作为属性访问客户端：$user->ncentral

   <?php
   
   namespace App;
   
   use Illuminate\Contracts\Auth\MustVerifyEmail;
   use Illuminate\Foundation\Auth\User as Authenticatable;
   use Illuminate\Notifications\Notifiable;
   use Spinen\Ncentral\Concerns\HasNcentral;
   
   class User extends Authenticatable
   {
       use HasNcentral, Notifiable;
   
       // ...
   }

3. [可选] 发布配置和迁移

   配置

   可以通过运行...将名为ncentral.php的配置文件发布到config/

   php artisan vendor:publish --tag=ncentral-config

   迁移

   可以通过运行...发布迁移文件。

   php artisan vendor:publish --tag=ncentral-migrations

   您需要迁移来在您的User模型上设置N-central API令牌。

通用PHP配置

1. 您需要构建一个数组作为配置传递给N-central对象。您可以在configs目录中审查ncentral.php文件。该文件中记录了所有属性。

2. 根据您的需要，您可以使用N-central客户端或Builder。

   要获取用于客户端凭据的Spinen\Ncentral\Api\Client实例...

   $ psysh
   Psy Shell v0.11.22 (PHP 8.2.12 — cli) by Justin Hileman
   > $configs = [
       "jwt" => "sometoken",
       "url" => "https://some.host.tld/api",
   ]
   
   > $ncentral = new Spinen\Ncentral\Api\Client(configs: $configs);
   = Spinen\Ncentral\Api\Client {#2744}

   要获取Spinen\Ncentral\Support\Builder实例...

   $ psysh
   Psy Shell v0.11.22 (PHP 8.2.12 — cli) by Justin Hileman
   > // Get a $ncentral instance from above
   
   > $builder = (new Spinen\Ncentral\Support\Builder)->setClient($ncentral);
   = Spinen\Ncentral\Support\Builder {#2757}
   
   >

   如果使用来自user模型的ncentral属性，它将像下面所有使用$builder的示例一样工作。

认证

N-central使用JWT令牌对用户进行限制，只能进行API调用。这防止了账户直接登录到应用程序。要获取“N-central用户-API令牌（JWT）”，请访问N-central UI。然后转到管理 → 用户管理 → 用户 → 点击用户 → API访问 → 生成JSON Web Token。

用法

Spinen\Ncentral\Api\Client支持的操作

• [API尚未支持] delete(string $path) - 与request()方法一起使用，'DELETE'作为最后一个参数的快捷方式

• get(string $path) - 与request()方法一起使用，'GET'作为最后一个参数的快捷方式

• getToken() - 获取、返回或刷新令牌。

注意：这是获取令牌的最佳方式，因为它处理了过期问题

• post(string $path, array $data) - 等同于 request() 方法，最后一个参数为 'POST'

• [API 尚不支持] put(string $path, array $data) - 等同于 request() 方法，最后一个参数为 'PUT'

• refreshToken() - 刷新令牌

• request(?string $path, ?array $data = [], ?string $method = 'GET') - 使用登录用户的 JWT 对 $path 进行 API 调用，并使用 $data。

• requestToken() - 请求令牌

• setConfigs(array $configs) - 验证并设置配置

• setDebug(bool $debug) - 设置 Guzzle 进行调试

• setToken(Token|string $token) - 设置 N-central API 的令牌

• uri(?string $path = null, ?string $url = null) - 为 N-central API 的路径生成完整的 URI。

• validToken() - 令牌是否有效，如果提供了作用域，令牌是否被作用域批准

使用客户端

客户端旨在模拟 Laravel 的 Eloquent 模型。在处理 N-central 资源时，您可以像在 Laravel 中一样访问属性和关系。

模型

API 响应被转换为模型，属性的类型转换为在 N-central API 文档 中定义的类型。您可以在 src/ 文件夹中查看模型。每个模型上都有一个名为 casts 的属性，该属性指示客户端如何将 API 响应中的属性转换为类型。如果 casts 属性为空，则属性未在 API 文档中定义，因此返回一个数组。

注意：由于 N-central 正在积极开发，因此模型上的文档属性可能会过时

> $builder->customers->first()
= Spinen\Ncentral\Customer {#4967
    // properties
  }

> $builder->customers->first()->toArray()
= [
    "customerId" => 249,
    "customerName" => "Customer1",
    "isSystem" => true,
    "isServiceOrg" => true,
    "parentId" => 248,
    "city" => null,
    "stateProv" => null,
    "county" => null,
    "postalCode" => "",
    "contactEmail" => null,
  ]

关系

注意：尚未设置

一些响应包含到相关资源的链接。如果属性有关系，您可以将其作为方法调用，额外的调用将自动进行并返回。值将存储在原始数据的位置，因此一旦加载就将其缓存。

您也可以将这些关系作为属性调用，客户端将为您返回一个 Collection（就像 Eloquent 一样）。

集合

结果被包装在 Spinen\Ncentral\Support\Collection 中，该 Collection 扩展了 Illuminate\Support\Collection，因此您可以使用任何在 Laravel Collection 方法 文档中记录的集合辅助方法。

使用“where”进行筛选

您可以在模型上使用 where 进行筛选。第一个参数是要筛选的属性。第二个参数是可选的，是要筛选属性的值。如果留空，则为真，因此变为 where('<property', true)。所有这些值都通过查询字符串传递。

有几个“辅助”方法是对 where 过滤的别名，以使调用更加表达。

• whereId('<id>') 是 where('id', '<id>') 的别名
• whereNot('<property>') 是 where('<property', false) 的别名

限制返回的记录数

您可以在构建器上调用 take 或 limit 方法（take 是 limit 的别名）以限制返回的记录数到参数计数。

> $customers = $builder->customers()->take(7)->get()
= Spinen\Ncentral\Support\Collection {#4999
    all: [
      Spinen\Ncentral\Customer {#4991
        // properties
      },
      // more...
    ],
  }

> $customers->count()
= 7

分页

一些端点支持分页。您可以使用简单的分页通过将 pagination 与构建器链起来并可选地提供大小值。您可以使用 page 方法获取特定页面，该方法接受页面号作为参数。您可以通过将分页大小作为 page 方法的第二个参数传递来压缩调用。

// Could have been $builder->devices()->paginate(2)->page(2)->get()
> $devices = $builder->devices()->page(3, 2)->get()
= Spinen\Ncentral\Support\Collection {#4761
    all: [
      Spinen\Ncentral\Device {#4763
        // properties
      },
      // more...
    ],
  }

> $devices->count()
= 2

更多示例

> $builder->customers->count()
= 4

$builder->statuses->pluck('customerName', 'customerId')->sort()
= Spinen\Ncentral\Support\Collection {#4959
    all: [
      18 => "Customer A",
      17 => "Customer B",
    ],
  }

开放项

• 在模型中设置关系
• 为模型添加获取器
• 在模型上添加作用域

已知问题

• 他们正在完善 API，因此某些事情可能会中断