开发者指南
快速入门
-
VodClient是与VOD交互的核心Class,所有VOD操作均需通过VodClient完成。
-
创建媒资。
点播所需的大量媒资文件须迁移到 VOD 平台。VodClient 提供了 createMediaResource() 方法用于上传音视频文件,成功后 VOD 平台将返回媒资对应的 MediaID,用于查询管理媒资的状态、获取播放地址及播放器代码。
-
管理媒资。
媒资状态请参见VOD核心概念-媒资状态。
媒资上传成功后,以 MediaID 为索引,开发者可以通过接口函数
getMediaResource()
查询媒资的信息和状态,并可通过函数publishMediaResource()
/stopMediaResource()
/deleteMediaResource()
恢复/停用/删除媒资。 -
获取播放地址和播放器代码。
媒资上传之后,开发者可以通过接口函数
generateMediaPlayerCode()
得到 VOD 平台生成的Web播放器代码,从而方便地将视频播放集成到自己的网页中。如果在Android或者iOS移动端播放视频,开发者可以调用接口函数
generateMediaDeliveryInfo()
获取媒资的播放URL地址,使用百度智能云的 Android 或者 iOS 播放器 SDK 播放。
媒资管理
上传媒资文件
VOD 通过 createMediaResource()
上传媒资文件,包括本地文件上传、从BOS导入媒资两种方式:
本地文件上传
假设本地媒资文件由变量 File file
指定,标题和描述通过 title 和 description 设置,transcodingPresetGroupName指定转码模板组名字,下面示例代码用于通过 createMediaResource()
上传媒资文件。
代码示例:
public void createMediaResource(VodClient vodClient, String title, String description, File file, String transcodingPresetGroupName, int priority) {
CreateMediaResourceResponse response = vodClient.createMediaResource(title, description, file, transcodingPresetGroupName, priority);
String mediaId = response.getMediaId();
}
从BOS(“华北-北京”区域)导入媒资
指定BOS Bucket和BOS Key,使用BOS上传视频文件。需要说明,使用本方法需要将object授予客户账号读权限,参考设置BOS bucket权限。
代码示例:
public void createMediaResource(VodClient vodClient, String bucketName, String objectKey, String title, String description, String transcodingPresetGroupName, int priority) {
CreateMediaResourceResponse response = vodClient.createMediaResource(bucketName, objectKey, title, description, transcodingPresetGroupName, priority);
String mediaId = response.getMediaId();
}
从公网URL中导入媒资
代码示例:
public void createMediaResource(VodClient vodClient, String sourceUrl, String title, String description, String transcodingPresetGroupName, int priority) {
CreateMediaResourceResponse response = vodClient.createMediaResource(sourceUrl, title, description, transcodingPresetGroupName, priority);
String mediaId = response.getMediaId();
}
说明:
- transcodingPresetGroupName 传入null,表示默认模板组。
- priority 优先级,当用户同时提交了大量转码时,这个值用于每个用户队列的内部排序和调度参考,不做跨用户比较。合法范围为0-9,0为最低,9为最高。
- mode:以上三个方法均有一个带mode的可选参数同名函数,用户默认传null即可。mode详见API说明。
申请媒资
用于生成媒资的唯一标识mediaId、用于存储源视频文件的sourceBucket以及源媒资文件在BOS存储中的key。sourceBucket对用户开放写权限,对于用户的BOS空间不可见。
public void applyMedia(VodClient vodClient) {
GenerateMediaIdResponse Response = vodClient.applyMedia();
String mediaId = response.getMediaId();
String sourceBucket = response.getSourceBucket();
String sourceKey = response.getSourceKey();
}
VodClient还提供一个public GenerateMediaIdResponse applyMedia(String mode);
方法。一般来说,用户无需调用这个函数。mode详见API说明。
处理媒资
用于对已完成申请和视频上传的媒资进行处理。
public void processMedia(VodClient vodClient, String mediaId, String title, String description, String sourceExtension, String transcodingPresetGroupName, int priority) {
InternalCreateMediaRequest request =
new InternalCreateMediaRequest()
.withMediaId(mediaId)
.withTitle(title)
.withDescription(description)
.withSourceExtension(sourceExtension)
.withTranscodingPresetGroupName(transcodingPresetGroupName)
.withPriority(priority);
InternalCreateMediaResponse response = vodClient.processMedia(request);
String mediaId = response.getMediaId();
}
对已完成申请和视频上传的媒资进行处理时,有自定义参数。代码示例如下:
public void processMedia(VodClient vodClient, String mediaId, String title, String description, String sourceExtension, String transcodingPresetGroupName, int priority, ActionAttributes actionAttributes) {
InternalCreateMediaRequest request =
new InternalCreateMediaRequest()
.withMediaId(mediaId)
.withTitle(title)
.withDescription(description)
.withSourceExtension(sourceExtension)
.withTranscodingPresetGroupName(transcodingPresetGroupName)
.withPriority(priority)
.withActionAttributes(actionAttributes);
InternalCreateMediaResponse response = vodClient.processMedia(request);
String mediaId = response.getMediaId();
}
查询指定的媒资信息
通过媒资的唯一标识 mediaId 查询指定媒资的详细信息。代码示例如下:
public void getMediaResource(VodClient vodClient, String mediaId) {
GetMediaResourceResponse response = vodClient.getMediaResource(mediaId);
String status = response.getStatus();
String createTime = response.getCreateTime();
String publishTime = response.getPublishTime();
String title = response.getAttributes().getTitle();
String description = response. getAttributes().getDescription();
long duration = response.getMeta().getDurationInSeconds();
long size = response.getMeta().getSizeInBytes();
String transcodingPresetGroupName = response.getTranscodingPresetGroupName();
List<PlayableUrl> playableUrlList = response.getPlayableUrlList();
List<String> thumbnailList = response.getThumbnailList();
}
媒资属性见下表:
参数 | 类型 | 描述 |
---|---|---|
mediaId | String | 媒资的唯一标识,开发者可通过 mediaId 查询指定媒资的详细信息 |
status | Object | 媒资状态,可选值PROCESSING/RUNNING/FAILED/PUBLISHED/DISABLED/BANNED |
attributes | Object | 媒资属性 |
+title | String | 媒资名称,“媒资属性”的子参数 |
+description | String | 媒资描述,“媒资属性”的子参数 |
meta | Object | 媒资元数据 |
+sourceSizeInBytes | Number | 媒资源文件大小,“媒资元数据”的子参数 |
+sizeInBytes | Number | 媒资数据大小,“媒资元数据”的子参数 |
+durationInSeconds | Number | 媒资时长,“媒资元数据”的子参数 |
error | String | 错误码,“错误信息”的子参数,有效值:TRANSCODING_FAILED(转码失败)、THUMBNAIL_FAILED(缩略图失败)、MEDIA_OVERTIME(媒资处理超时) |
message | String | 错误描述,“错误信息”的子参数 |
publishTime | String | 媒资发布时间 |
createTime | String | 媒资创建时间 |
transcodingPresetGroupName | String | 使用的转码模板组名称间 |
playableUrlList | Array | 处理后可以播放的视频信息 |
+transcodingPresetName | String | 使用的转码模板名称 |
+url | String | 可以播放视频文件的地址 |
thumbnailList | Array | 缩略图文件的地址 |
查询媒资并分页显示
对特定用户的所有媒资进行条件筛选并分页显示。代码示例如下:
public void listMediaResources(VodClient vodClient) {
int pageNo = 1;
int pageSize = 20;
String status = "PUBLISHED";
Date begin = DateUtils.parseAlternateIso8601Date("2016-01-15T08:46:56Z");
Date end = DateUtils.parseAlternateIso8601Date("2016-01-18T08:46:56Z");
String title = "test";
ListMediaResourceResponse responce = vodClient.listMediaResources(pageNo, pageSize, status, begin, end, title);
for (MediaResource mediaResource : responce.getMedia()) {
String mediaId = mediaResource.getMediaId();
String status = mediaResource.getStatus();
String createTime = mediaResource.getCreateTime();
String publishTime = mediaResource.getPublishTime();
String title = mediaResource.getAttributes().getTitle();
String description = mediaResource.getAttributes().getDescription();
long duration = mediaResource.getMeta().getDurationInSeconds();
long size = mediaResource.getMeta().getSizeInBytes();
}
}
参数详情见下表:
参数 | 类型 | 描述 | 是否必须 |
---|---|---|---|
pageNo | Integer | 页数。首页为第一页,有效值:正整数 | 是 |
pageSize | Integer | 每页大小。有效值:1-1000的整数 | 是 |
status | String | 媒资状态,用于筛选处于特定状态的媒资 | 否 |
begin | Date | 媒资创建时间(createTime)上限,用于筛选创建时间等于或晚于begin的媒资 | 否 |
end | Date | 媒资创建时间(createTime)下限,用于筛选创建时间等于或早于end的媒资 | 否 |
查询媒资并用marker机制显示
对特定用户的所有媒资进行条件筛选并分页显示。代码示例如下:
public void listMediaResourcesByMarker(VodClient vodClient, String marker) {
int pageSize = 20;
String status = "PUBLISHED";
Date begin = DateUtils.parseAlternateIso8601Date("2016-01-15T08:46:56Z");
Date end = DateUtils.parseAlternateIso8601Date("2016-01-18T08:46:56Z");
String title = "test";
ListMediaResourceByMarkerResponse response = vodClient.listMediaResources(marker, pageSize, status, begin, end, title);
for (MediaResource mediaResource : response.getMedia()) {
String mediaId = mediaResource.getMediaId();
String status = mediaResource.getStatus();
String createTime = mediaResource.getCreateTime();
String publishTime = mediaResource.getPublishTime();
String title = mediaResource.getAttributes().getTitle();
String description = mediaResource.getAttributes().getDescription();
long duration = mediaResource.getMeta().getDurationInSeconds();
long size = mediaResource.getMeta().getSizeInBytes();
}
if (response.getIsTruncated()) {
marker = response.getNextMarker();
listMediaResourcesByMarker(client, marker);
}
}
参数详情见下表:
参数 | 类型 | 描述 | 是否必须 |
---|---|---|---|
marker | String | 本次请求的marker,标记查询的起始位置,是上次marker机制查询返回的nextMarker,首次查询不提供本字段 | 否 |
maxSize | Integer | 本次请求返回的任务列表的最大元素个数,有效值:[1-1000],默认值:1000 | 否 |
status | String | 媒资状态,用于筛选处于特定状态的媒资 | 否 |
begin | Date | 媒资创建时间(createTime)上限,用于筛选创建时间等于或晚于begin的媒资 | 否 |
end | Date | 媒资创建时间(createTime)下限,用于筛选创建时间等于或早于end的媒资 | 否 |
title | String | 媒资标题前缀,用于筛选标题以title开头的媒资 | 否 |
更新指定媒资
通过媒资的唯一标识 mediaId 更新指定媒资的属性,包括名称和描述。代码示例如下:
public void updateMediaResource(VodClient vodClient, String mediaId, String title, String description) {
vodClient.updateMediaResource(mediaId, title, description);
}
停用指定媒资
通过媒资的唯一标识 mediaId 停用指定媒资,仅对状态为PUBLISHED
的媒资有效。代码示例如下:
public void stopMediaResource(VodClient vodClient, String mediaId) {
vodClient.stopMediaResource(mediaId);
}
恢复指定媒资
通过媒资的唯一标识 mediaId 恢复指定媒资,仅对状态为DISABLED
的媒资有效。代码示例如下:
public void publishMediaResource(VodClient vodClient, String mediaId) {
vodClient.publishMediaResource(mediaId);
}
删除指定媒资
通过媒资的唯一标识 mediaId 删除指定媒资,对状态为RUNNING
的媒资无效。删除后,媒资不可见。删除操作不可逆。
下述示例代码用于删除指定媒资。
public void deleteMediaResource(VodClient vodClient, String mediaId) {
vodClient.deleteMediaResource(mediaId);
}
获取媒资原始视频的下载地址
用于查询指定媒资的原始视频下载地址。
public void getMediaSourceDownload (VodClient vodClient, String mediaId, long expiredInSeconds) {
GetMediaSourceDownloadResponse response = vodClient. getMediaSourceDownload (expiredInSeconds);
String url = response.getSourceUrl();
}
通知管理
创建通知
通过用户提供的回调地址进行创建通知。如果您在创建/申请媒资文件时指定了通知,在文件处理完成后,VOD会向您指定的回调地址推送通知消息。
public void createNotification(VodClient client, String name, String endpoint) {
client.createNotification(name, endpoint);
}
查询指定通知
查询指定通知的详细信息。代码示例如下:
public void getNotification(VodClient client, String name) {
GetNotificationResponse resp = client.getNotification(name);
System.out.println("name: " + resp.getName());
System.out.println("name: " + resp.getEndpoint());
}
查询所有通知
查询已创建的全部通知。代码示例如下:
public void listNotifications(VodClient client) {
ListNotificationsResponse resp = client.listNotifications();
for (Notification notification : resp.getNotifications()) {
System.out.println("name: " + notification.getName());
System.out.println("name: " + notification.getEndpoint());
}
}
删除通知
删除指定通知。代码示例如下:
public void deleteNotification(VodClient client, String name) {
client.deleteNotification(name);
}
统计分析
媒资统计
通过媒资的唯一标识 mediaId 查询指定媒资的播放信息,包括指定时间段内的播放次数、最大并发播放次数及下行流量。输入查询时间段的起止时间,按日统计,日期格式举例:2018-02-07。
public void getMediaStatisticResponse(VodClient vodClient, String mediaId, Date startTime, Date endTime, boolean aggregate) {
GetMediaStatisticResponse response = vodClient.getMediaStatistic(mediaId, startTime, endTime, aggregate);
}
播放器管理
由于 VOD 平台开发者(VOD的客户)面向的终端用户((VOD 平台开发者的客户))所使用设备中不能存储 AK/SK 对,即 VOD 平台开发者的播放器代码需要运行在匿名环境中,VOD 通过播放器服务接口向 VOD 平台开发者提供一套独立的鉴权逻辑,根据 mediaId来返回可播放的文件地址。开发者使用安全播放器时,须嵌入此处的接口逻辑,从而固定的播放器代码可以随着 VOD 系统升级而自动调整播放路径。
查询媒资分发信息
通过媒资的唯一标识 mediaId 查询指定媒资的标题、时长、可播放文件及媒资封面图的实际路径等,用于自定义播放器的开发。代码示例如下:
public void generateMediaDeliveryInfo(VodClient vodClient, String mediaId) {
GenerateMediaDeliveryInfoResponse response = vodClient.generateMediaDeliveryInfo(mediaId);
// 获取媒资对应的可播放源文件的地址
String mediaSourceUrl = response.getFile();
// 获取媒资对应的封面图片的地址
String mediaCoverPage = playableUrl.getCover();
}
分发信息见下表:
参数 | 类型 | 描述 |
---|---|---|
mediaId | String | 媒资的唯一标识,开发者可通过 mediaId 查询指定媒资的详细信息 |
file | String | 可播放文件的实际路径 |
cover | String | 媒资封面图的实际路径。获取到路径后,可通过图片服务(图片样式除外)对媒资封面图进行缩放、裁剪、格式转换、旋转、添加水印等实时处理 |
title | String | 媒体标题 |
duration | Integer | 媒资播放时长,单位:秒 |
获取到媒资缩略图(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、基本外观数据及AK生成可扩展的播放器代码,便于开发者开发简单的播放器,仅对状态为PUBLISHED
的媒资有效。开发者还可基于获取到的播放器代码继续进行高级定制。代码示例如下:
public void generateMediaPlayerCode(VodClient vodClient, String mediaId, int width, int height, boolean autoStart) {
GenerateMediaPlayerCodeResponse response = vodClient.generateMediaPlayerCode(mediaId, width, height, autoStart);
String htmlCode = “”;
String fileCode = "";
String coverFile = "";
for (PlaybackCode code : response.getCodes()) {
switch(code.getCodeType()) {
case "html":
htmlCode = code.getSourceCode();
break;
case "file":
fileCode = code.getSourceCode();
break;
case "cover":
coverFile = code.getSourceCode();
break;
}
}
}
外观数据及AK等基本信息如下:
参数 | 类型 | 描述 | 是否必须 |
---|---|---|---|
mediaId | String | 媒资的唯一标识,开发者可通过 mediaId 查询指定媒资的详细信息 | 是 |
width | Number | 播放器宽度 | 是 |
height | Number | 播放器高度 | 是 |
autostart | Boolean | 是否自动播放,可选值: true, false | 是 |
ak | String | Access Key ID,用于用户鉴权 | 是 |
日志
VOD Java SDK发布版本中增加了logback作为slf4j的实现,开发者可以直接使用。如果工程中有其他框架实现,例如log4j,也可以用来替代logback。
默认日志
如果使用默认的logback,需要配置logback.xml到classpath中。不做配置时,日志级别默认为DEBUG。
<configuration>
<property name="LOG_HOME" value="./log/"/>
<appender name="STDOUT" class="ch.qos.logback.core.ConsoleAppender">
<!-- encoders are assigned the type
ch.qos.logback.classic.encoder.PatternLayoutEncoder by default -->
<encoder>
<pattern>%d{HH:mm:ss.SSS} [%thread] %-5level %logger{36} - %msg%n</pattern>
</encoder>
</appender>
<appender name="FILE" class="ch.qos.logback.core.rolling.RollingFileAppender">
<rollingPolicy class="ch.qos.logback.core.rolling.TimeBasedRollingPolicy">
<FileNamePattern>${LOG_HOME}/VODUnitTest.%d{yyyy-MM-dd}.log</FileNamePattern>
<MaxHistory>30</MaxHistory>
</rollingPolicy>
<encoder class="ch.qos.logback.classic.encoder.PatternLayoutEncoder">
<pattern>%d{yyyy-MM-dd HH:mm:ss.SSS} [%thread] %-5level %logger{50} - %msg%n</pattern>
</encoder>
<triggeringPolicy class="ch.qos.logback.core.rolling.SizeBasedTriggeringPolicy">
<MaxFileSize>10MB</MaxFileSize>
</triggeringPolicy>
</appender>
<root level="info">
<appender-ref ref="STDOUT"/>
<appender-ref ref="FILE"/>
</root>
</configuration>
自有日志模块
如果使用自己的日志实现模块,例如项目依赖于Maven,则可以参考下面的配置到pom.xml中来去除logback。
<?xml version="1.0" encoding="utf-8"?>
<dependency>
<groupId>com.baidubce</groupId>
<artifactId>bce-java-sdk</artifactId>
<version>${bce.sdk.version}</version>
<exclusions>
<exclusion>
<groupId>ch.qos.logback</groupId>
<artifactId>logback-classic</artifactId>
</exclusion>
<exclusion>
<artifactId>logback-core</artifactId>
<groupId>ch.qos.logback</groupId>
</exclusion>
<exclusion>
<groupId>org.slf4j</groupId>
<artifactId>jcl-over-slf4j</artifactId>
</exclusion>
</exclusions>
</dependency>