README

本项目为将 Brightcove 媒体 API 集成到您的应用程序提供一个起点。它提供了与 API 交互的简单方法，以及一系列的辅助函数。

兼容性说明

请注意，PHP MAPI Wrapper v2.0 不兼容 任何之前版本（当时称为 "Echove"）。类名已被更改，许多函数已被重命名，并且方法已被更新以利用 Brightcove API 的更改。

如果您需要确定已做了哪些更改的帮助，请通过电子邮件发送请求到 opensource@brightcove.com。

要求

PHP 版本 5.2 或更高版本，或者您必须有 JavaScript 对象表示法 (JSON) PECL 包。有关 JSON PECL 包的更多信息，请访问 PHP JSON 包网站。

使用缓存扩展

PHP MAPI Wrapper 包含一个缓存扩展。要使用此功能，请将文件包含在您的页面中，同时包含核心 PHP MAPI Wrapper 文件。

require('bc-mapi.php');
require('bc-mapi-cache.php');

然后，在实例化核心类之后，您可以实例化缓存扩展。

// Using flat files
$bc = new BCMAPI(API_READ_TOKEN, API_WRITE_TOKEN);
$bc_cache = new BCMAPICache('file', 600, '/var/www/myWebSite/cache/', '.cache');

// Using Memcached
$bc = new BCMAPI(API_READ_TOKEN, API_WRITE_TOKEN);
$bc_cache = new BCMAPICache('memcached', 600, 'localhost', NULL, 11211);

构造函数的参数为

[string] 要使用的缓存方法类型，可以是 'file' 或 'memcached'
[int] 缓存文件被认为是冷文件前的秒数
[string] 缓存目录（文件）或主机（memcached）的绝对路径
[string] 缓存项的文件扩展名（仅限文件）
[int] 要使用的端口（仅限 Memcached）

示例

实例化

此示例显示了如何实例化或启动 BCMAPI PHP 类。对于 Read API，第一个令牌是必需的。第二个令牌是用于 Write API 的，是可选的。

// Include the BCMAPI SDK
require('bc-mapi.php');

// Instantiate the class, passing it our Brightcove API tokens (read, then write)
$bc = new BCMAPI(
	'READ_API_TOKEN',
	'WRITE_API_TOKEN'
);

// You may optionally include the caching extension provided with BCMAPI...
require('bc-mapi-cache.php');

// Using flat files
$bc_cache = new BCMAPICache('file', 600, '/var/www/myWebSite/cache/', '.cache');

// Using Memcached
$bc_cache = new BCMAPICache('memcached', 600, 'localhost', NULL, 11211);

属性

此示例显示了如何设置和检索一些 BCMAPI 属性，这些属性可用于调试和额外的设置。

// Turn on HTTPS mode
$bc->__set('secure', TRUE);

// Make our API call
$videos = $bc->find('allVideos');

// Determine how many possible results there are
echo 'Total Videos: ' . $bc->total_count . '&lt;br /&gt;';

// Make our API call
$videos = $bc->findAll();

// Determine how many times we called the Brightcove API
echo 'API Calls: ' . $bc->__get('api_calls');

区域支持（国际化）

此示例显示了如何更改支持国际区域的 API URL。

// Change our region to Japan
$bc->__set('url_read', 'api.brightcove.co.jp/services/library?');
$bc->__set('url_write', 'api.brightcove.co.jp/services/post');

错误处理

此示例显示了如何利用 BCMAPI 内置的错误处理。

// Create a try/catch
try {
	// Make our API call
	$video = $bc->find('find_video_by_id', 123456789);
} catch(Exception $error) {
	// Handle our error
	echo $error;
	die();
}

查找查询

此示例显示了如何从 Brightcove 账户检索视频。

// Make our API call
$video = $bc->find('find_video_by_id', 123456789);

// Print the video name and ID
echo $video->name . ' (' . $video->id . ')';

查找查询 - 简写

此示例显示了您可以使用简写方法名来使代码更容易编写和阅读。

// Make our API call
$video = $bc->find('videoById', 123456789);

查找查询 - 额外参数

此示例显示了如何使用键值数组定义额外的 API 调用参数。

// Define our parameters
$params = array(
	'id' => 123456789,
	'video_fields' => 'video_id,name,shortDescription'
);

// Make our API call
$video = $bc->find('videoById', $params);

查找查询 - 真正的查找全部

