twigger/unioncloud

NUS UnionCloud平台API包装器

维护者

详细信息

github.com/bristol-su/nus-unioncloud-api-wrapper

源代码

问题

安装: 793

依赖项: 1

建议者: 0

安全性: 0

星标: 1

关注者: 2

分支: 0

开放问题: 1

v1.0.11 2022-05-25 11:43 UTC

Requires

Requires (Dev)

GPL-3.0-or-later 64b5778a8883431a724e4238ae363c2887beb169

  • Toby Twigger <tt15951.woop@bristol.ac.uk>

This package is auto-updated.

Last update: 2024-09-22 01:03:24 UTC

README

Toby Twigger (tt15951@bristol.ac.uk) 代表Bristol SU (https://www.bristolsu.org.uk).

Scrutinizer Code Quality Build Status

安装

将 twigger/unioncloud 添加到 composer.json 文件中的 require 依赖项

composer require twigger/unioncloud

需要 composer 的自动加载，并将脚本指向 UnionCloud 命名空间

use \Twigger\UnionCloud\API\UnionCloud as UnionCloudWrapper

Laravel

默认支持 Laravel

配置

发布 UnionCloud 配置

php artisan vendor:publish --provider="Twigger\UnionCloud\API"

将以下内容添加到您的 .env 文件中

AUTHENTICATOR=v0
UNIONCLOUD_BASEURL=bristol.unioncloud.org
UNIONCLOUD_V0AUTH_EMAIL=myEmail
UNIONCLOUD_V0AUTH_PASSWORD=myPassword
UNIONCLOUD_V0AUTH_APPID=appID
UNIONCLOUD_V0AUTH_APPPASSWORD=appPassword

如果您使用的是版本 1 身份验证（AWS），则需要以下内容

AUTHENTICATOR=v1
UNIONCLOUD_BASEURL=api.unioncloud.org
UNIONCLOUD_V1_ACCESS_KEY=ACCESS_KEY
UNIONCLOUD_V1_SECRET_KEY=API_SECRET
UNIONCLOUD_V1_API_KEY=APIKEY

如果您使用的是 Laravel <5.5，则还需要在 config/app.php 中的 providers 数组中注册服务提供者

Twigger\UnionCloud\API\UnionCloudServiceProvider::class

从 Laravel 服务容器解析 UnionCloud 实例

$unionCloud = resolve('Twigger\UnionCloud\API\UnionCloud');

这将使用您的身份验证参数和基本 URL 进行设置。

用法

设置

创建一个新的 UnionCloud 包装器

$unionCloud = new UnionCloudWrapper($auth);

这需要一个身份验证参数的关联数组。例如，

$auth = [
	'email'=>'tt15951@bristol.ac.uk',
	'password'=>'top_secret',
	'appID'=>'MyAppID',
	'appPassword'=>'myPass'
];

设置所有相关的全局配置值。目前这些是基本 URL 和调试选项。

  • 基本 URL 的格式是 'bristol.unioncloud.org'。
  • 调试将返回有关原始请求和响应的信息。即使在不处于调试模式时，您也可以访问元数据（例如状态代码）。
$unionCloud->setBaseURL('union.unioncloud.org') ;
$unionCloud->debug();

发出请求

发出的任何请求都采用以下格式

  • 要交互的资源
  • 请求特定的配置
  • 要执行的特定 API 调用
  • 接收数据的格式

如果您的 IDE 支持 DocBlocks，您应该有关于所有可用资源和方法的提示。

要交互的资源

这些采用资源名称的 camelCase 形式的复数形式。例如，

users()
userGroupMemberships()

将返回一个特定的请求类，其中包含该资源所有可用的方法。

请求特定的配置

这允许您更改 API 调用的具体细节。以下方法可用

setMode($mode) // Takes basic, standard or full. Defaults to full
paginate()
setPage($page)
  • setMode() 允许您更改发出请求的模式。UnionCloud 接受 basic|standard|full 作为选项。默认为 full。
  • paginate() 应用于启用分页功能。可以与 paginate() 一起使用 setPage 以检索特定的页面。然而，这很少使用，因为默认页面是 1。

特定 API 调用

您现在可以调用正确的 API 端点。请求类包含有关如何创建 API 请求的 BaseRequest 类的说明。例如，您可以在 UserRequest 类中调用 search() 函数。这需要一个搜索参数的数组。

查看您的 IDE 提示以确定您可用哪些方法。

接收响应的格式

为了使与 UnionCloud 的交互尽可能简单，您可以请求不同类型的响应类。您可能会收到以下之一

  • 请求类
    • 如果您使用 paginate() 函数，您将收到一个请求类，但是 getResponse() 函数将返回保存的响应。有关分页的更多详细信息，请参阅分页部分。
  • 响应类
    • 这是正常的响应方法。此方法返回一个包含有关请求的详细信息（例如状态码、页码等）的类。如果开启了调试，此类还将包含有关请求的信息。
    • 使用get()函数从响应类中检索数据。这将以ResourceCollection类形式给出。
  • ResourceCollection类
    • 资源集合简单地就是一组资源的集合。我们使用自定义集合类来引入用于处理响应的有用功能。
    • 例如，您可以使用first()函数获取返回的第一个资源。
  • 资源类
    • 这是存放资源数据的类。例如，有一个用户资源类，其中包含有关用户的信息。

链式调用

为了实现干净的代码，允许链式调用。以下行将搜索名为Toby的用户，并以UserResource类返回第一个用户。我们假设$unionCloud包含一个UnionCloud类，该类具有传递正确的认证参数。

$user = $unionCloud->users()->search(['forename'=>'Toby'])->get()->first();

我们还可以指定搜索模式。

$user = $unionCloud->users()->setMode('basic')->search(['forename'=>'Toby'])->get()->first();

或者，如果我们想要检查请求是否成功

if($unionCloud->users()->setMode('basic')->getByUID('1234567')->getStatusCode() === 200) {
	// Request was successful
}

使用ResourceClasses

为了使使用UnionCloud的开发更容易，我们提供数据在ResourceClass中。每个资源都有一个ResourceClass，其中可能包含与该资源交互的有助于功能的函数。例如，UserResource类可能包含一个名为isOver18()的函数，该函数将检查用户是否超过18岁。

要访问资源类中存在的变量，只需将它们视为类属性。给定$user包含一个填充的用户资源类，以下可用于查看特定用户的信息

$user->forename
$user->dob
...

类型转换

为了进一步改进工作流程，我们自动将某些参数转换为特定类型。例如，日期字段将显示为Carbon实例，名称字段将正确大写。

基本类型转换

除非您正在开发或修改Resource类，否则您无需担心手动类型转换。

在Resource类中，有一个名为$casts的变量。它定义了资源属性键，以及我们应该将其转换的格式。目前可用的选项有

  • 日期（Carbon实例）
  • 正确大小写（格式化名称）
  • AnotherResourceClass::class

AnotherResourceClass::class允许我们将特定的返回属性转换为其他Resource类。比如说，一个用户有一个返回的用户组成员资格属性，它包含一个用户组成员资格数组。我们可以指定用户组成员资格属性应该转换为用户组成员资格资源类，通过将$casts设置为以下内容。

$casts = [
	'userGroupMemberships' => UserGroupMembershipResource::class
];

我们将每个用户组成员资格传递给资源构造函数，以生成每个成员资格的资源类。

始终使用驼峰式命名法指定属性！

高级类型转换

对于某些API调用，同一数组中返回两个或多个资源。例如，以下可能返回

$event = [
	'user_uid' => 22222,
	'user_forename' => 'Toby',
	'event_id' => 3848,
	`event_name` => `Event the user 22222 set up`
];

在这种情况下，使用$customCasts数组。每个键应包含您想要创建的新属性和新资源类，用竖线分隔。值应该是一个映射数组，从当前属性到新资源属性。在上面的示例中，如果我们想要数据看起来像以下这样

	$event = [
		'setup_user' => UserResource[
			'uid' => 22222,
			'forename' => 'Toby'
		].
		'event_id' => 3848,
		'event_name' => 'Event the user 22222 set up'
	];

我们可以指定以下类型转换

$customCasts = [
	'setup_user|'.UserResource::class => [
		'user_uid' => 'uid',
		'user_forename' => 'forename'
	],
	...
];

分页

只有当API已设置以处理分页时，分页才适用。这意味着在API说明（特定请求类中的方法）中，已调用函数$this->enablePagination()。

使用此存储库的开发者还必须为每个API调用请求分页功能。这可以通过以下方式完成，例如

$users = $unionCloud->users()->paginate()->search(['forename', 'Toby'])

这将返回一个UserRequest类。

以下方法现在可用于使用

$users->getResponse(); // Get the UserResponse class for the first page
$users->getAllPages(); // Return a collection containing all users. This will iterate through pages until the final page is reached, so may take a while (although syncronous requests are coming!)
$users->next(); // Return the RequestClass containing the response to the next page.
$users->previous(); // Return the RequestClass containing the response to the previous page.

贡献

这是一个未完成的仓库，任何贡献都将受到欢迎！以下是需要完成的事物的清单。

  • 大多数请求类都需要填充其方法
  • 大多数资源类都需要填充铸造信息以及有用的资源特定功能。
  • 需要编写一个AWS认证器

仓库文档

自动生成的phpDocumentor文档可以在GitHub Pages上找到 phpDoc 文档