开发者指南

快速入门

  1. 新建 VodClient

    VodClient是与VOD交互的核心Class,所有VOD操作均需通过VodClient完成。

  2. 创建媒资

  3. 管理媒资。

    媒资状态请参见VOD核心概念-媒资状态

    媒资上传成功后,以 mediaId 为索引对媒资进行管理,具体请参见媒资管理

  4. 获取播放地址和播放器代码。

    媒资上传之后,开发者可以通过接口函数getPlayableUrl()getMediaPlayerCode()得到 VOD 平台生成的播放地址和Web播放器代码,从而方便地进行播放器集成。

媒资管理

创建媒资

VOD提供下述三种创建媒资的方式:

  • 方法一: 使用createMediaFromFile方法从本地上传

    代码示例:

    $fileName = "<Local_Path>";
    $createMediaFromFileResult = $vodClient->createMediaFromFile($fileName, "my demo title 1", "my demo desc 1");
    echo json_encode($createMediaFromFileResult);
    
  • 方法二: 使用createMediaFromBosObject方法从BOS(“华北-北京”区域)导入

    代码示例:

    $bucket = "<Bucket_Name>";
    $boskey = "<BOS_Key>";
    $createMediaFromBosObjectResult = $vodClient->createMediaFromBosObject($bucket, $boskey, "my demo title 2", "my demo desc 2");
    echo json_encode($createMediaFromBosObjectResult);
    
  • 方法三:申请媒资、BOS上传、处理媒资三步创建法

注意:
createMediaFromFilecreateMediaFromBosObject是SDK内部包装了vodClient和bosClient,本质上也是三步创建法。

  1. 通用申请媒资获取mediaId、BOS Bucket和BOS Key;
  2. 使用BOS上传视频文件;
  3. 通过处理媒资方法通知VOD服务文件上传完毕,VOD开始生成并处理媒资。

    代码示例:

    // Firstly, apply a media
    echo "Apply a media:\n";
    $mediaUploadInfo = $vodClient->applyMedia();
    echo json_encode($mediaUploadInfo);
    
    // You can get a response like:
    // {
    //     "mediaId": "mda-gdai0ibwh7n6mw0v",
    //     "sourceBucket": "vod-gapd2rrde9hrwq20",
    //     "sourceKey": "vod-gapd2rrde9hrwq20\/mda-gdai0ibwh7n6mw0v",
    // }
    
    // Secondly, upload your video to the key of the bucket (Beijing Region).
    // In the example, use uploadPart method.
    // You can use any method of BosClient to do it, like bosClient->copyObject, etc
    // Here is a demo for MultipartUpload demo:
    // init multi-part upload
    echo "\n\nUploading media via bosClient:\n";
    $bucket = $mediaUploadInfo->sourceBucket;
    $key =  $mediaUploadInfo->sourceKey;
    $initUploadResponse = $bosClient->initiateMultipartUpload($bucket, $key);
    $uploadId = $initUploadResponse->uploadId;
    $fileName = "C:\\Users\\zhaiyao\\Desktop\\VOD\\_resource\\video\\demo.mp4";
    // do upload part
    try {
        $offset = 0;
        $partNumber = 1;
        $partSize = BosClient::MIN_PART_SIZE;
        $length = $partSize;
        $partList = array();
        $bytesLeft = filesize($fileName);
    
        while ($bytesLeft > 0) {
            $length = ($length > $bytesLeft) ? $bytesLeft : $length;
            $uploadResponse = $bosClient->uploadPartFromFile(
                $bucket,
                $key,
                $uploadId,
                $partNumber,
                $fileName,
                $offset,
                $length);
            array_push($partList, array(
                'partNumber' => $partNumber,
                'eTag' => $uploadResponse->metadata['etag'],
            ));
            $offset += $length;
            $partNumber++;
            $bytesLeft -= $length;
        }
        // complete upload
        $bosClient->completeMultipartUpload($bucket, $key, $uploadId, $partList);
    } catch (\Exception $e) {
        $bosClient->abortMultipartUpload($bucket, $key, $uploadId);
        throw $e;
    }
    
    // In the end, you must call processMedia to let vod know you've uploaded the video can vod can start handling it.
    echo "\n\nProcess the media:\n";
    $processMediaInfo = $vodClient->processMedia($mediaUploadInfo->mediaId, "my title 0", "my desc 0");
    echo json_encode($processMediaInfo);
    