Brightcove 限制了 "find_all_videos" 调用为 100 个结果，需要分页和多个 API 调用。此示例显示了如何使用 findAll() 方法自动完成此操作。 警告：请谨慎使用 * // 定义我们的参数 $params = array( 'video_fields' => 'id,name' );

// Make our API call
$videos = $bc->findAll('video', $params);

搜索查询

此示例显示了如何搜索有关 "gates" 的视频，但不是 "Bill Gates"。

// Define our parameters
$params = array(
	'video_fields' => 'id,name,shortDescription'
);

// Set our search terms
$terms = array(
	'all' => 'display_name:gates',
	'none' => 'display_name:bill'
);

// Make our API call
$videos = $bc->search('video', $terms, $params);

搜索查询（多字段搜索）

此示例显示了如何搜索标题和标签中包含 "jobs" 的视频。

// Define our parameters
$params = array(
	'video_fields' => 'id,name,shortDescription'
);

// Set our search terms
$terms = array(
	'all' => 'display_name:jobs,tag:jobs'
);

// Make our API call
$videos = $bc->search('video', $terms, $params);

创建 - 视频

本例详细说明了如何将视频上传到Brightcove账户。此代码处理来自表单传递的数据。请注意，我们将上传的电影重命名为其原始名称，而不是放置在“tmp”目录中时生成的随机字符串；这是因为tmp_name不包括文件扩展名。视频名称是必填字段。

// Create an array of meta data from our form fields
$metaData = array(
	'name' => $_POST['videoName'],
	'shortDescription' => $_POST['videoShortDescription']
);

// Move the file out of 'tmp', or rename
rename($_FILES['videoFile']['tmp_name'], '/tmp/' . $_FILES['videoFile']['name']);
$file = '/tmp/' . $_FILES['videoFile']['name'];

// Upload the video and save the video ID
$id = $bc->createMedia('video', $file, $metaData);

创建 - 图片

本例详细说明了如何将图片上传到Brightcove账户。此代码处理来自表单传递的数据。请注意，我们将上传的图片重命名为其原始名称，而不是放置在“tmp”目录中时生成的随机字符串；这是因为tmp_name不包括文件扩展名。

// Create an array of meta data from our form fields
$metaData = array(
	'type' => 'VIDEO_STILL',
	'displayName' => $_POST['imageName']
);

// Move the file out of 'tmp', or rename
rename($_FILES['bcImage']['tmp_name'], '/tmp/' . $_FILES['bcImage']['name']);
$file = '/tmp/' . $_FILES['bcImage']['name'];

// Upload the image, assign to a video, and save the image asset ID
$id = $bc->createImage('video', $file, $metaData, 123456789);

创建 - 播放列表

本例展示了如何在Brightcove账户中创建播放列表。代码处理来自表单传递的数据。名称、视频ID和播放列表类型都是必填字段。

// Take a comma-separated string of video IDs and explode into an array
$videoIds = explode(',', $_POST['playlistVideoIds']);

// Create an array of meta data from our form fields
$metaData = array(
	'name' => $_POST['playlistName'],
	'shortDescription' => $_POST['playlistShortDescription'],
	'videoIds' => $videoIds,
	'playlistType' => 'explicit'
);

// Create the playlist and save the playlist ID
$id = $bc->createPlaylist('video', $metaData);

更新 - 视频/播放列表

本例展示了如何更新视频，但相同的方法也可以用于播放列表。

// Create an array of the new meta data
$metaData = array(
	'id' => 123456789,
	'shortDescription' => 'Our new short description.'
);

// Update a video with the new meta data
$bc->update('video', $metaData);

删除 - 视频/播放列表

本例展示了如何删除视频，但相同的方法也可以用于播放列表。级联删除意味着视频也将从所有播放列表和播放器中删除。

// Delete a 'video' by ID, and cascade the deletion
$bc->delete('video', 123456789, NULL, TRUE);

状态 - 视频上传

本例展示了如何确定上传到Brightcove账户的视频的状态。

// Retrieve upload status
$status = $bc->getStatus('video', 123456789);

分享视频

本例展示了如何与另一个Brightcove账户分享视频。将返回新视频ID的列表。请注意，两个账户之间必须启用共享。

// List the accounts to share the video with
$ids = array(
	123456789
);

// Share the videos, and save the new video IDs
$new_ids = $bc->shareMedia('video', 123456789, $ids);

