README

这是一个SDK，可以用于通过StreamOne API 3.0版本与StreamOne平台进行通信。

需求

SDK需要PHP 5.4或更高版本，并且应该启用PHP fopen封装器。

安装

使用composer

安装SDK的推荐方法是使用Composer。要安装，将以下内容添加到您的composer.json文件中

{
	"require": {
		"streamone/php-sdk-v3": "~3.2"
	}
}

之后，您应该在包含composer.json文件的目录中运行Composer以更新包

php composer.phar update streamone/php-sdk-v3

手动安装

您可以使用位于Github页面顶部的“标签”按钮下载最新版本的ZIP文件。将ZIP文件的内容放在某个位置，然后您可以开始使用它。请注意，如果您使用此方法，您应该自己require SDK的文件。

用法

要使用StreamOne SDK，您首先应该设置配置，然后您可以开始与StreamOne API通信。

配置

要设置配置，您应该使用所需的配置选项初始化StreamOne\API\v3\Config

api_url（必需）：这应该是要使用的API的基础URL。例如：https://api.streamonecloud.net。
authentication_type（必需）：这应该是user或application，表示要使用的认证类型。

对于authentication_type user，需要以下内容

user_id和user_psk：这些应包含用于认证的用户ID和预共享密钥。

对于authentication_type application，需要以下内容

application_id和application_psk：这些应包含用于认证的应用程序ID和预共享密钥。

此外，还可以使用以下可选值

default_account_id（可选）：可以设置为账户ID，如果设置，则默认用于所有API操作的账户。
visible_errors（可选，默认为[2,3,4,5,7]）：要突出显示的所有错误代码的列表。所有可能的错误都在Status.php中定义。
request_factory（可选，默认为StreamOne\API\v3\RequestFactory）：用于创建请求的工厂。如果您想覆盖它，可以在这里传递一个实现了StreamOne\API\v3\RequestFactoryInterface的实例。
cache（可选，默认为StreamOne\API\v3\NoopCache）：用于请求和令牌的缓存。应该是StreamOne\API\v3\CacheInterface的实现。
request_cache（可选，默认为StreamOne\API\v3\NoopCache）：用于请求的缓存。覆盖了对cache的任何设置，并且也应该是一个实现了StreamOne\API\v3\CacheInterface的实例。
token_cache（可选，默认为StreamOne\API\v3\NoopCache）：用于令牌的缓存。覆盖了对cache的任何设置，并且也应该是一个实现了StreamOne\API\v3\CacheInterface的实例。
use_session_for_token_cache（可选，默认为true）：如果为true，则如果使用会话，将使用会话来存储令牌信息。否则，始终使用token_cache。
session_store（可选，默认为StreamOne\API\v3\PhpSessionStore）：用于存储会话信息和可选令牌信息的会话存储。

请注意，对于request_factory、cache、request_cache、token_cache和session_store，您可以传递实现所需接口的对象的实例，或者传递一个包含值的数组，其中第一个元素应该是包含命名空间的完整类名，其他参数将传递给该类的构造函数。

如果您忘记了user_psk或application_psk，您可以通过StreamOne Manager重置它。

以下是一个示例配置：

<?php

require_once('vendor/autoload.php');

use StreamOne\API\v3\Config;

$config = new Config(array(
    'api_url' => 'https://api.streamonecloud.net',
    'authentication_type' => 'user',
    'user_id' => 'abcdefghijkl',
    'user_psk' => 'abcdefghijklmnopqrstuvwxyzABCDEF',
    'default_account_id' => '',
));

平台

Platform类是执行请求的主要入口点。您在创建时传递Config，然后它可以允许您执行请求、启动新的会话或创建一个actor。

示例

<?php

require_once('vendor/autoload.php');

use StreamOne\API\v3\Config;
use StreamOne\API\v3\Platform;

$config = ... // As above

$platform = new Platform($config);

// Start a new request
$request = $platform->newRequest('api', 'info');

// Or use a session
$session = $platform->newSession(); // You can optionally pass a different session store here

// Or create an actor
$actor = $platform->newActor(); // You can pass a session here to use that session for this actor

请求

Request可用于对StreamOne API执行实际请求。它扩展了RequestBase，其中包含其他请求类应使用的代码。

可以使用请求执行以下操作：

设置账户：使用setAccount($account)为该请求使用一个账户。默认情况下，如果设置了，将使用Config中的default_account。
设置多个账户：使用setAccounts(array $accounts)为该请求设置多个账户。某些API操作允许您提供多个账户。
设置客户：使用setCustomer($customer)使用客户而不是账户进行该请求。支持多个账户或客户的API操作可以使用此功能。
使用setTimeZone(DateTimeZone $timezone)设置时区。如果没有设置，将使用当前actor的默认时区，但可能会覆盖此设置。
使用setArgument($key, $value)设置一个参数：大多数API操作允许和/或需要设置参数。使用此函数提供它们。

设置请求后，应调用execute()以实际连接到API并执行请求。之后，请求中可用以下信息：

