开发者指南

快速入门

  1. 新建 DocClient

    DocClient是与Document Service交互的客户端,所有Document操作都是通过DocClient完成的。请您参考新建DocClient,完成初始化客户端的操作。

  2. (可选)创建Notification(文档通知)。

    成功创建通知后,DOC会在文档转码完成后向您指定的回调地址推送消息。

  3. 创建文档。

    通过创建文档,DOC会将您的本地文档上传到百度智能云。

  4. 管理文档。

    文档状态请参见DOC核心概念-文档状态

    文档上传成功后,以 documentID 为索引,您可以通过接口函数 getDocument() 查询文档的信息和状态,并可通过函数 deleteDocument() 删除文档。

  5. 播放文档。

    文档转码成功后,您可将获取到的播放地址及相关参数集成到html/Android/iOS代码中,在各个终端实现文档播放,具体请参见:

文档处理

当您把文档文档上传到百度智能云后,DOC会存储文档、对文档进行转码并生成HTML阅读代码,方便您在多个终端进行文档在线浏览。文档状态请参见DOC核心概念-文档状态

创建文档

创建文档有两种方法:

  • 通过本地文档创建。代码示例如下:
public void createDocument(DocClient client, File file, String title, String format, String notification, String access, String targetType) {
    CreateDocumentResponse resp = client.createDocument(file, title, format, notification, access, targetType);
    System.out.println("documentId: " + resp.getDocumentId());
}
  • 通过BOS上的object创建。代码示例如下:
public void createDocument(DocClient client, String bucket_name, String object_name, String title, String format, String notification, String access, String targetType) {
    CreateDocumentResponse resp = client.createDocumentFromBos(bucket_name, object_name, title, format, notification,access, targetType);
    System.out.println("documentId: " + resp.getDocumentId());
}

注意:通过BOS创建文档存在如下限制条件:

  • 源文档所在BOS bucket所属地域必须为华北-北京(bj);百度智能云文档转码服务尚不支持根据其它地域BOS object创建文档。
  • 用户需要将源文档所在BOS bucket权限设置为公共读,或者在自定义权限设置中为百度智能云文档转码服务账号(183db8cd3d5a4bf9a94459f89a7a3a91)添加READ权限。

查询指定文档

通过文档的唯一标识 documentId 查询指定文档的详细信息。代码示例如下:

public void getDocument(DocClient client, String documentId) {
    GetDocumentResponse resp = client.getDocument(documentId);
    System.out.println("documentId: " + resp.getDocumentId());
    System.out.println("title: " + resp.getTitle());
    System.out.println("format: " + resp.getFormat());
    System.out.println("status: " + resp.getStatus()); 
    if (resp.getStatus() == "PUBLISHED") {
        System.out.println("pageCount: " + resp.getPublishInfo().getPageCount());
        System.out.println("sizeInBytes: " + resp.getPublishInfo().getSizeInBytes());
        System.out.println("coverUrl: " + resp.getPublishInfo().getCoverUrl());
        System.out.println("publishTime: " + resp.getPublishInfo().getPublishTime());
    }
    if (resp.getStatus() == "UPLOADING") {
        System.out.println("bucket: " + resp.getUploadInfo().getBucket());
        System.out.println("object: " + resp.getUploadInfo().getObject());
        System.out.println("bosEndpoint: " + resp.getPublishInfo().getBosEndpoint());
    }       
    if (resp.getStatus() == "FAILED") {
        System.out.println("errorCode: " + resp.getError().getCode());
        System.out.println("errorMessage: " + resp.getError().getMessage());
    }
    System.out.println("notification: " + resp.getNotification());
    System.out.println("createTime: " + resp.getCreateTime());
}

删除文档

通过文档的唯一标识 documentId 删除指定文档。代码示例如下:

public void deleteDocument(DocClient client, String documentId) {
    client.deleteDocument(documentId);
}

阅读文档

通过文档的唯一标识 documentId 获取指定文档的阅读信息,以便在PC/Android/iOS设备上阅读。仅对状态为PUBLISHED的文档有效。获取到阅读信息后,请根据您的设备选择相应的方式进行在线浏览:

代码示例如下:

public void readDocument(DocClient client, String documentId) {
    ReadDocumentResponse resp = client.readDocument(documentId);
    System.out.println("documentId: " + resp.getDocumentId());
    System.out.println("host: " + resp.getHost());
    System.out.println("token: " + resp.getToken());
}

文档通知

创建通知

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

public void createNotification(DocClient client, String name, String endpoint) {
    client.createNotification(name, endpoint);
}

查询指定通知

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

public void getNotification(DocClient client, String name) {
    GetNotificationResponse resp = client.getNotification(name);
    System.out.println("name: " + resp.getName());
    System.out.println("name: " + resp.getEndpoint());
}

查询所有通知

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

public void listNotifications(DocClient 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(DocClient client, String name) {
    client.deleteNotification(name);
}

文档日志

您可以直接使用SDK中支持的logback作为slf4j的实现,也可以自行选择其他框架(例如log4j)。

默认日志

若您使用默认的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}/DocumentUnitTest.%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>
      <groupId>ch.qos.logback</groupId>
      <artifactId>logback-core</artifactId>
    </exclusion>
    <exclusion>
      <groupId>org.slf4j</groupId>
      <artifactId>jcl-over-slf4j</artifactId>
    </exclusion>
  </exclusions>
</dependency>