说明:

  1. processMedia:在处理媒资时候,还支持extension, presetGroup, priority 这几个可选参数。不上传时表示采用系统默认值。如果需要自定义上传时,可以参考下述代码实现:

    $options = array();
    $options["sourceExtension"] = "wmv";
    $options["presetGroup"] = "defaultmp4";
    $options["priority"] = 3;
    echo json_encode($vodClient->processMedia("mda-111111111111", "php sdk test title", "test desc", $options));
    
  2. createMediaFromFilecreateMediaFromBosObject的函数原型分别如下:

    public function createMediaFromFile($fileName, $title, $description = ‘’, $options = array())
    public function createMediaFromBosObject($bucket, $key, $title, $description = ‘’, $options = array())
    

同样,也可以参照上述方法传递可选参数。

查询指定的媒资信息

通过媒资的唯一标识 mediaId 查询指定媒资的详细信息,包括:

  • 媒资状态
  • 媒资属性(媒资名称、媒资描述)
  • 媒资元数据
  • 媒资数据大小
  • 媒资时长
  • 媒资发布、创建时间

代码示例:

$response = $vodClient->getMedia("mda-gc4dxiw1gwthhunr");
echo json_encode($response);

筛选媒资并分页展示

对当前用户的媒资进行筛选,并使用分页机制显示。

代码示例:

// 根据pageNo和pageSize去查询

echo json_encode($vodClient->listMedia($pageNo, $pageSize));

// 根据pageNo、pageSize和title前缀去查询,其他参数类似,请参考API参数

$options=array();
$options[‘title’] = ‘$TITLE_PREFIX’;
echo json_encode($vodClient->listMediaByPage($pageNo, $pageSize, $options));

筛选媒资并用marker机制显示

对特定用户的所有媒资进行条件筛选并用marker机制显示。

$response = $vodClient->listMediaByMarker();
echo json_encode($response);

更新媒资的 title 和 description

通过媒资的唯一标识 mediaId 更新指定媒资的属性,包括名称和描述。

代码示例:

$response = $vodClient->updateMedia("mda-gdej4nuxiug7m0pg", "modified content", "modified content desc");
echo json_encode($response);

停用指定媒资

通过媒资的唯一标识 mediaId 停用指定媒资,仅对状态为 PUBLISHED 的媒资有效。

代码示例:

$response = $vodClient->disableMedia("mda-gdej4nuxiug7m0pg");
echo json_encode($response);

恢复指定媒资

通过媒资的唯一标识 mediaId 恢复指定媒资,仅对状态为 DISABLED 的媒资有效。

代码示例:

$response = $vodClient->publishMedia("mda-gdej4nuxiug7m0pg");
echo json_encode($response);

删除指定媒资

通过媒资的唯一标识 mediaId 删除指定媒资。删除后,媒资不可见。删除操作不可逆。

代码示例:

$response = $vodClient->deleteMedia("mda-gdej4nuxiug7m0pg");
echo json_encode($response);

查询媒资的原始视频下载地址

通过getMediaSource($mediaId, $expiredInSeconds)方法查询指定媒资的原始视频下载地址。 expiredInSeconds为该链接失效时间,整数,最长可以设置为86400。

代码示例:

vodClient->getMediaSource("mda-111111111111", 1000);

通知管理

创建通知

通过用户提供的回调地址进行创建通知。如果您在创建/申请媒资文件时指定了通知,在文件处理完成后,VOD会向您指定的回调地址推送通知消息。