valid()：如果且仅当API请求成功连接到API并包含有效数据时为true。
status()：API响应的状态码。通常0表示OK。
statusMessage()：API响应的（文本）状态消息。
success()：如果且仅当valid()返回true且status()返回0时为true。
header()：API响应的完整头。如果valid()返回false，则为null。
body()：API响应的完整体。如果valid()返回false，则为null。

我们提供了一个StreamOne\API\v3\RequestException类，可以在API请求失败时抛出异常。

以下是一个API请求示例：

<?php

require_once('vendor/autoload.php');

use StreamOne\API\v3\Config;
use StreamOne\API\v3\Platform;
use StreamOne\API\v3\RequestException;

$config = ... // As above
$platform = ... // As above

$request = $platform->newRequest('item', 'view');
$request
	->setArgument('itemtype', 'video')
	->setAccount('ACCOUNT')
	->execute();

if ($request->success())
{
	foreach ($request->body() as $item)
	{
		// Do something with $item
	}
}
else
{
	throw RequestException::fromRequest($request);
}

会话

注意：当认证类型设置为application时，需要会话请求。当认证类型设置为user时，不需要。

会话可以由应用程序使用，在StreamOne平台上代表用户执行API操作。

要使用会话，您需要作为应用程序进行认证（通过将authentication_type设置为application）。然后，您可以使用StreamOne\API\v3\Session类启动会话并使用该会话执行操作。

Session类提供了以下有用的方法：

isActive()：如果会话处于活动状态，即用户当前已登录，则返回true。
start($username, $password, $ip)：为具有给定用户名和密码的用户启动一个新的会话。$ip应设置为想要登录的客户端的IP地址。这确保了当有人连续多次登录失败时，API可以进行速率限制。
end()可用于结束当前活动的会话。
newRequest() 可以用于代表用户在本会话中进行请求。
getUserId() 可以用于获取当前登录用户的ID。

会话使用示例

<?php

require_once('vendor/autoload.php');

use StreamOne\API\v3\Config;
use StreamOne\API\v3\Platform;
use StreamOne\API\v3\RequestException;

$config = ... // As above
$platform = ... // As above

$session = $platform->newSession();

if (!$session->isActive())
{
	$session->start('username', 'password', '10.11.12.13');
}

$request = $session->newRequest('item', 'view');
// etc

操作者

演员对应用户或应用程序。它可以用来执行具有相同设置的多项请求，如账户和/或客户。

演员还可以用来检查给定的演员是否具有执行API操作所需的令牌。当需要时，系统将从API请求令牌，并缓存这些信息，因此不必在每次请求时都执行。将从配置中的 token_cache 使用来存储这些信息。

完整的令牌列表可以在 https://manager.streamonecloud.net/docs/api_v3/tokens 找到

演员使用示例

<?php

require_once('vendor/autoload.php');

use StreamOne\API\v3\Config;
use StreamOne\API\v3\Platform;

$config = ... // As above
$platform = ... // As above

$actor = $platform->newActor();
// or
// $session = ... // As above
// $actor = $platform->newActor($session);

$actor->setAccount('ACCOUNT');

if ($actor->hasToken('item-read'))
{
	$request = $actor->newRequest('item', 'view');
	// etc
}

其他有用类

StreamOne SDK中还有更多类可用

FileCache、MemCache、MemoryCache、NoopCache 和 SessionCache：分别将缓存存储在文件、memcached、内存、无处和当前会话中的不同缓存类。
MemorySessionStore 和 PhpSessionStore：分别将会话信息存储在内存中和PHP会话中的不同会话存储。
Password 在使用会话登录时使用，也可以在更改用户密码时使用。
PersistentActor 将所有与演员相关的信息保存在当前会话中。如果您希望您的应用程序记住演员的账户/客户设置，这将很有用。
Status 包含API可以报告的所有状态的常量。

完整示例

<?php

require_once('vendor/autoload.php');

use StreamOne\API\v3\Config;
use StreamOne\API\v3\Platform;
use StreamOne\API\v3\RequestException;

$config = new Config(array(
	'api_url' => 'https://api.streamonecloud.net',
	'authentication_type' => 'user',
	'user_id' => 'abcdefghijkl',
	'user_psk' => 'abcdefghijklmnopqrstuvwxyzABCDEF',
	'default_account_id' => '',
));

$platform = new Platform($config);

$request = $platform->newRequest('api', 'info');

$request->execute();

if ($request->success())
{
	var_dump($request->body());
}
else
{
	throw RequestException::fromRequest($request);
}

$request = $platform->newRequest('item', 'view');
$request
    ->setArgument('itemtype', 'video')
    ->setAccount('ACCOUNT')
    ->execute();

if ($request->success())
{
    var_dump($request->body());
}
else
{
    throw RequestException::fromRequest($request);
}


$actor = $platform->newActor();

$actor->setAccount('ACCOUNT');

# A full list of tokens can be found at https://manager.streamonecloud.net/docs/api_v3/tokens
if ($actor->hasToken('item-read'))
{
    $request = $actor->newRequest('item', 'view');
    // etc
}
else
{
    echo "Actor does not have access to this token";
}

许可证和版权

所有源代码均根据 MIT许可协议许可。

streamone / php-sdk-v3

维护者

详细信息