README

介绍

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

安装

通过 composer 安装。

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

用法

本文档假定您已经对 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值，必须向Search对象添加一个PropertyRequest。

<?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、app）。要获取会话源，请联系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()方法。