$response = $vodClient->createNotification("mynotification", "http://mysite.com/notify");
echo json_encode($response);

查询指定通知

查询指定通知的详细信息。代码示例如下:

$response = $vodClient->getNotification("mynotification");
echo json_encode($response);

查询所有通知

查询已创建的全部通知。代码示例如下:

$response = $vodClient->listNotification();
echo json_encode($response);

删除通知

删除指定通知,代码示例如下:

$response = $vodClient->deleteNotification("mynotification");
echo json_encode($response);

统计分析

媒资统计

通过媒资的唯一标识 mediaId 查询指定媒资的播放信息,包括指定时间段内的播放次数、最大并发播放次数及下行流量。输入查询时间段的起止时间,按日统计,日期格式参考下述示例。

vodClient->getMediaStatistic("mda-111111111111", "2017-10-31","2017-11-01", true);

播放器管理

查询媒资播放地址

通过媒资的唯一标识 mediaId 查询指定媒资的可播放文件及媒资封面图的实际路径,用于自定义播放器的开发。

代码示例:

$response = $vodClient->getMediaDelivery("mda-gdehnybvy7mnm6sz");
 echo json_encode($response);

注意:
如果查询多模版媒资时,本方法仅能够查询出默认转码模板的转码结果。如果需要查询出所有结果,请使用“查询指定的媒资信息”方法,并按照API规范解析相关字段。

获取到媒资缩略图(cover)的实际路径后,可通过图片服务(图片样式除外)对媒资封面图进行缩放、裁剪、格式转换、旋转、添加水印等实时处理,URL格式如下所示:

# 例1:将媒资封面图(600×330)缩略成宽度为200,高度按原图比例等比例缩放
http://gcikixy9wpfkpdx3qbb.exp.bcevod.com/mda-gcseezyb93g5hqpp/mda-gcseezyb93g5hqpp.jpg@w_200

# 例2:将媒资封面图(600×330)拉伸到200×150的比例,再等比例缩放至宽200,高150
http://gcikixy9wpfkpdx3qbb.exp.bcevod.com/mda-gcseezyb93g5hqpp/mda-gcseezyb93g5hqpp.jpg@s_1,w_200,h_150

# 例3:将媒资封面图(600×330)等比例缩小330/150倍,再居中裁剪至宽200,高150
http://gcikixy9wpfkpdx3qbb.exp.bcevod.com/mda-gcseezyb93g5hqpp/mda-gcseezyb93g5hqpp.jpg@s_2,w_200,h_150

查询播放器代码

通过媒资的唯一标识 mediaId 及基本外观数据生成基础的播放器代码,便于开发者开发简单的播放器。对于高级定制需求,请根据播放器SDK自定义播放器。

函数原型:getMediaCode($mediaId, $width, $height, $autoStart, $ak)

参数说明:

参数 描述
mediaId 生成播放器代码的媒资ID
width 生成播放器的宽度
height 生成播放器的高度
autoStart 生成的播放器是否自动播放该媒资
ak 生成播放器用的ak

代码示例:

$response = $vodClient->getMediaCode("mda-gdehnybvy7mnm6sz", 720, 480, true, $ak);   
echo json_encode($response);

转码模板组管理

查询指定转码模板组

指定转码模板组名称,查询这个转码模板组的详细信息。

$response = $vodClient->getPresetGroup("presetname");   
echo json_encode($response);

查询用户所有转码模板组

查询已创建的全部转码模板组详细信息,包括系统默认和用户自定义创建的转码模板组。

$response = $vodClient->listPresetGroup();   
echo json_encode($response);

策略组管理

查询所有策略组

查询特定用户的全部策略组的详细信息。

$response = $vodClient->listStrategyGroup();   
echo json_encode($response);

查询特定策略组

查询特定策略组的详细信息。

$response = $vodClient->getStrategyGroup("Strategyname");   
echo json_encode($response);