添加到/从播放列表中删除

本例展示了如何将资产添加到播放列表中，以及如何从播放列表中删除资产。您可以传递视频ID数组或单个视频ID。

// Add two videos to a playlist
$bc->addToPlaylist(555555555, array(123456789, 987654321));

// Remove a video from a playlist
$bc->removeFromPlaylist(555555555, 987654321);

SEF URL/时间格式化

本例展示了BCMAPI便利方法，这些方法可以将视频标题转换为搜索引擎友好格式，并将视频长度转换为格式化字符串。

// Make our API call
$video = $bc->find('videoById', 123456789);

// Print the SEF video name and formatted duration
echo 'Name: ' . $bc->sef($video->name) . '&lt;br /&gt;';
echo 'Duration:' . $bc->time($video->length) . '&lt;br /&gt;';

自动时间戳转换

为了更无缝地将Brightcove API集成到PHP中，“find_modified_videos”调用的“from_date”参数应提供自纪元（UNIX时间戳）以来的秒数，而不是自分钟以来的分钟数，如Brightcove媒体API文档所述。如果您愿意，仍然可以传递分钟数。

// Set timestamp to 7 days ago (in seconds)
$time = time() - 604800;

// Make our API call
$videos = $bc->find('modifiedVideos', $time);

// Set timestamp to 7 days ago (in minutes)
$time = floor((time() - 604800) / 60);

// Make our API call
$videos = $bc->find('modifiedVideos', $time);

标签过滤器

本例展示了如何删除不包含所列标签的任何视频。

// Make our API call
$videos = $bc->find('allVideos');

// Remove all videos without specified tags
$videos = $bc->filter($videos, 'published=true,include=true');

方法

BCMAPI

BCMAPI类的构造函数。

参数

token_read Brightcove账户的读取API令牌

默认值: NULL 类型: 字符串
token_write Brightcove账户的写入API令牌

默认值: NULL 类型: 字符串

属性

api_calls 私有 - 已处理的总API调用数

类型: 整数
media_delivery 私有 - 对于UDS资产返回哪种类型的URL

类型: 字符串
page_number 公共 - 上次返回的'page_number'的值

类型: 整数
page_size 公共 - 上次返回的'page_size'的值

类型: 整数
secure 私有 - BCMAPI是否通过HTTPS运行

类型: 布尔
show_notices 私有 - BCMAPI是否会发送错误通知

类型: 布尔
timeout_attempts 私有 - 在API超时情况下重试调用的次数

类型: 整数
timeout_delay 私有 - 重试尝试的延迟时间（秒数）

类型: 整数
timeout_retry 私有 - 是否自动重试由于API超时而失败的调用

类型: 布尔
token_read 私有 - 要使用的读取Brightcove令牌

类型: 字符串
token_write 私有 - 要写入的Brightcove令牌

类型: 字符串
total_count 公共 - 最后一次返回的'total_count'的值

类型: 整数

__set

设置BCMAPI类的属性。

参数

key 要设置的属性

类型: 字符串
value 属性的新的值

类型：混合

返回值

属性的新的值

Type:		Mixed

__get

检索BCMAPI类的属性。

参数

key 要检索的属性

类型: 字符串

返回值

属性的值

Type:		Mixed

find

格式化请求以用于任何API "Find" 方法，并检索数据。请求的调用可以写成简短版本（例如，“allVideos”或“all_videos”代替“find_all_videos”）。如果调用支持get_item_count，则默认为TRUE。

参数

call 请求的API方法

类型: 字符串
params API参数的键值数组，或匹配默认值的单个值

默认：NULL 类型：混合

返回值

包含所有API返回数据的对象

Type:		Object

findAll

在忽略分页的情况下查找账户中的所有媒体资产。此方法应谨慎使用，因为具有大量资产库的账户将需要大量的API调用。这可能会显著影响性能，并可能导致Brightcove收取额外费用。

参数

type 要检索的对象类型

默认：video 类型：字符串
params API参数的键值数组

默认：NULL 类型：数组

返回值

包含所有API返回数据的对象

Type:		Object

search

执行视频元数据的搜索

参数

type 要检索的对象类型

默认：video 类型：字符串
terms 搜索中使用的术语

默认：NULL 类型：数组
params API参数的键值数组

默认：NULL 类型：混合

返回值

包含所有API返回数据的对象

Type:		Object

