文档

GenerateWebofficeToken - 获取Weboffice凭证

更新时间:

获取文档预览编辑凭证。

接口说明

  • 请确保在使用该接口前,已充分了解智能媒体管理产品的收费方式和价格

  • 访问凭证过期时间为 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:GenerateWebofficeTokennone
  • Project
    acs:imm:{#regionId}:{#accountId}:project/{#ProjectName}

请求参数

名称类型必填描述示例值
ProjectNamestring

项目名称,获取方式请参见创建项目

test-project
SourceURIstring

待预览或编辑文档的 OSS 地址。

OSS 地址规则为oss://${Bucket}/${Object},其中Bucket为和当前项目处于同一地域的 OSS Bucket 名称,Object为包含文件扩展名的文件完整路径。

oss://test-bucket/test-object.docx
Filenamestring

文件名称,必须包含文件扩展名。默认为参数 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
CachePreviewboolean

缓存预览标识:

  • true:开启后,文档预览时将不再更新协同编辑内容,适用于仅预览的场景。
  • false:关闭时,默认采用协同预览,及预览时候可以同步更新协同编辑内容。

注意 缓存预览和非缓存预览的单价不同,详情请查看计费项说明。
注意 该参数设置后,Pemission.copy 参数不生效。

true、false
Refererstring

OSS 防盗链。IMM 需要从 OSS 中获取源文件,如果 OSS 进行了防盗链设置,IMM 需要将对应的头部传给 OSS 才能获取源文件。

说明 如果访问文档所在的 Bucket 设置了 Referer,请设置此参数。
*
UserDatastring

用户自定义信息,必须填写 Notification 参数传入 MNS 配置时才能生效,在异步消息通知中会为您返回,用于方便您系统内对消息通知进行关联处理。最大长度为 2048 字节。

{ "id": "test-id", "name": "test-name" }
PreviewPageslong

限制只能预览前几页,默认不限制。最大不能超过 5000

5
Passwordstring

文档的打开密码。

说明 如果需要预览或编辑有密码的文档,请设置此参数。
123456
ExternalUploadedboolean

是否支持直接上传文档到 OSS。可取值如下:

  • true:支持,上传的文档将覆盖原文档生成新版本。在开启后,仍需先关闭当前正在编辑的文档,然后等待约 5 分钟后重新打开,才能加载新的文档。仅当文档处于关闭状态时才可上传,文档处于打开状态时,新的保存会覆盖掉上传的文件。
  • false(默认):不支持,上传文档是非预期行为,会返回错误。
false
NotifyTopicNamestring

支持将一些事件以 MNS 消息的方式通知给客户。该参数为 MNS 异步消息通知的 topic。

test-topic
Hidecmbboolean

是否隐藏工具栏,文档预览模式下支持设置此参数。可取值如下:

  • false(默认):不隐藏工具栏。

  • true:隐藏工具栏。

false
PermissionWebofficePermission

用户权限信息,以 JSON 格式表示。

用户权限包括如下选项:

每个选项的类型均为 Boolean,默认值均为 false,可选值为 true 和 false。

  • Readonly(可选):预览模式。

  • Rename(可选):重命名文件权限,只提供消息通知功能,重命名事件会发送到 MNS 中。

  • History(可选):查看历史版本的权限。

  • Copy(可选):拷贝权限。

  • Export(可选):导出 PDF 权限。

  • Print(可选):打印权限。

说明 PDF 仅支持预览功能,因此必须将” Readonly“参数设置为 true。
说明 若要使用多版本功能,必须先在 OSS 中开通多版本功能,然后将 ”History“参数设置为 true。
UserWebofficeUser

用户信息。可以传业务的用户信息,WebOffice 页面会进行显示,如果不传入此字段,用户信息会默认显示为“Unknown”。

WatermarkWebofficeWatermark

水印信息。该水印在前端生成,并没有写入到源文档中,同一个文档传入不同的参数会得到不同的水印。

CredentialConfigCredentialConfig

如无特殊需求,请保持留空即可。

链式授权配置,非必填。更多信息,请参见使用链式授权访问其他实体资源

NotificationNotification

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 访问凭证。

RequestIdstring

请求 ID。

1759315A-CB33-0A75-A72B-62D7********
WebofficeURLstring

Weboffice 入口 URL。在线预览或者编辑文档。

说明 无法通过浏览器直接打开,需要配合 Weboffice JS-SDK,和访问凭证(AccessToken)一起才可以预览或编辑文档。更多信息,请参见快速入门
https://office-cn-shanghai.imm.aliyuncs.com/office/s/dd221b2cdb44fb66e9070d1d70a8b9bbb6d6fff7?_w_tokentype=1
AccessTokenstring

Weboffice 访问凭证。

2d73dd5d87524c5e8a194c3eb5********
RefreshTokenstring

Weboffice 刷新凭证。

e374995ec532432bb678074d36********
AccessTokenExpiredTimestring

访问凭证的过期时间。过期时间 30 分钟。

2021-08-30T13:13:11.347146982Z
RefreshTokenExpiredTimestring

刷新凭证的过期时间。过期时间 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-30API 内部配置变更,不影响调用查看变更详情
2023-03-09OpenAPI 入参发生变更查看变更详情

相关文档