文档转码相关接口

更新时间： 2024/08/23 16:16:33

1 接口概述

1.1 请求说明

1.1.1 服务地址

网易云信互动白板服务使用的域名访问地址为：vcloud.163.com。

1.1.2 通信协议

所有接口均通过HTTPS进行通信，提供高安全性的通信通道。

获取上传加速节点和断点续传查询断点接口除外，只支持HTTP通信。

1.1.3 请求方法

所有接口都只支持POST请求。

获取上传加速节点和断点续传查询断点接口除外，为GET请求。

1.1.4 字符编码

所有接口均使用UTF-8编码。

1.2 公共参数

所有接口均需要放置以下公共参数在请求头中，用于标识用户和接口鉴权。后续的接口说明不再对这些参数进行说明，但每次发起请求均需要携带。

参数	类型	必须	说明
AppKey	String	是	开发者平台分配的AppKey
Nonce	String	是	随机数（随机数，最大长度128个字符）
CurTime	String	是	当前UTC时间戳，从1970年1月1日0点0分0秒开始到现在的秒数
CheckSum	String	是	服务器认证需要，SHA1(AppSecret+Nonce+CurTime)，16进制字符小写

获取上传加速节点、文件数据上传、断点续传查询断点三个接口，不使用上述公共参数。

1.3 接口鉴权

接口通过请求头中的公共参数进行鉴权。登录网易云信控制台，点击应用名称 > 右侧[App Key管理]，即可查看AppKey和AppSecret，通过该安全凭证进行SHA1(AppSecret+Nonce+CurTime)计算。

本文档中提供的所有接口均面向开发者服务器端调用，用于计算CheckSum的AppSecret开发者应妥善保管,可在应用的服务器端存储和使用，但不应存储或传递到客户端，也不应在网页等前端代码中嵌入。

计算CheckSum的java代码举例如下：

import java.security.MessageDigest;
public class CheckSumBuilder {
    public static String getCheckSum(String appSecret, String nonce, String curTime) {
        return encode("sha1", appSecret + nonce + curTime);
    }
    private static String encode(String algorithm, String value) {
        if (value == null) {
            return null;
        }
        try {
            MessageDigest messageDigest = MessageDigest.getInstance(algorithm);
            messageDigest.update(value.getBytes());
            return getFormattedText(messageDigest.digest());
        } catch (Exception e) {
            throw new RuntimeException(e);
        }
    } 
    private static String getFormattedText(byte[] bytes) {
        int len = bytes.length;
        StringBuilder buf = new StringBuilder(len * 2);
        for (int j = 0; j < len; j++) {
            buf.append(HEX_DIGITS[(bytes[j] >> 4) & 0x0f]);
            buf.append(HEX_DIGITS[bytes[j] & 0x0f]);
        }
        return buf.toString();
    }
    private static final char[] HEX_DIGITS = { '0', '1', '2', '3', '4', '5', '6', '7', '8', '9', 'a', 'b', 'c', 'd', 'e', 'f' };
}

1.4 返回说明

所有接口返回类型为JSON。返回字段如下：

名称	类型	说明
code	Int	返回结果的状态码
data	String	返回的结果集
requestId	String	本次请求标识
message	String	当返回结果的状态码不为200时，包含的错误信息

获取上传加速节点、文件数据上传、断点续传查询断点三个接口除外。

2 文档转码相关接口

文档转码功能是将WORD(X)、PPT(X)、XLS(X)、PDF、TXT格式转码为H5、png及jpg格式，本页面主要说明文档转码相关的API调用和代码示例，包含文档上传、文档转码和查询结果等接口。

2.1 获取文档上传凭证

2.1.1 接口描述

域名：vcloud.163.com

接口名：/app/wboard/upload/init

用于文档上传的初始化，获取xNosToken（上传凭证）、bucket（存储对象的桶名）、object（生成的唯一对象名）。

2.1.2 输入参数

参数	类型	必须	说明
docFormat	String	是	ppt、pptx、doc、docx、pdf、xls、xlsx、txt
name	String	否	用户命名的上传文档名称

2.1.3 输出参数

参数	类型	说明
code	Int	状态码
message	String	错误信息
requestId	String	请求唯一标识
data	String	错误信息
data.docId	String	文档ID
data.token	String	上传凭证
data.bucket	String	上传桶名
data.objectKey	String	上传对象名

2.1.4 响应状态码