createMedia

将媒体资产文件上传到Brightcove。当从上传创建资产时，建议首先将文件从PHP放置的临时目录中移动出来，并将文件重命名为原始名称。资产名称和简短描述都是必需的；如果留空，它们将使用当前的UNIX时间戳填充。某些上传设置不允许，具体取决于已设置的默认值以及上传的文件类型。设置这些参数的值不正确将触发警告。

参数

type 要上传的对象类型

默认：video 类型：字符串
file 临时文件的位置

默认值: NULL 类型: 字符串
meta 媒体资产信息

类型：数组
options 可选的上传值

默认：NULL 类型：数组

返回值

媒体资产ID

Type:		String

createPlaylist

创建播放列表。

参数

type 要创建的播放列表类型

默认：video 类型：字符串
meta 播放列表信息

类型：数组

返回值

播放列表ID

Type:		String

update

更新媒体资产。只需要传递已更改的元数据。但是，请确保包含资产ID。

参数

type 要更新的对象类型

默认：video 类型：字符串
meta 媒体资产信息

类型：数组

返回值

新的DTO

Type:		DTO

createImage

将媒体图像文件上传到Brightcove。当创建图像时，建议首先将文件从PHP放置的临时目录中移动出来，并将文件重命名为原始名称。

参数

type 为上传图像的对象类型

默认：video 类型：字符串
file 临时文件的位置

默认值: NULL 类型: 字符串
meta 图像信息

类型：数组
id 要将图像分配给其的媒体资产ID

默认：NULL 类型：整数
ref_id 要将图像分配给其的媒体资产的引用ID

默认值: NULL 类型: 字符串
resize 是否在上传时调整图像大小

默认：TRUE 类型：布尔值

返回值

图像资产

Type:		Mixed

createOverlay

将标志叠加文件上传到Brightcove。当创建标志叠加时，建议首先将文件从PHP放置的临时目录中移动出来，并将文件重命名为原始名称。

参数

file 临时文件的位置

默认值: NULL 类型: 字符串
meta 图标叠加信息

类型：数组
id 分配图标叠加的媒体资产的ID

默认：NULL 类型：整数
ref_id 分配图标叠加的媒体资产的参考ID

默认值: NULL 类型: 字符串

返回值

图标叠加资产

Type:		Mixed

deleteOverlay

删除一个图标叠加。

参数

id 媒体资产的ID

默认：NULL 类型：整数
ref_id 媒体资产的参考ID

默认值: NULL 类型: 字符串
options 可选值

默认：NULL 类型：数组

delete

删除一个媒体资产。必须传递一个ID或参考ID。

参数

type 要删除的项目类型

默认：video 类型：字符串
id 媒体资产的ID

默认：NULL 类型：整数
ref_id 媒体资产的参考ID

默认值: NULL 类型: 字符串
options 可选值

默认：NULL 类型：数组

getStatus

检索媒体资产上传的状态。

参数

type 要检查的对象类型

默认：video 类型：字符串
id 媒体资产的ID

默认值: NULL 类型: 字符串
ref_id 媒体资产的参考ID

默认：TRUE 类型：字符串

返回值

上传状态

Type:		String

shareMedia

与所选帐户共享媒体资产。两个帐户之间必须启用共享。

参数

type 要共享的对象类型

默认：video 类型：字符串
id 媒体资产的ID

类型: 整数
account_ids 帐户ID数组

类型：数组
accept 是否自动接受共享

默认：FALSE 类型：布尔值
force 是否应该覆盖现有的媒体副本

默认：FALSE 类型：布尔值

返回值

新的媒体资产ID

Type:		Array

removeFromPlaylist

从播放列表中删除资产。

参数

playlist_id 要修改的播放列表ID

类型: 整数
video_ids 要从中删除的播放列表视频ID数组

类型：数组

返回值

新的播放列表DTO

Type:		Array

addToPlaylist

将资产添加到播放列表。

参数

playlist_id 要修改的播放列表ID

类型: 整数
video_ids 要添加到播放列表的视频ID数组

类型：数组

返回值

新的播放列表DTO

Type:		Array

convertTime

将毫秒转换为格式化时间或秒。

参数

ms 媒体资产的长度（毫秒）

默认：类型：整数
seconds 是否仅返回秒

默认：FALSE 类型：布尔值

返回值

媒体资产的格式化长度或总秒数

Type:		Mixed

