README

简介

QBank 3 API PHP包装器是一个库，使得您可以从PHP直接使用QBank 3 API变得容易。无需自己处理连接或解释结果。

安装

通过composer安装。

{
	"require": {
		"qbnk/qbank3api-phpwrapper": "dev-master"
	}
}

升级

每个主要版本都带来了向后不兼容的更改。请参阅UPGRADING.md中的具体说明。

使用方法

本文档假设您已经熟悉QBank的概念。如果您不熟悉或者需要参考，请阅读QBank知识库中的文章。知识库位于：support.qbank.se

通过创建一个新的QBankApi来实例化包装器。该QBankApi类构造函数接受三个参数，其中两个是必需的。第一个是要连接的QBank API的URL。如果QBank由QBNK托管，则QBank的域名就足够了；否则，需要API端点的完整URL。

第二个参数是一个包含所有必要信息的Credentials对象，用于对QBank进行身份验证。这些如下所示

• 客户端ID - 一个用于识别调用者的唯一ID。由QBNK发行，通常每个组织一个。
• 用户名 - QBank中用户的用户名。您连接到的内容和使用权限由它决定。
• 密码 - 用户的密码。

要获取客户端ID，请联系我们support@qbank.se

<?php

use QBNK\QBank\API\QBankApi;
use QBNK\QBank\API\Credentials;

$credentials = new Credentials('CLIENT_ID', 'myUsername', 'myPassword');
$qbankApi = new QBankApi('customer.qbank.se', $credentials);

搜索

搜索是查找QBank中的Media的关键。通常，人们至少会有一组用于列出Media的准则，但即使想要显示所有内容，搜索也是必经之路。要找到QBank中的所有Media，您将执行一个不带参数的搜索。如果没有设置过滤选项，搜索将与终端中的*通配符类似，匹配所有内容。

<?php

use QBNK\QBank\API\QBankApi;
use QBNK\QBank\API\Credentials;
use QBNK\QBank\API\Model\Search;

$credentials = new Credentials('CLIENT_ID', 'myUsername', 'myPassword');
$qbankApi = new QBankApi('customer.qbank.se', $credentials);
$results = $qbankApi->search()->search(new Search());
var_dump(count($results));	// Prints: int(50)

但我们为什么只得到了50个结果，而我们的QBank包含数千个Media呢？简单的答案是，搜索是分页的，以避免数据洪流并在合理的时间内返回结果。默认的页面大小是50。要获取多页结果，每页包含您选择的结果数量，非常简单。

<?php

use QBNK\QBank\API\QBankApi;
use QBNK\QBank\API\Credentials;
use QBNK\QBank\API\Model\Search;

$credentials = new Credentials('CLIENT_ID', 'myUsername', 'myPassword');
$qbankApi = new QBankApi('customer.qbank.se', $credentials);
$search = new Search();
$search->setLimit(10);
for ($i = 0; $i < 5; $i++) {
	$search->setOffset($i * $search->getLimit());
    $results = $qbankApi->search()->search($search);
    var_dump(count($results));
}

/* 
Prints: 
int(10)
int(10)
int(10)
int(10)
int(10)
*/

已执行搜索的结果是一个SearchResult对象。这是一个围绕Media对象数组的包装器类，但附加了一些额外信息。其中之一是非常有用的getTotalHits()方法。使用它，您可以使用合理的限制进行搜索，并仍然打印出总结果数。然后您可以根据需要编写代码来获取更多结果。

SearchResult还实现了Iterator接口，因此您可以像常规数组一样遍历它。这使得显示结果变得容易。

<?php

use QBNK\QBank\API\QBankApi;
use QBNK\QBank\API\Credentials;
use QBNK\QBank\API\Model\Search;

$credentials = new Credentials('CLIENT_ID', 'myUsername', 'myPassword');
$qbankApi = new QBankApi('customer.qbank.se', $credentials);
$results = $qbankApi->search()->search(new Search());
var_dump(count($results));	// Prints: int(50)
var_dump($results->getTotalHits()); // Prints: int(34814);
foreach ($results as $media) {	//Prints a list of 50 media id and name combinations 
    echo 'ID: '.$media->getMediaId().' Name: '.$media->getName()."\n";
}

使用准则搜索

通常我们有一些默认的准则，比如Media属于特定的Category或者可能部署到特定的站点。这可以通过向Search对象添加准则轻松完成。

<?php

use QBNK\QBank\API\QBankApi;
use QBNK\QBank\API\Credentials;
use QBNK\QBank\API\Model\Search;

$credentials = new Credentials('CLIENT_ID', 'myUsername', 'myPassword');
$qbankApi = new QBankApi('customer.qbank.se', $credentials);
$search = new Search()
    ->setCategoryIds([1, 2]);
    ->setDeploymentSiteIds([1])
;
$results = $qbankApi->search()->search($search);

您还可以根据属性进行筛选。这可以通过将PropertyCriteria添加到您的搜索对象中完成。但是，这不会获取在SearchResult中设置的属性。要获取SearchResult中Media的Property值，必须将PropertyRequest添加到Search对象中。

<?php

use QBNK\QBank\API\QBankApi;
use QBNK\QBank\API\Credentials;
use QBNK\QBank\API\Model\Search;

$credentials = new Credentials('CLIENT_ID', 'myUsername', 'myPassword');
$qbankApi = new QBankApi('customer.qbank.se', $credentials);
$search = new Search()
    ->setProperties([
    	new PropertyRequest()->setSystemName('property1'),
    	new PropertyCriteria()->setSystemName('property2')
    ])
;
$results = $qbankApi->search()->search($search);

还有许多其他筛选搜索的可能性，这只是一个演示中最常用的几种。浏览一下Search类中的设置器，应该可以很清楚地知道可以做什么。

事件

事件是向QBank报告已发生值得收集统计数据的调用，即事件。事件统计数据在QBank中显示。

要报告事件，必须获取会话ID。会话ID在一段时间内标识正在执行的用户。要获取会话ID，必须提供会话来源。会话来源标识事件的来源（例如，前端、API、应用）。要获取会话来源，请联系support@qbank.se。

<?php

use QBNK\QBank\API\QBankApi;
use QBNK\QBank\API\Credentials;
use QBNK\QBank\API\Model\Search;

$credentials = new Credentials('CLIENT_ID', 'myUsername', 'myPassword');
$qbankApi = new QBankApi('customer.qbank.se', $credentials);
$sessionId = $qbankApi->events()->session(SESSION_SOURCE_ID, 'identifierhash', '127.0.0.1', 'CustomApp/1.0', USER_ID);
$qbankApi->events()->view($sessionId, MEDIA_ID);

要报告自定义事件（未被现有方法覆盖的事件），只需使用custom()方法。这些将与其他事件一起显示在统计数据中。

<?php

use QBNK\QBank\API\QBankApi;
use QBNK\QBank\API\Credentials;
use QBNK\QBank\API\Model\Search;

$credentials = new Credentials('CLIENT_ID', 'myUsername', 'myPassword');
$qbankApi = new QBankApi('customer.qbank.se', $credentials);
$sessionId = $qbankApi->events()->session(SESSION_SOURCE_ID, 'identifierhash', '127.0.0.1', 'CustomApp/1.0', USER_ID);
$qbankApi->events()->custom($sessionId, MEDIA_ID, 'Some custom event');

还可以报告外部使用情况，例如来自CMS或其他应用。这不在统计中显示，但在QBank的媒体详情中显示。这提供了一个很好的概述，说明了媒体的使用情况。当然，如果不再使用，也可以删除使用报告。请参阅addUsage()和removeUsage()方法。