状态码	含义
200	操作成功
400	请求报文参数错误
500	服务器内部出现错误，请稍后重试或者将完整错误信息发送给客服人员帮忙解决
501	权限认证失败，请参考文档中的接口鉴权部分
502	服务未开通，请前往开通页面申请服务开通
429	请求的次数超过了限制

2.1.5 示例代码

输入1

curl -X POST -H "Content-Type: application/json;charset=utf-8" -H "AppKey: 027338bf05c****c9d6af80b3" -H "Nonce: 1" -H "CurTime: 14***3418" -H "CheckSum: 61bbfd88****e65a2abe7ae13" -d'{"docFormat":"ppt","name":"第一课时.ppt"}' https://vcloud.163.com/app/wboard/upload/init

输出1

{
	"code" : 200,
	"requestId" : "xxxx",
	"data" : {
		"docId" : 1123, //文档ID
		"token" : "UPLOAD ab1856bb3****7b94e1b8e5ee:n5VKrOLVFkLM7JIBDa****k2U2fXh0xM=:eyJCdWNrZXQiOiJ2b2R******WROTk1NTc5NjU4In0=",
		"bucket" : "vodk***wxdf",
		"objectKey" : "d3790***c66a71952ad.ppt"
	}
}

2.2 文档上传

通过获取到上传凭证，直传到网易NOS对象存储。

参考：直传用户指南

文档直传java代码demo如下：

import org.apache.http.Header;
import org.apache.http.HttpResponse;
import org.apache.http.client.methods.CloseableHttpResponse;
import org.apache.http.client.methods.HttpGet;
import org.apache.http.client.methods.HttpPost;
import org.apache.http.entity.ByteArrayEntity;
import org.apache.http.impl.client.CloseableHttpClient;
import org.apache.http.impl.client.HttpClients;
import org.apache.http.util.EntityUtils;

import com.alibaba.fastjson.JSON;
import com.alibaba.fastjson.JSONObject;

/**
 * 以下为示例代码
 */
public static void main(String[] args) throws IOException {
    String filePath = "/path/ppt.ppt";
    // 以下参数通过接口2.1获取
    String xNosToken = "token";
    String object = "objectKey";
    String bucket = "bucket";

    //获取上传加速节点地址
    String hostUrl = "http://wanproxy.127.net/lbs?version=1.0&bucketname=" + bucket;
    HttpGet get = new HttpGet(hostUrl);
    CloseableHttpClient client = HttpClients.createDefault();
    CloseableHttpResponse response = client.execute(get);
    String resultStr = EntityUtils.toString(response.getEntity(), "utf-8");
    System.out.println(resultStr);
    json = JSON.parseObject(resultStr);
    String host = json.getJSONArray("upload").getString(0);
    System.out.println(host);

    // 上传
    File file = new File(filePath);
    String context = null;
    InputStream in = new FileInputStream(file);
    long size = file.length();
    long offset = 0;
    while (size > 0) {
        int upsize = (int) Math.min(size, 1024 * 1024 * 4);
        String url = host + "/" + bucket + "/" + object + "?offset=" + offset;
        size = size - upsize;
        offset = offset + upsize;
        url += "&complete=" + (size == 0 ? "true" : "false") + "&version=1.0";
        if (context != null) {
            url += "&context=" + context;
        }
        byte[] buffer = new byte[upsize];
        in.read(buffer);

        ByteArrayEntity arrayEntity = new ByteArrayEntity(buffer);
        HttpPost httpPost = new HttpPost(url);
        httpPost.addHeader("x-nos-token", xNosToken);
        httpPost.setEntity(arrayEntity);
        HttpResponse resp = client.execute(httpPost);
        String str = EntityUtils.toString(resp.getEntity(), "utf-8");
        System.out.println(str);
        JSONObject js = JSON.parseObject(str);

        if (context == null) {
            context = js.getString("context");
        }
    }

    // release client and response
}

2.3 提交文档转码

文档上传完成之后，通过接口2.1获取的docId发起文档转码。转码为异步任务，任务结束支持主动回调

2.3.1 接口描述

域名：vcloud.163.com

接口名：/app/wboard/transcode/commit

h5格式仅支持ppt及pptx转码
对于word转图片，建议优先导出为pdf再转图片,以防部分元素样式兼容问题

2.3.2 输入参数

