获取文档预览编辑凭证。
接口说明
-
请确保在使用该接口前,已充分了解智能媒体管理产品的收费方式和价格。
-
访问凭证过期时间为 30 分钟,刷新凭证过期时间为 1 天。
-
返回的过期时间为 UTC 时间,和北京时间有 8 小时的时差。
-
支持的输入文件格式:
- 文字文档(Word):doc、docx、txt、dot、wps、wpt、dotx、docm、dotm、rtf。
- 演示文档(PPT):ppt、pptx、pptm、ppsx、ppsm、pps、potx、potm、dpt、dps。
- 表格文档(Excel):et、xls、xlt、xlsx、xlsm、xltx、xltm、csv
- PDF 文档:pdf。
-
支持最大的文件 200MB。
-
支持最大的文档页数 5000 页。
-
2023-12-01 之前创建的项目,按照文档打开次数计费。当前按照 API 接口调用次数计费。如需切换成新的计费模式,创建新的项目即可,但需要注意,一次 API 调用只能给一个用户使用,若重复使用,则只有最后一个用户可以正常访问,其余用户的访问权限将被回收。
-
在与智能媒体管理相同的地域下开通 MNS 服务,创建主题和队列,并配置订阅关系,可以通过 NotifyTopicName 参数传入 MNS 主题名称来接收文件保存的消息通知。关于 MNS SDK 的更多信息,请参见接收和删除消息。 文件保存消息通知 Message 字段 JSON 格式示例请参考 WebOffice 消息通知格式。
调试
您可以在OpenAPI Explorer中直接运行该接口,免去您计算签名的困扰。运行成功后,OpenAPI Explorer可以自动生成SDK代码示例。
授权信息
下表是API对应的授权信息,可以在RAM权限策略语句的Action
元素中使用,用来给RAM用户或RAM角色授予调用此API的权限。具体说明如下:
- 操作:是指具体的权限点。
- 访问级别:是指每个操作的访问级别,取值为写入(Write)、读取(Read)或列出(List)。
- 资源类型:是指操作中支持授权的资源类型。具体说明如下:
- 对于必选的资源类型,用背景高亮的方式表示。
- 对于不支持资源级授权的操作,用
全部资源
表示。
- 条件关键字:是指云产品自身定义的条件关键字。
- 关联操作:是指成功执行操作所需要的其他权限。操作者必须同时具备关联操作的权限,操作才能成功。
操作 | 访问级别 | 资源类型 | 条件关键字 | 关联操作 |
---|---|---|---|---|
imm:GenerateWebofficeToken | none |
|
| 无 |
请求参数
名称 | 类型 | 必填 | 描述 | 示例值 |
---|---|---|---|---|
ProjectName | string | 是 | 项目名称,获取方式请参见创建项目。 | test-project |
SourceURI | string | 是 | 待预览或编辑文档的 OSS 地址。 OSS 地址规则为 | oss://test-bucket/test-object.docx |
Filename | string | 否 | 文件名称,必须包含文件扩展名。默认为参数 SourceURI 的最后一级。 支持的文件扩展名(其中 PDF 只支持预览):
| test-Object.pptx |
CachePreview | boolean | 否 | 缓存预览标识:
注意 缓存预览和非缓存预览的单价不同,详情请查看计费项说明。
注意 该参数设置后,Pemission.copy 参数不生效。 | true、false |
Referer | string | 否 | OSS 防盗链。IMM 需要从 OSS 中获取源文件,如果 OSS 进行了防盗链设置,IMM 需要将对应的头部传给 OSS 才能获取源文件。 说明
如果访问文档所在的 Bucket 设置了 Referer,请设置此参数。
| * |
UserData | string | 否 | 用户自定义信息,必须填写 Notification 参数传入 MNS 配置时才能生效,在异步消息通知中会为您返回,用于方便您系统内对消息通知进行关联处理。最大长度为 2048 字节。 | { "id": "test-id", "name": "test-name" } |
PreviewPages | long | 否 | 限制只能预览前几页,默认不限制。最大不能超过 5000 | 5 |
Password | string | 否 | 文档的打开密码。 说明
如果需要预览或编辑有密码的文档,请设置此参数。
| 123456 |
ExternalUploaded | boolean | 否 | 是否支持直接上传文档到 OSS。可取值如下:
| false |
NotifyTopicName | string | 否 | 支持将一些事件以 MNS 消息的方式通知给客户。该参数为 MNS 异步消息通知的 topic。 | test-topic |
Hidecmb | boolean | 否 | 是否隐藏工具栏,文档预览模式下支持设置此参数。可取值如下:
| false |
Permission | WebofficePermission | 否 | 用户权限信息,以 JSON 格式表示。 用户权限包括如下选项: 每个选项的类型均为 Boolean,默认值均为 false,可选值为 true 和 false。
说明
PDF 仅支持预览功能,因此必须将” Readonly“参数设置为 true。
说明
若要使用多版本功能,必须先在 OSS 中开通多版本功能,然后将 ”History“参数设置为 true。
| |
User | WebofficeUser | 否 | 用户信息。可以传业务的用户信息,WebOffice 页面会进行显示,如果不传入此字段,用户信息会默认显示为“Unknown”。 | |
Watermark | WebofficeWatermark | 否 | 水印信息。该水印在前端生成,并没有写入到源文档中,同一个文档传入不同的参数会得到不同的水印。 | |
CredentialConfig | CredentialConfig | 否 | 如无特殊需求,请保持留空即可。 链式授权配置,非必填。更多信息,请参见使用链式授权访问其他实体资源。 | |
Notification | Notification | 否 | Notification 消息通知配置,目前仅支持 MNS,异步通知消息格式请参考 WebOffice 消息通知格式。 说明
文件保存和文件重命名时会有消息通知。
|
典型场景举例
对于如下示例的参数结构,对一些经典的场景示例说明:
预览只读文件(如果是预览 pdf 文件,必须这样设置)
文档预览模式,文档只能预览不可编辑规则:
{
"ProjectName" : "test-project",
"SourceURI" : "oss://test-bucket/test-object.pdf",
"Filename" : "test-object.docx",
"PreviewPages" : "5",
"Permission" : "{'Readonly':'true'}"
}
预览文件后缀为大写的文件
预览文件后缀为大写的文件,需要设置 Filename 参数后缀为小写:
{
"ProjectName" : "test-project",
"SourceURI" : "oss://test-bucket/test-object.DOCX",
"Filename" : "test-object.docx",
"PreviewPages" : "5",
"Permission" : "{'Readonly':'true'}"
}
对指定文档只预览前 5 页
文档一共 10 页,只显示前 5 页规则:
{
"ProjectName" : "test-project",
"SourceURI" : "oss://test-bucket/test-object.docx",
"Filename" : "test-object.docx",
"PreviewPages" : "5",
"Permission" : "{'Readonly':'true'}"
}
对指定文档预览添加密码
文档预览时设置密码,或者源文件设置了密码预览时直接打开不需要密码规则:
{
"ProjectName" : "test-project",
"SourceURI" : "oss://test-bucket/test-object.docx",
"Filename" : "test-object.docx",
"Password" : "123456",
"Permission" : "{'Readonly':'true'}"
}
对指定的文档预览添加水印
文档预览时添加水印规则:
{
"ProjectName" : "test-project",
"SourceURI" : "oss://test-bucket/test-object.docx",
"Filename" : "test-object.docx",
"Watermark" : "{'Type':'1','Value':'水印值','Font':'bold 20px Serif'}",
"Permission" : "{'Readonly':'true'}"
}
对指定的文档预览时隐藏工具栏
文档预览时隐藏工具栏规则:
{
"ProjectName" : "test-project",
"SourceURI" : "oss://test-bucket/test-object.docx",
"Filename" : "test-object.docx",
"Hidecmb" : "true",
"Permission" : "{'Readonly':'true'}"
}
对指定的文档进行在线编辑,查看历史版本,拷贝,打印,导出 PDF 权限
文档在线编辑,查看历史版本,拷贝,打印,导出 PDF 权限规则:
{
"ProjectName" : "test-project",
"SourceURI" : "oss://test-bucket/test-object.docx",
"Filename" : "test-object.docx",
"Permission" : "{'Readonly':'false','History':'true','Copy':'true','Print':'true','Export':'true'}"
}
返回参数
常见错误
ProjectName 对应的项目未找到,请到新版本 IMM 控制台检查地域下该项目是否存在。
{
"Code": "ResourceNotFound",
"Message": "The specified resource acs:imm::xxx:project/xxx is not found"
}
User 参数是必填参数,请检查该参数是否填写。
{
"Code": "InvalidArgument.User",
"Message": "The parameter User is required but not provided"
}
User 参数不正确,请检查该参数值是否是正确的 JSON 格式。
{
"Code": "InvalidJSON parsing error, User",
"Message": "Specified parameter JSON parsing error, User is not valid."
}
Permission 参数不正确,请检查该参数值是否是正确的 JSON 格式。
{
"Code": "InvalidJSON parsing error, Permission",
"Message": "Specified parameter JSON parsing error, Permission is not valid."
}
Watermark 参数不正确,请检查该参数值是否是正确的 JSON 格式。
{
"Code": "InvalidJSON parsing error, Watermark",
"Message": "Specified parameter JSON parsing error, Watermark is not valid."
}
PreviewPages 参数格式不正确,请检查 PreviewPages 参数值。
{
"Code": "InvalidPreviewPages",
"Message": "Specified parameter PreviewPages is not valid."
}
SourceURI 对应的 OSS 文件不存在,请检查 Bucket 下该文件是否存在。
{
"Code": "ResourceNotFound",
"Message": "The specified resource oss://xx is not found"
}
示例
正常返回示例
JSON
格式
{
"RequestId": "1759315A-CB33-0A75-A72B-62D7********",
"WebofficeURL": "https://office-cn-shanghai.imm.aliyuncs.com/office/s/dd221b2cdb44fb66e9070d1d70a8b9bbb6d6fff7?_w_tokentype=1",
"AccessToken": "2d73dd5d87524c5e8a194c3eb5********",
"RefreshToken": "e374995ec532432bb678074d36********",
"AccessTokenExpiredTime": "2021-08-30T13:13:11.347146982Z",
"RefreshTokenExpiredTime": "2021-08-31T12:43:11.347146982Z"
}
错误码
访问错误中心查看更多错误码。
变更历史
变更时间 | 变更内容概要 | 操作 |
---|---|---|
2023-08-30 | API 内部配置变更,不影响调用 | 查看变更详情 |
2023-03-09 | OpenAPI 入参发生变更 | 查看变更详情 |
相关文档
- 关于 OSS 多版本的介绍,请参见 OSS 版本控制概述