在业务系统中Word文档转pdf是常见的需求,Word文档格式用于业务文档的编辑过程,Pdf文档格式用于流转分发的过程,通过zOffice的Open API可以方便的把Word文档转成Pdf,同时可以确保转出的Pdf与用户在浏览器中看到的Word文件完全一致。
一、zOffice简介
zOffice提供云端Office能力,包括Word、Excel、PPT三类办公文档的在线协同编辑,通过专业级的文档能力,高效的协作体验,内容级的安全管控,丰富的集成开发接口,来赋能企业的业务系统,帮助业务系统实现文档在线预览和编辑,文档操作过程全部线上进行,完成在线办公的场景闭环。
官网链接:https://www.filez.com/zoffice
集成介绍文档: https://lenovocloud.zbox.filez.com/l/a0OsO0
二、实现过程
转Pdf API是zOffice提供的服务端Rest API,具体描述如下:
1.接口说明
POST /docs/publicapi/v1/convert
请求体
Content-Type为application/json
参数名 | 类型 | 说明 | 是否必须 |
fileUrl | string | 文件下载地址 | 是 |
filename | string | 包含后缀的文件名,Word类型支持doc/docx/wps | 是 |
targetFilename | string | 包含后缀的目标文件名,PDF后缀为pdf | 是 |
callback | string | 回调地址。任务转换结束后zOffice回调通知状态 | 是 |
- callback说明
任务转换结束后,zOffice通过callback回调通知调用方,zOffice回调时回传给三方。
2.返回结果
正常返回:
{
"taskId": "6f6598c8-c87e-420b-b6c4-6f1b187201dc",
"code": "Ok",
"detail": {
"taskStatus": "IN_QUEUE"
}
}
错误返回:
{
"taskId": "695fbf6e-90d2-42ba-83d5-00e81e5e366e",
"code": "TaskQueueCongestion",
"detail": {
"taskStatus": "FAIL"
}
}
code值是"OK",表示该转换pdf请求被zOffice正确接受,转换正在进行。转pdf结果需要等待回调通知。
3.回调通知
回调通知为三方系统实现,zOffice server在任务结束后通知三方。第三方调用文档转换请求时,需要携带了callback回调参数,zOffice在任务转换结束后会调用请求发送任务状态。
转换成功通知:
{
"taskId": "1c1cf10b-d9e6-4927-b75e-dddf6b441445",
"code": "ConvertSuccessNotify",
"detail": {
"taskStatus": "SUCCESS",
"defaultDownloadPath": "/docs/open/v1/convert/download",
"contentId": "640eeac02a9baf5dbc69d426",
"filename": "demo-docx.pdf"
}
}
转换失败通知数据:
msg中会描述任务失败原因
{
"taskId": "1c1cf10b-d9e6-4927-b75e-dddf6b441445",
"code": "ConvertFailNotify",
"detail": {
"taskStatus": "FAIL",
"msg": "conversion fotmat err",
"filename": "demo-docx.pdf"
}
}
4.结果下载
接口说明:下载转换结果
GET /docs/publicapi/v1/convert/download?taskId=xxx&contentId=xxx
请求参数
参数名 | 类型 | 说明 | 是否必须 |
taskId | string | 任务ID,对应回调响应中taskId | 是 |
contentId | string | 结果ID,对应回调响应中detail.contentId | 是 |
返回:文件流
5.认证
如果业务方能成功调用zOffice转pdf API,调用API时需要携带如下请求头
请求头 | 示例值 | 描述 |
zOffice-auth-type | s2s_MD5_sig | 固定为s2s_MD5_sig |
zOffice-message-nonce | 1f178946-397f-41a7-ae9e-fde1f40ad51a | 随机值,每次请求时随机生成 |
timeStamp | 1678618777752 | 请求时间戳,数字,自 UNIX 纪元开始(1970 年 1 月 1 日 00:00:00 (UTC))到当前时间的毫秒数 |
Authorization | repoId:appId:hash-md5(secret@@timestamp@@message-nonce@@reqBody) | 指定算法计算的token |
Authorization计算方式
public class Demo {
public static void main(String[] args) {
String timestampHeaderValue = System.currentTimeMillis() + "";
String messageNonceHeaderValue = UUID.randomUUID().toString();
String body = "请求体对应的json字符串,无请求体可忽略";
String token = getAuthToken(timestampHeaderValue, messageNonceHeaderValue, body);
String repoId = "repoId";
String appId = "appId";
token = repoId + ":" + appId + ":" + token;
System.out.println("Authorization Header value is " + token);
}
private static String getAuthToken(String timestamp, String nonce,
, String body
) {
try {
MessageDigest md5 = MessageDigest.getInstance("MD5");
String secret = "secret";
String seed = secret + "@@" + timestamp +"@@" + nonce;
if (body !== null && body.length() > 0) {
seed += "@@" + body;
}
md5.update(seed.getBytes(StandardCharsets.UTF_8));
return new BigInteger(1, md5.digest()).toString(16);
} catch (NoSuchAlgorithmException e) {
e.printStackTrace();
}
return "";
}
}
其中
- repoId是与zOffice预定好的应用系统ID。appId值为固定值publicApi。
- secret是zOffice服务和三方服务约定的密钥。
认证失败会返回状态码401及认证失败信息,例如
401 InvalidAuthTimestamp
401 InvalidAuthHeader
三、总结
使用 zOffice 提供的Word文档转pdf api,可以所见即所得的获得pdf格式文档,帮助业务系统中的文档处理流程完成闭环。
zOffice提供非常丰富的集成能力,您可以在论坛中搜索zOffice获取更多内容。相信利用zOffice,您可以更高效地生成各类业务文档,从而极大的提高您的办公自动化效率。