开发者指南

更新时间：2022-06-02

快速入门

新建 VodClient。

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>

百度智能云

智能点播平台 VOD

智能点播平台 VOD

开发者指南

快速入门

媒资管理

上传媒资文件

申请媒资

处理媒资

查询指定的媒资信息

查询媒资并分页显示

查询媒资并用marker机制显示

更新指定媒资

停用指定媒资

恢复指定媒资

删除指定媒资

获取媒资原始视频的下载地址

通知管理

创建通知

查询指定通知

查询所有通知

删除通知

统计分析

媒资统计

播放器管理

查询媒资分发信息

查询播放器代码

日志

默认日志

自有日志模块