调用GenerateWebofficeToken获取Weboffice凭证_智能媒体管理(IMM)-阿里云帮助中心

获取文档预览编辑凭证。

接口说明

请确保在使用该接口前，已充分了解智能媒体管理产品的收费方式和价格。
访问凭证过期时间为 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 消息通知格式。

说明若要使用多版本功能，必须先在 OSS 中开通多版本功能，然后将 ”History“参数设置为 true。

调试

您可以在OpenAPI Explorer中直接运行该接口，免去您计算签名的困扰。运行成功后，OpenAPI Explorer可以自动生成SDK代码示例。

调试

授权信息

下表是API对应的授权信息，可以在RAM权限策略语句的Action元素中使用，用来给RAM用户或RAM角色授予调用此API的权限。具体说明如下：

操作：是指具体的权限点。
访问级别：是指每个操作的访问级别，取值为写入（Write）、读取（Read）或列出（List）。
资源类型：是指操作中支持授权的资源类型。具体说明如下：
- 对于必选的资源类型，用背景高亮的方式表示。
- 对于不支持资源级授权的操作，用全部资源表示。
条件关键字：是指云产品自身定义的条件关键字。
关联操作：是指成功执行操作所需要的其他权限。操作者必须同时具备关联操作的权限，操作才能成功。

操作	访问级别	资源类型	条件关键字	关联操作
imm:GenerateWebofficeToken	none	*Project `acs:imm:{#regionId}:{#accountId}:project/{#ProjectName}`	无	无

请求参数

名称	类型	必填	描述	示例值
ProjectName	string	是	项目名称，获取方式请参见创建项目。	test-project
SourceURI	string	是	待预览或编辑文档的 OSS 地址。 OSS 地址规则为`oss://${Bucket}/${Object}`，其中`Bucket`为和当前项目处于同一地域的 OSS Bucket 名称，`Object`为包含文件扩展名的文件完整路径。	oss://test-bucket/test-object.docx
Filename	string	否	文件名称，必须包含文件扩展名。默认为参数 SourceURI 的最后一级。支持的文件扩展名（其中 PDF 只支持预览）：文字文档（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	test-Object.pptx
CachePreview	boolean	否	缓存预览标识： true：开启后，文档预览时将不再更新协同编辑内容，适用于仅预览的场景。 false：关闭时，默认采用协同预览，及预览时候可以同步更新协同编辑内容。注意缓存预览和非缓存预览的单价不同，详情请查看计费项说明。注意该参数设置后，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。可取值如下： true：支持，上传的文档将覆盖原文档生成新版本。在开启后，仍需先关闭当前正在编辑的文档，然后等待约 5 分钟后重新打开，才能加载新的文档。仅当文档处于关闭状态时才可上传，文档处于打开状态时，新的保存会覆盖掉上传的文件。 false（默认）：不支持，上传文档是非预期行为，会返回错误。	false
NotifyTopicName	string	否	支持将一些事件以 MNS 消息的方式通知给客户。该参数为 MNS 异步消息通知的 topic。	test-topic
Hidecmb	boolean	否	是否隐藏工具栏，文档预览模式下支持设置此参数。可取值如下： false（默认）：不隐藏工具栏。 true：隐藏工具栏。	false
Permission	WebofficePermission	否	用户权限信息，以 JSON 格式表示。用户权限包括如下选项：每个选项的类型均为 Boolean，默认值均为 false，可选值为 true 和 false。 Readonly（可选）：预览模式。 Rename（可选）：重命名文件权限，只提供消息通知功能，重命名事件会发送到 MNS 中。 History（可选）：查看历史版本的权限。 Copy（可选）：拷贝权限。 Export（可选）：导出 PDF 权限。 Print（可选）：打印权限。说明 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'}"
}

返回参数

名称	类型	描述	示例值
	object	Weboffice 访问凭证。
RequestId	string	请求 ID。	1759315A-CB33-0A75-A72B-62D7********
WebofficeURL	string	Weboffice 入口 URL。在线预览或者编辑文档。说明无法通过浏览器直接打开，需要配合 Weboffice JS-SDK，和访问凭证（AccessToken）一起才可以预览或编辑文档。更多信息，请参见快速入门。	https://office-cn-shanghai.imm.aliyuncs.com/office/s/dd221b2cdb44fb66e9070d1d70a8b9bbb6d6fff7?_w_tokentype=1
AccessToken	string	Weboffice 访问凭证。	2d73dd5d87524c5e8a194c3eb5********
RefreshToken	string	Weboffice 刷新凭证。	e374995ec532432bb678074d36********
AccessTokenExpiredTime	string	访问凭证的过期时间。过期时间 30 分钟。	2021-08-30T13:13:11.347146982Z
RefreshTokenExpiredTime	string	刷新凭证的过期时间。过期时间 1 天。	2021-08-31T12:43:11.347146982Z

常见错误

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 入参发生变更	查看变更详情

GenerateWebofficeToken - 获取Weboffice凭证