参数	类型	必须	说明
docId	Long	是	文档ID
transcodeFormat	String	是	转码输出格式(jpg、png、h5)
callbackUrl	String	否	转码结果回调地址
userDefInfo	String	否	回调自定义参数
picWidth	Integer	否	目标图片宽度，默认0(随文档宽度)
picHeight	Integer	否	目标图片高度，默认0(随文档高度)
dpi	Integer	否	目标图片清晰度(50-300，默认100)
thumbnail	Boolean	否	是否需要生成缩略图,仅ppt转h5有效(默认false)
thumbnailWidth	Integer	否	生成缩略图宽度(默认200,最大500)

2.3.3 输出参数

参数	类型	说明
code	Int	状态码
message	String	错误信息
requestId	String	请求唯一标识
data	String	错误信息
data.docId	String	文档ID
data.taskId	String	转码任务ID

2.3.4 响应状态码

状态码	含义
200	操作成功
400	请求报文参数错误
500	服务器内部出现错误，请稍后重试或者将完整错误信息发送给客服人员帮忙解决
501	权限认证失败，请参考文档中的接口鉴权部分
502	服务未开通，请前往开通页面申请服务开通
429	请求的次数超过了限制

2.3.5 示例代码

输入1

curl -X POST -H "Content-Type: application/json;charset=utf-8" -H "AppKey: 027338b4******98bc9d6af80b3" -H "Nonce: 1" -H "CurTime: 146***418" -H "CheckSum: 61bbfd88c*******e7ae13" -d'{"docId":1123,"transcodeFormat":"jpg"}' https://vcloud.163.com/app/wboard/transcode/commit

输出1

{
	"code" : 200,
	"requestId" : "xxxx",
	"data" : {
		"docId" : 1123, //文档ID
		"taskId" : 2223 //转码任务ID
	}
}

2.3.6 结果回调

转码完成之后如果提供了callbackUrl地址，则将主动回调

回调内容示例

// http post json 
{
	"pageCount": 5, //页数
	"docId": 12231, //文档ID
	"taskId": 3322, // 转码任务ID
	"format": "jpg", // 转出目标类型
	// transcodeFormat为jpg、png时，拼接方式：resulturl + 页码 + . + format （eg: http://xxx.netease.com/doc/10***75/12231/3322/1.jpg） 
	// transcodeFormat为h5时，拼接方式：resulturl + index.json （eg: http://xxx.netease.com/doc/10***75/12231/3322/index.json）
	"resultUrl": "http://wb.vod.126.net/doc/10****75/1/1/", 
	"backupResultUrls": [ //备用访问地址列表
	    "http://wb.netease.im/doc/10****75/1/1/"
	],
	"type": "wboard_doc_transcode", //固定值
	"userDefInfo": "xxxx", //用户自定义信息
	"status": 40, //任务状态 40成功，20失败
	"thumbnailDto":{
	    "success":true,
	    "thumbnailWidth":320,
	    // 缩略图访问地址，拼接方式：thumbnailUrl + 页码 + .jpg
	    "thumbnailUrl":"https://wb.vod.126.net/doc/1029575/1652****1355/CD1rxr7R/thumbnail/",
	    "backupThumbnailUrls":[ //备用访问地址列表
	        "http://wb.vod.netease.im/doc/1029575/16528****1355/CD1rxr7R/thumbnail/"
	    ]
	}
}

2.4 转码任务查询

文档提交转码之后，可以根据taskId主动查询任务结果

2.4.1 接口描述

域名：vcloud.163.com

接口名：/app/wboard/transcode/query

2.4.2 输入参数

参数	类型	必须	说明
taskId	Long	是	任务ID

2.4.3 输出参数

参数	类型	说明
code	Int	状态码
message	String	错误信息
requestId	String	请求唯一标识
data	Object	结果信息
data.docId	String	文档ID
data.taskId	String	转码任务ID
data.status	Integer	10初始化，40成功，20失败, 30转码中
data.format	String	转出目标类型
data.pageCount	String	转出文件页数
data.resultUrl	String	访问地址前缀
data.userDefInfo	String	用户自定义信息
data.createTime	Long	转码发起时间(毫秒时间戳)
data.thumbnailDto	Object	缩略图信息
data.thumbnailDto.success	Boolean	缩略图结果，true:成功；false:失败
data.thumbnailDto.thumbnailWidth	Integer	缩略图宽度
data.thumbnailDto.thumbnailUrl	String	缩略图访问地址
data.thumbnailDto.backupThumbnailUrls	List	缩略图备用访问地址

2.4.4 响应状态码

状态码	含义
200	操作成功
400	请求报文参数错误
500	服务器内部出现错误，请稍后重试或者将完整错误信息发送给客服人员帮忙解决
501	权限认证失败，请参考文档中的接口鉴权部分
502	服务未开通，请前往开通页面申请服务开通
429	请求的次数超过了限制

