本文中含有需要您注意的重要提示信息,忽略该信息可能对您的业务造成影响,请务必仔细阅读。
智能媒体管理IMM提供文档在线预览和协作编辑功能,支持用户在不同终端通过浏览器预览及多人协作编辑存储于阿里云OSS上的Office文档。目前,存在多个版本的文档服务接口。本文阐述了从旧版(API版本为2017-09-06)迁移至新版(API版本为2020-09-30)的相关步骤。
背景信息
智能媒体管理(IMM)后续新增功能及优化将主要集中于新版,旧版将逐步下线。新版本相较于旧版提供了更多新增功能及更广泛的地域支持,为了确保您获得更优质的使用体验,建议您尽快迁移至新版。
优势对比
设置页数:新版支持设置预览文档的页数。用户可以指定预览文档的前几页,默认情况下不设限制,最大值为5000页。
设置密码:新版支持对有密码的文档进行预览或编辑。当需要预览或编辑的文档设置了密码时,您可以输入该密码以解锁文档。
文档版本管理:新版支持将编辑后的文档直接上传至OSS,并保存为新版本。默认情况下,不会上传编辑后的版本。如需进行上传,请将此参数值设置为true。
此功能需要开启OSS的版本控制功能。关于OSS版本控制功能的更多信息,请参见版本控制。
新版与旧版API对应关系说明
SDK/API版本。
旧版使用旧版SDK,API版本为2017-09-06。
新版使用新版SDK,API版本为2020-09-30。
文档在线预览和协作编辑关于新版与旧版API的对应关系,请参见下表。
功能 | 新版API | 旧版API | 说明 |
功能 | 新版API | 旧版API | 说明 |
获取预览或编辑凭证 | GenerateWebofficeToken - 获取Weboffice凭证 API版本为2020-09-30 | GetOfficePreviewURL - 获取文档预览URL API版本为2017-09-06 | 新版将获取预览凭证和编辑凭证合并为一个接口,您只需设置参数的值即可选择获取预览凭证或编辑凭证。 |
GetWebofficeURL - 获取Weboffice的访问凭证 API版本为2017-09-06 | |||
刷新预览或编辑凭证 | RefreshWebofficeToken - 刷新Weboffice凭证 API版本为2020-09-30 | RefreshOfficePreviewToken - 刷新文档预览凭证 API版本为2020-09-30 | 新版将刷新预览凭证合并为一个接口。 |
RefreshWebofficeToken - 刷新Weboffice的访问凭证 API版本为2020-09-30 |
如何迁移
您可以按照以下步骤进行迁移:
创建新版项目。
调试新版同功能对应接口。
将您的业务切换到新版接口。
删除旧版本项目。
步骤一 :创建新版项目
创建新版项目之前确认是否已创建过新版项目,参考检查项目新旧版本,新版项目存在则无需创建。
登录智能媒体管理控制台。
左下角提供了新旧版本的切换功能,用户可在旧版中点击以体验新版。如出现“返回旧版”的提示,请忽略该步骤。
在项目列表页面,请在页面左上角选择与旧版项目相同的地域,具体如下图所示。
在项目列表页面,单击创建项目,弹出创建项目面板,填写项目信息确认完成创建,如下图所示。
创建项目时,需选择与旧版项目相同的服务角色,并将工作流模板设置为Official:DefaultEmptyId,其余选项无需进行配置。
您也可以调用新版同功能对应接口CreateProject - 创建项目替换旧版接口PutProject - 创建一个项目来创建项目。
SDK/API版本。
新版使用新版SDK,API版本为2020-09-30。
旧版使用旧版SDK,API版本为2017-09-06。
SDK 安装命令
pip install alibabacloud_imm20200930==4.6.1
步骤二:迁移预览凭证接口
替换旧版接口GetOfficePreviewURL,调用新版同功能对应接口GenerateWebofficeToken获取文档在线预览凭证。具体操作请参见以下步骤:
GenerateWebofficeToken接口的项目名参数应使用新版本创建的项目名称。
新版本WebOffice生成预览凭证
SDK/API版本。
新版使用新版SDK,API版本为2020-09-30。
旧版使用旧版SDK,API版本为2017-09-06。
SDK 安装命令
pip install alibabacloud_imm20200930==4.6.1
替换旧版接口GetWebofficeURL,调用新版同功能对应接口GenerateWebofficeToken获取文档在线预览凭证。具体操作请参见以下步骤:
GenerateWebofficeToken接口的项目名参数应使用新版本中创建的项目名。
新版本WebOffice生成预览凭证
SDK/API版本。
新版使用新版SDK,API版本为2020-09-30。
旧版使用旧版SDK,API版本为2017-09-06。
SDK 安装命令
pip install alibabacloud_imm20200930==4.6.1
新版本预览凭证文档在线预览
旧版前端代码不需要修改,只需要接入新版本生成预览凭证业务接口即可。
获取的在线预览凭证嵌入HTML页面进行文档预览。示例代码如下:
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<title>Weboffice</title>
<meta name="viewport" content="width=device-width,initial-scale=1.0">
<style>
iframe {
width: 100%;
height: 100%;
}
</style>
</head>
<body>
<script src="https://g.alicdn.com/IMM/office-js/1.1.19/aliyun-web-office-sdk.min.js"></script>
<div id="weboffice-zone"></div>
<script>
window.onload = init;
async function init() {
// 填入Weboffice链接和预览凭证信息。
weboffice({
"AccessToken": "52bbf0b2aa584a38b9a9b43cbbcd76****",
"WebofficeURL": "https://office-cn-shanghai.imm.aliyuncs.com/office/p/e4a268d86c08b9f3748d100efb9bec2a2f2064e8?_w_tokenty****",
})
}
function weboffice(tokenInfo) {
let mount = document.getElementById('#weboffice-zone');
let ins = aliyun.config({ mount, url: tokenInfo.WebofficeURL });
ins.setToken({ token: tokenInfo.AccessToken });
}
</script>
</body>
</html>
通过浏览器打开html文件,预览界面如下:
步骤三:迁移刷新预览凭证接口
替换旧版接口RefreshOfficePreviewToken,调用新版同功能对应接口RefreshWebofficeToken刷新预览凭证。具体操作请参见以下步骤:
RefreshWebofficeToken接口的项目名称参数应使用新版本所创建的项目名称。
SDK/API版本。
新版使用新版SDK,API版本为2020-09-30。
旧版使用旧版SDK,API版本为2017-09-06。
SDK 安装命令
pip install alibabacloud_imm20200930==4.6.1
替换旧版接口RefreshWebofficeToken,调用新版同功能对应接口RefreshWebofficeToken刷新预览凭证。具体操作请参见以下步骤:
RefreshWebofficeToken接口的项目名称参数应使用新版本所创建的项目名称。
SDK/API版本。
新版使用新版SDK,API版本为2020-09-30。
旧版使用旧版SDK,API版本为2017-09-06。
SDK 安装命令
pip install alibabacloud_imm20200930==4.6.1
新版在线预览刷新预览凭证
旧版前端代码不需要修改,只需要接入新版刷新预览凭证业务接口即可。
刷新预览凭证HTML页面进行文档预览。示例代码如下:
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<title>Demo</title>
<meta name="viewport" content="width=device-width,initial-scale=1.0">
<style>
html,body{
margin:0;
height:100%;
}
#weboffice-zone{
height: 100%;
width: 100%;
}
iframe {
width: 100%;
height: 100%;
}
</style>
</head>
<body>
<script src="https://g.alicdn.com/IMM/office-js/1.1.15/aliyun-web-office-sdk.min.js"></script>
<script src="https://g.alicdn.com/code/lib/axios/0.27.2/axios.min.js"></script>
<div id="weboffice-zone"></div>
<script>
window.onload = init;
var tokenInfo;
function init() {
// 调用后端接口获取预览链接和凭证。
axios.get("https://example.developer.backend.com/GenerateWebofficeToken")
.then(r => r.data)
.then(function (data){
tokenInfo = data;
weboffice(tokenInfo);
});
}
function weboffice(tokenInfo) {
var mount = document.getElementById('weboffice-zone');
var demo = aliyun.config({
mount: mount,
url: tokenInfo.WebofficeURL,
refreshToken: refreshTokenPromise // Token过期自动刷新。
});
demo.setToken({
token: tokenInfo.AccessToken,
timeout: 25*60*1000 // Token过期时间,单位为ms。25分钟之后刷新Token。
});
}
// refreshToken方法暂不支持async/await,支持返回Promise, 或者普通对象{token,timeout}。
function refreshTokenPromise() {
return new Promise(function(resolve){
axios.get("https://example.developer.backend.com/RefreshWebofficeURLToken", tokenInfo) // 调后端接口刷新凭证。
.then(r => r.data)
.then(function(data) {
// 保存,供下次刷新使用。
tokenInfo = data
resolve({
token: tokenInfo.AccessToken,
timeout: 10*60*1000
})
})
})
}
</script>
</body>
</html>
通过浏览器打开html文件,预览界面如下:
步骤四:删除旧版项目
删除旧版项目之前,请确保业务已完全迁移到新版,旧版没有流量之后再进行删除,此操作不可恢复。
登录智能媒体管理控制台。
左下角可切换新旧版本,点击可返回旧版。
在项目列表页面中,选择旧版项目所处的地域,如下图所示。
在项目列表页面中,选择需删除的旧版项目,然后点击删除按钮,如下图所示。
点击确定完成删除操作。
新版与旧版费用对比
通常情况下,新旧版本的计费模式基本保持一致。旧版按文档打开次数进行计费,而新版则引入了按API接口调用次数计费的机制。需要注意的是,一次API调用仅限于一位用户使用,若存在重复调用,则只有最后一次调用的用户能够正常访问。
在线预览和协作编辑计费项
新旧版本下同一使用场景计费对比
版本 | 使用场景 | API | 计费 | 计费说明 |
版本 | 使用场景 | API | 计费 | 计费说明 |
旧版在线预览 | 客户线上演示文档需要一个小时,中间休息一次。 | GetWebofficeURL - 获取Weboffice的访问凭证 RefreshWebofficeToken - 刷新Weboffice的访问凭证 API版本为2017-09-06 | 旧版按文档打开次数计费,打开两次,计费DocumentWebofficePreview*2。 | |
新版在线预览 | GenerateWebofficeToken - 获取Weboffice凭证 RefreshWebofficeToken - 刷新Weboffice凭证 API版本为2020-09-30 | 新版按接口请求次数计费,调用获取凭证和刷新凭证接口,计费DocumentWebofficePreview*2 |
- 本页导读 (1)
- 背景信息
- 优势对比
- 新版与旧版API对应关系说明
- 如何迁移
- 步骤一 :创建新版项目
- 步骤二:迁移预览凭证接口
- 步骤三:迁移刷新预览凭证接口
- 步骤四:删除旧版项目
- 新版与旧版费用对比
- 在线预览和协作编辑计费项
- 新旧版本下同一使用场景计费对比