开发者指南

快速入门

  1. 新建 VodClient

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

  2. 创建媒资。

    点播所需的大量媒资文件须迁移到 VOD 平台。VodClient 提供了 createMediaResource() 方法用于上传音视频文件,成功后 VOD 平台将返回媒资对应的 MediaID,用于查询管理媒资的状态、获取播放地址及播放器代码。

  3. 管理媒资。

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

    媒资上传成功后,以 MediaID 为索引,开发者可以通过接口函数 getMediaResource() 查询媒资的信息和状态,并可通过函数 publishMediaResource()/stopMediaResource()/deleteMediaResource() 恢复/停用/删除媒资。

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

    媒资上传之后,开发者可以通过接口函数 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();
}

查询指定的媒资信息

通过媒资的唯一标识 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>