2.4.5 示例代码

输入1

curl -X POST -H "Content-Type: application/json;charset=utf-8" -H "AppKey: 027338bf****d6af80b3" -H "Nonce: 1" -H "CurTime: 1465***418" -H "CheckSum: 61bbfd88c51****84e65a2abe7ae13" -d'{"taskId":1123}' https://vcloud.163.com/app/wboard/transcode/query

输出1

    {
	"code" : 200,
	"requestId" : "xxxx",
	"data" : {
		"pageCount": 5, //页数
		"docId": 12231, //文档ID
		"taskId": 3322, // 转码任务ID
		"format": "jpg", // 转出目标类型
		"resultUrl": "http://nos.netease.com/doc/10***75/1/1/", // 访问地址,拼接方式：resulturl + 页码 + . + format
		// eg: http://nos.netease.com/doc/10***75/12231/3322/1.jpg  http://nos.netease.com/doc/10**75/12231/3322/2.jpg
		"type": "wboard_doc_transcode", //固定值
		"userDefInfo": "xxxx", //用户自定义信息
		"status": 40, //任务状态 40成功，20失败
		"createTime": 1641382440000, //转码发起时间
		"thumbnailDto" : {
			"success":true,
			"thumbnailWidth":320,
			// 缩略图访问地址，拼接方式：thumbnailUrl + 页码 + .jpg
			"thumbnailUrl":"https://wb.vod.126.net/doc/1029575/1652****1355/CD1rxr7R/thumbnail/",
			"backupThumbnailUrls":[ //备用访问地址列表
			    "http://wb.vod.netease.im/doc/1029575/16528****1355/CD1rxr7R/thumbnail/"
			]
		}
	}
}

2.5 文档信息查询

文档上传之后，可以根据docId查询上传的文档信息

2.5.1 接口描述

域名：vcloud.163.com

接口名：/app/wboard/doc/get

2.5.2 输入参数

参数	类型	必须	说明
docId	Long	是	文档ID(接口2.1获取的docId)

2.5.3 输出参数

参数	类型	说明
code	Int	状态码
message	String	错误信息
requestId	String	请求唯一标识
data	String	错误信息
data.id	Long	文档ID
data.docUrl	String	文档url地址
data.format	String	文档类型
data.name	String	文档名称
data.fileSize	Long	文档大小

2.5.4 响应状态码

状态码	含义
200	操作成功
400	请求报文参数错误
500	服务器内部出现错误，请稍后重试或者将完整错误信息发送给客服人员帮忙解决
501	权限认证失败，请参考文档中的接口鉴权部分
502	服务未开通，请前往开通页面申请服务开通
429	请求的次数超过了限制

2.5.5 示例代码

输入1

curl -X POST -H "Content-Type: application/json;charset=utf-8" -H "AppKey: 027338b****c9d6af80b3" -H "Nonce: 1" -H "CurTime: 14***3418" -H "CheckSum: 61bbfd88c****65a2abe7ae13" -d'{"docId":1123}' https://vcloud.163.com/app/wboard/doc/get

输出1

{
	"code" : 200,
	"requestId" : "xxxx",
	"data" : {
		"id": 12231,
		"format": "jpg", 
		"docUrl": "http://nos.netease.com/doc/10***575/1/xx.ppt",
		"name": "测试ppt文档",
		"fileSize": 123444
	}
}

此文档是否对你有帮助？

有帮助

去反馈

1 接口概述
1.1 请求说明
1.1.1 服务地址
1.1.2 通信协议
1.1.3 请求方法
1.1.4 字符编码
1.2 公共参数
1.3 接口鉴权
1.4 返回说明
2 文档转码相关接口
2.1 获取文档上传凭证
2.1.1 接口描述
2.1.2 输入参数
2.1.3 输出参数
2.1.4 响应状态码
2.1.5 示例代码
2.2 文档上传
2.3 提交文档转码
2.3.1 接口描述
2.3.2 输入参数
2.3.3 输出参数
2.3.4 响应状态码
2.3.5 示例代码
2.3.6 结果回调
2.4 转码任务查询
2.4.1 接口描述
2.4.2 输入参数
2.4.3 输出参数
2.4.4 响应状态码
2.4.5 示例代码
2.5 文档信息查询
2.5.1 接口描述
2.5.2 输入参数
2.5.3 输出参数
2.5.4 响应状态码
2.5.5 示例代码