convertTags

将媒体资产标签数组解析为键值数组。

参数

tags 来自媒体资产DTO的标签数组

默认：类型：数组
implode 将数组返回为Brightcove格式

默认：FALSE 类型：布尔值

返回值

标签的键值数组，或逗号分隔的字符串

Type:		Mixed

tagsFilter

删除不包含适当标签的资产。

参数

videos 您希望过滤的所有资产

默认：类型：数组
tag 要过滤的标签的逗号分隔列表

默认：类型：字符串

返回值

过滤后的资产列表

Type:		Array

sef

将媒体资产名称格式化为搜索引擎友好。

参数

name 资产名称

默认：类型：字符串

返回值

搜索引擎友好的资产名称

Type:		String

BCMAPICache

BCMAPICache类的构造函数。

参数

type 要使用的缓存方法类型，'file' 或 'memcached'

默认：file 类型：字符串
time 缓存文件被视为冷文件的秒数

默认：600 类型：整数
location 缓存目录的绝对路径（文件）或主机（memcached）

默认：类型：字符串
extension 缓存项的文件扩展名（仅文件）

默认：.c 类型：字符串
port

默认：11211 类型：整数

属性

extension 公共 - 缓存项的文件扩展名（仅文件）

类型: 字符串
location 公共 - 缓存目录的绝对路径（文件）或主机（memcached）

类型: 字符串
memcached 公共 - 如果有效，则Memcached对象

类型：对象
port 公共 - 要使用的端口（仅Memcached）

类型: 整数
time 公共 - 缓存文件被视为冷文件的秒数

类型: 整数
type 公共 - 要使用的缓存方法类型，'file' 或 'memcached'

类型: 字符串

错误

BCMAPIApiError

这是BCMAPI返回的最通用的错误，因为它在API返回意外数据或错误时抛出。错误中将包含API返回的数据，以帮助您诊断问题。

BCMAPIDeprecated

请求的项目不再由Brightcove和/或BCMAPI支持。尽早停止使用此方法，因为项目可能在任何未来的版本中被移除。

BCMAPIDtoDoesNotExist

指定的资产在Brightcove系统中不存在。请确保您使用的是正确的ID。

BCMAPIIdNotProvided

方法（通常是“删除”或“分享”功能）未传递ID（通常）。包括ID参数以解决错误。

BCMAPIInvalidFileType

传递给函数的文件不受支持。尝试另一种文件类型以解决错误。

BCMAPIInvalidMethod

请求的“find”方法不受BCMAPI支持，或在Brightcove API中不存在。删除方法调用并检查BCMAPI和Brightcove API文档。

BCMAPIInvalidProperty

您尝试设置或检索的BCMAPI属性不存在。检查BCMAPI文档。

BCMAPIInvalidType

您指定的DTO类型（视频、播放列表、图像等）不允许用于该方法。检查BCMAPI和Brightcove API文档。

BCMAPISearchTermsNotProvided

请指定一个或多个搜索参数。验证您是否以数组的形式传递了参数。

BCMAPITokenError

您提供的读取或写入令牌不被Brightcove识别。验证您是否使用了正确的令牌。

BCMAPITransactionError

无法访问API，或API未返回任何数据。验证服务器已安装、启用并能够检索远程数据。验证Brightcove API目前是否可用。

brightcove / mapi

维护者

详情

README

兼容性说明

要求

使用缓存扩展

示例

实例化

属性

区域支持（国际化）

错误处理

查找查询

查找查询 - 简写

查找查询 - 额外参数

查找查询 - 真正的查找全部

搜索查询

搜索查询（多字段搜索）

创建 - 视频

创建 - 图片

创建 - 播放列表

更新 - 视频/播放列表

删除 - 视频/播放列表

状态 - 视频上传

分享视频

添加到/从播放列表中删除

SEF URL/时间格式化

自动时间戳转换

标签

标签过滤器

方法

BCMAPI

参数

属性

__set

参数

返回值

__get

参数

返回值

find

参数

返回值

findAll

参数

返回值

search

参数

返回值

createMedia

参数

返回值

createPlaylist

参数

返回值

update

参数

返回值

createImage

参数

返回值

createOverlay

参数

返回值

deleteOverlay

参数

delete

参数

getStatus

参数

返回值

shareMedia

参数

返回值

removeFromPlaylist

参数

返回值

addToPlaylist

参数

返回值