文档反馈
文档反馈

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)、PDF格式转码为为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
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: 027338bf05cc4a65b5d98bc9d6af80b3" -H "Nonce: 1" -H "CurTime: 1465723418" -H "CheckSum: 61bbfd88c51028a2a28b3628584e65a2abe7ae13" -d'{"docFormat":"ppt","name":"第一课时.ppt"}' https://vcloud.163.com/app/wboard/upload/init

输出1

{
    "code" : 200,
    "requestId" : "xxxx",
    "data" : {
        "docId" : 1123, //文档ID
        "token" : "UPLOAD ab1856bb39044591939d7b94e1b8e5ee:n5VKrOLVFkLM7JIBDaCyPjzVKswqfxBZak2U2fXh0xM=:eyJCdWNrZXQiOiJ2b2RrMzJ5d3hkZiIsIk9iamVjdCI6ImEzM2U1MmQ3LTUxZGMtNDZhNS1iMTFlLWFiNmMyMmJiOTk2ZC5KUEciLCJFeHBpcmVzIjoxNDY5NTg3NTc5LCJDYWxsYmFja1VybCI6Imh0dHA6Ly8xMDYuMi40NC4yNDgveGhyL3ZvZC9ub3MvY2FsbGJhY2siLCJDYWxsYmFja0JvZHkiOiJmaWxlTmFtZT10ZXN0LkpQRyZvYmplY3ROYW1lPWEzM2U1MmQ3LTUxZGMtNDZhNS1iMTFlLWFiNmMyMmJiOTk2ZC5KUEcmJChPYmplY3RTaXplKSZ1aWQ9MjQxMzMmdHlwZUlkPTAmcHJlc2V0SWQ9MCZ3YXRlcm1hcmtJZHM9bnVsbCZkZXNjcmlwdGlvbj1udWxsJnZpZGVvQ2FsbGJhY2s9bnVsbCYkKEFWaW5mby5WaWRlby5EdXJhdGlvbikmJChBVmluZm8uVmlkZW8uSGVpZ2h0KSYkKEFWaW5mby5WaWRlby5XaWR0aCkmMCYwJjAmbnVsbCZ1cGxvYWRTdGFydD0xNDY2OTk1NTc5NjU4In0=",
        "bucket" : "vodk32ywxdf",
        "objectKey" : "d37906a7-0119-4dd9-820d-4c66a71952ad.mp4"
    }
}

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 = "/Users/caojingui/Desktop/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

2.3.2 输入参数

参数 类型 必须 说明
docId Long 文档ID
transcodeFormat String 转码输出格式(jpg、png)
callbackUrl String 转码结果回调地址
userDefInfo String 回调自定义参数
picWidth Integer 目标图片宽度,默认0(随文档宽度)
picHeight Integer 目标图片高度,默认0(随文档高度)
dpi Integer 目标图片清晰度(50-300,默认100)

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: 027338bf05cc4a65b5d98bc9d6af80b3" -H "Nonce: 1" -H "CurTime: 1465723418" -H "CheckSum: 61bbfd88c51028a2a28b3628584e65a2abe7ae13" -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", // 转出目标类型
    "resultUrl": "http://nos.netease.com/doc/1029575/1/1/", // 访问地址,拼接方式:resulturl + 页码 + . + format
    // eg: http://nos.netease.com/doc/1029575/12231/3322/1.jpg  http://nos.netease.com/doc/1029575/12231/3322/2.jpg
    "type": "wboard_doc_transcode", //固定值
    "userDefInfo": "xxxx", //用户自定义信息
    "status": 40 //任务状态 40成功,20失败
}

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 String 错误信息
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 用户自定义信息

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: 027338bf05cc4a65b5d98bc9d6af80b3" -H "Nonce: 1" -H "CurTime: 1465723418" -H "CheckSum: 61bbfd88c51028a2a28b3628584e65a2abe7ae13" -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/1029575/1/1/", // 访问地址,拼接方式:resulturl + 页码 + . + format
        // eg: http://nos.netease.com/doc/1029575/12231/3322/1.jpg  http://nos.netease.com/doc/1029575/12231/3322/2.jpg
        "type": "wboard_doc_transcode", //固定值
        "userDefInfo": "xxxx", //用户自定义信息
        "status": 40 //任务状态 40成功,20失败
    }
}
×

反馈成功

非常感谢您的反馈,我们会继续努力做得更好。