README

这是一个帮助开发者编写与 ViDA 交互的代码的包。

ViDA SDK 目前仍在开发中，但一旦完成，将为希望使用 ViDA API 的开发者提供一个简单的接口。

入门

以下是使用 SDK 的起点

连接到 API

有两个类用于连接到 API。第一个是 App()，可以用来执行不需要用户身份验证的请求，例如请求用户令牌。第二个是 User()，用于几乎所有其他操作。

要通过 App() 连接，创建一个新的 App() 对象，并传入 iRAP 提供给您的 App 凭证

$api = new App(
  $app_auth_id,
  $app_api_key,
  $app_private_key
);

然后您可以请求用户令牌。请参阅获取用户令牌

要通过 User() 连接，创建一个新的 User() 对象，并传入 iRAP 提供给您的 App 凭证和通过 requestUserPermissions() 获取的用户凭据（或 iRAP 提供给您的凭据）

$api = new User(
  $app_auth_id,
  $app_api_key,
  $app_private_key,
  $user_auth_id,
  $user_api_key,
  $user_private_key
);

到此为止。从此以后，SDK 将自动处理您的所有身份验证需求。

响应

对 ViDA API 的请求将通过 SDK 返回一个响应对象。响应对象的内容可能因请求而异，但通常您可以在对象中找到以下属性

/*  The response body i.e. the results
 *  that are returned
 */
$response->response;

/*  The HTTP Response code,
 *  e.g. 200 for success,
 *  401 for unauthorized
 */
$response->code;

/*  Status of the response:
 *  Success or Error
 */
$response->status;

/*  The error message, if status == 'Error'
 */
$response->error;

检查这些属性对于理解响应非常重要，例如，空响应属性可能表示错误，但也可能表示您的请求没有找到相关结果。

权限

为了访问特定的资源或方法，您的应用程序必须具有使用它的权限。权限由 iRAP 设置，基于我们认为您的应用程序需要执行的操作。

如果您尝试访问没有正确权限的资源，您将获得以下响应

$response->status = 'Error';
$response->code = 401;
$response->error = 'Authentication failure - You do not have permission to access this resource';

如果您觉得需要访问您没有权限访问的资源或方法，您可以通过 support@irap.org 邮件 iRAP 请求权限。请提供您想要实现的目标的说明。

获取用户令牌

要代表用户发出请求，需要一个用户令牌，可以使用以下请求获取

$api->requestUserPermissions($returnUrl);

这将重定向用户到 SSO 服务，成功登录并授予权限后，将重定向回指定的 $returnUrl URL，并在成功时返回以下响应

$response->userAuthId;
$response->userApiKey;
$response->userPrivateKey;

这些应该保存在您的应用程序中，用于所有未来的 API 调用，并且可以用于以下方式实例化 User 对象

$api = new User(
  $app_auth_id,
  $app_api_key,
  $app_private_key,
  $user_auth_id,
  $user_api_key,
  $user_private_key
);

访问和添加资源

访问资源可能像这样简单

$datasets = $api->getDatasets();

...而添加资源可以这样做

$response = $api->addDataset($name, 
  $project_id, 
  $manager_id,
  $country_id,
  $type,
  $assessment_date,
  $description);

如果您想访问特定的资源，应将资源 ID 传递给被调用的方法，例如

$dataset_details = $api->getDatasets(1);

...将填充 $dataset_details，以包含 id 为 1 的数据集的详细信息。使用不指定资源 ID 的 Get 方法将返回您有权访问的资源列表。

更新资源

要更新资源，您必须使用替换方法。替换方法需要提供您想要更新的资源的资源ID以及您想要更新的资源值。

所需字段因资源类型而异，例如，更新数据集的请求可能如下所示

$response = $api->replaceDataset(
  $id, 
  $name, 
  $project_id, 
  $manager_id
);

注意：所有字段都是必填的，即使您只想更改其中一个字段的值。

删除资源

要删除资源，您必须使用删除方法。删除方法需要提供您想要删除的资源的资源ID。

要删除数据集，请使用以下方法

$response = $api->deleteDataset($id);

这将删除ID为$id指定的数据集。

过滤器

默认情况下，对资源的Get方法将返回所有可供认证用户使用的可用结果。这很有用，但如果您只需要部分结果，则需要做更多的工作。

为了简化这一过程，SDK包含一个过滤器对象，允许您仅返回您正在寻找的准则。您可以在返回结果中的任何字段上使用过滤器，并使用以下任一操作

字段 = 值

字段 != 值

字段 > 值

字段 < 值

字段 >= 值

字段 <= 值

过滤器最简单的用法如下

$filter = new iRAP\VidaSDK\Filter('id', 1);

要使用过滤器，您必须将其包含在您的请求中

$result = $api->getUsers(null, $filter);

此请求将返回id字段等于1的用户。

注意：等于（=）是过滤器的默认运算符，因此无需显式包含它。

如果您想查看id不等于1的所有用户，可以这样做

$filter = new iRAP\VidaSDK\Filter('id', 1, '!=');
$result = $api->getUsers(null, $filter);

注意，!=运算符被指定为第三个参数。

多个过滤器

对单个字段进行筛选很有用，但有时您可能需要筛选多个字段。这可以通过在过滤器对象上调用addFilter()方法来完成。这是一个“AND”关系（所有准则都必须通过，而不仅仅是其中一个）。

$filter = new iRAP\VidaSDK\Filter('id', 1, '!=');
$filter->addFilter('is_admin', 1);
$result = $api->getUsers(null, $filter);

现在您正在寻找一个id不等于1且是管理员的用户。addFilter方法也将接受一个运算符参数，因此您可以在不同的字段上使用不同的运算符。与之前一样，默认的是等于（=）。您可以根据需要多次调用addFilter()方法，以创建所需的过滤器准则。

过滤器组

在某些情况下，您可能希望在替代的准则集上执行搜索，而不必运行两个单独的查询。为此，我们提供了过滤器组。这允许您传入多个过滤器对象，具有替代的搜索选项。例如

# Create the first filter for the first admins that were put into the system
$filter1 = new iRAP\VidaSDK\Filter('id', 10, '<=');
$filter1->addFilter('is_admin', 1);

# Create second filter for newer users that are not admins.
$filter2 = new iRAP\VidaSDK\Filter('id', 1000, '>');
$filter2->addFilter('is_admin', 1, '!=');

# Group the filters together
$filter = new iRAP\VidaSDK\FilterGroup(iRAP\VidaSDK\Conjunction::createOr(), $filter1, $filter2);

$result = $api->getUsers(null, $filter);

在这个例子中，如果第一个过滤器组满足条件，或者第二个过滤器组满足条件，将返回结果。注意，两个过滤器对象在一个数组中传递给FilterGroup对象。您可以根据需要包含任意多的过滤器对象。

对于真正高级的需求，您可以在过滤器组内部嵌套过滤器组，允许对结果应用高度特定的筛选。这应该能够满足几乎所有用例，但如果不是，在应用层进行筛选仍然是必要的。

可用的资源

不同资源类型的列表以及访问它们的方法可以在SDK包中的Controllers/ApiInterface.php文件中找到。随着API中提供新方法，此文件将继续添加。

要求

SDK运行的唯一要求是PHP 5.6或更高版本。