All Products
Search

This Product

    Intelligent Media Management:GenerateWebofficeToken

    Document Center

    Intelligent Media Management:GenerateWebofficeToken

    最終更新日:Nov 20, 2025
    This topic is generated by a machine translation engine without any human intervention. ALIBABA CLOUD DOES NOT GUARANTEE THE ACCURACY OF MACHINE TRANSLATED CONTENT. To request a human-translated version of this topic or provide feedback on this translation, please include it in the feedback form.

    Obtain Document Preview and Edit Token

    Operation description

    • Please ensure that you fully understand the billing method and pricing of the Intelligent Media Management product before using this interface.

    • The access token expires in 30 minutes, and the refresh token expires in 1 day.

    • The returned expiration time is in UTC, which has an 8-hour difference from Beijing Time.

    • Supported input file formats:

      • Word documents: doc, docx, txt, dot, wps, wpt, dotx, docm, dotm, rtf.
      • Presentation documents (PPT): ppt, pptx, pptm, ppsx, ppsm, pps, potx, potm, dpt, dps.
      • Spreadsheet documents (Excel): et, xls, xlt, xlsx, xlsm, xltx, xltm, csv
      • PDF documents: pdf.

    • Supports files up to 200MB.

    • Supports documents with a maximum of 5000 pages.

    • Projects created before 2023-12-01 are billed based on the number of document openings. Currently, billing is based on the number of API calls. To switch to the new billing model, simply create a new project. Note that one API call can only be used by one user; if reused, only the last user will have normal access, and the access rights of other users will be revoked.

    • In the same region as the Intelligent Media Management, activate MNS service, create topics and queues, and configure subscription relationships. You can pass the MNS topic name through the NotifyTopicName parameter to receive message notifications for file saves. For more information about the MNS SDK, see Receiving and Deleting Messages. For an example of the JSON format of the Message field in file save message notifications, refer to WebOffice Message Notification Format.

    Note To use the multi-version feature, you must first enable the multi-version feature in OSS, then set the 'History' parameter to true.

    Debugging

    You can run this interface directly in OpenAPI Explorer, saving you the trouble of calculating signatures. After running successfully, OpenAPI Explorer can automatically generate SDK code samples.

    Authorization information

    The following table shows the authorization information corresponding to the API. The authorization information can be used in the Action policy element to grant a RAM user or RAM role the permissions to call this API operation. Description:

    • Operation: the value that you can use in the Action element to specify the operation on a resource.
    • Access level: the access level of each operation. The levels are read, write, and list.
    • Resource type: the type of the resource on which you can authorize the RAM user or the RAM role to perform the operation. Take note of the following items:
      • For mandatory resource types, indicate with a prefix of * .
      • If the permissions cannot be granted at the resource level, All Resources is used in the Resource type column of the operation.
    • Condition Key: the condition key that is defined by the cloud service.
    • Associated operation: other operations that the RAM user or the RAM role must have permissions to perform to complete the operation. To complete the operation, the RAM user or the RAM role must have the permissions to perform the associated operations.
    OperationAccess levelResource typeCondition keyAssociated operation
    imm:GenerateWebofficeTokennone
    *Project
    acs:imm:{#regionId}:{#accountId}:project/{#ProjectName}
      none
    		none

    Request parameters

    ParameterTypeRequiredDescriptionExample
    ProjectNamestringYes

    Project name, for how to obtain it, please refer to Create Project.

    		test-project
    SourceURIstringYes

    OSS address of the document to be previewed or edited. The OSS address follows the rule oss://${Bucket}/${Object}, where Bucket is the name of the OSS Bucket in the same region as the current project, and Object is the full path of the file including the file extension.

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

    Filename, which must include the file extension. By default, it is the last segment of the SourceURI parameter. Supported file extensions (PDF is only supported for preview):

    • Text documents (Word): doc, docx, txt, dot, wps, wpt, dotx, docm, dotm, rtf
    • Presentation documents (PPT): ppt, pptx, pptm, ppsx, ppsm, pps, potx, potm, dpt, dps - Spreadsheet documents (Excel): et, xls, xlt, xlsx, xlsm, xltx, xltm, csv
    • PDF documents: pdf
    		test-Object.pptx
    CachePreviewbooleanNo

    Cache preview flag:

    • true: When enabled, the document preview will no longer update collaborative editing content, suitable for scenarios where only preview is needed.
    • false: When disabled, it defaults to collaborative preview, allowing the preview to synchronously update collaborative editing content.
      Notice The price for cache preview and non-cache preview differs. Please refer to the billing item description for more details.
      Notice Search and print functions are not supported during cache preview.
      Notice Updating cached content is currently not supported in cache preview mode.
    		true、false
    RefererstringNo

    OSS anti-leeching. IMM needs to obtain the source file from OSS. If OSS has set up anti-leeching, IMM must pass the corresponding header to OSS to get the source file.

    Note If the Bucket where the document is located has Referer set, please configure this parameter.
    		*
    UserDatastringNo

    User-defined information. It only takes effect when Notification parameters are filled in for MNS configuration. It will be returned in asynchronous message notifications, which can help you correlate and process messages within your system. The maximum length is 2048 bytes.

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

    Limits the number of pages that can be previewed. By default, there is no limit. The maximum cannot exceed 5000.

    		5
    PasswordstringNo

    The password to open the document.

    Note If you need to preview or edit a password-protected document, set this parameter.
    		123456
    ExternalUploadedbooleanNo

    Indicates whether uploading a file with the same name to OSS is an expected behavior. Possible values are as follows:

    • true: Uploading a file with the same name to OSS is an expected behavior. The uploaded document will overwrite the original document and generate a new version. After setting it to true, you still need to close the currently editing document and wait for about 5 minutes before reopening it to load the new document. The upload is only effective when the document is closed; if the document is open, the new save will overwrite the uploaded file.
    • false (default): Uploading a file with the same name to OSS is not an expected behavior, and the interface will return an error.
    		false
    NotifyTopicNamestringNo

    Supports notifying some events to customers via MNS messages. This parameter is the topic for MNS asynchronous message notifications.

    		test-topic
    HidecmbbooleanNo

    Whether to hide the toolbar. This parameter can be set in document preview mode. Possible values are as follows:

    • false (default): Do not hide the toolbar.
    • true: Hide the toolbar.
    		false
    PermissionWebofficePermissionNo

    User permission information, represented in JSON format.

    User permissions include the following options:

    Each option is of type Boolean, with a default value of false, and can be set to true or false.

    • Readonly (optional): Preview mode.
    • Rename (optional): File renaming permission, which only provides message notification functionality. The renaming event will be sent to MNS.
    • History (optional): Permission to view historical versions.
    • Copy (optional): Copy permission.
    • Export (optional): PDF export permission.
    • Print (optional): Print permission.
    Note PDF only supports preview functionality, so the "Readonly" parameter must be set to true. PDF files do not support exporting. To use the multi-version feature, you must first enable the multi-version feature in OSS and then set the "History" parameter to true.

    Notice Printing is not supported in cached preview.
    Notice Historical versions can be viewed in edit mode but not in preview mode.

    UserWebofficeUserNo

    User information. You can pass in user information from the business side, which will be displayed on the WebOffice page.

    The system distinguishes different users by User.Id, and User.Name is used only for front-end display. If User.Id is not provided, the backend will generate a random ID. Users with different IDs are considered different entities and cannot modify or delete each other's comments.

    The default format is: Unknown_random string. If User.Id is not provided, the user information will default to "Unknown".

    WatermarkWebofficeWatermarkNo

    Watermark information. The watermark is generated on the front end and is not written into the source document. The same document with different parameters will result in different watermarks.

    CredentialConfigCredentialConfigNo

    If there are no special requirements, leave this blank.

    Chained authorization configuration, not required. For more information, see Using Chained Authorization to Access Other Entity Resources.

    NotificationNotificationNo

    Notification message configuration, currently supporting only MNS. For the asynchronous notification message format, refer to WebOffice Message Notification Format.

    Note There will be message notifications when the file is saved or renamed.

    典型场景举例

    对于如下示例的参数结构，对一些经典的场景示例说明：

    预览只读文件（如果是预览 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'}"
}

    Response parameters

    ParameterTypeDescriptionExample
    object

    Weboffice access credentials.

    RequestIdstring

    Request ID.

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

    Weboffice entry URL. Used for online preview or editing of documents.

    Note Cannot be opened directly in a browser; it needs to be used with the Weboffice JS-SDK and access token (AccessToken) to preview or edit documents. For more information, see Getting Started.
    		https://office-cn-shanghai.imm.aliyuncs.com/office/s/dd221b2cdb44fb66e9070d1d70a8b9bbb6d6fff7?_w_tokentype=1
    AccessTokenstring

    Weboffice access token.

    		2d73dd5d87524c5e8a194c3eb5********
    RefreshTokenstring

    Weboffice refresh token.

    		e374995ec532432bb678074d36********
    AccessTokenExpiredTimestring

    Expiration time of the access token. The expiration time is 30 minutes.

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

    Expiration time of the refresh token. The expiration time is 1 day.

    		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"
}

    Examples

    Sample success responses

    JSONformat

    {
  "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"
}

    Error codes

    For a list of error codes, visit the Service error codes.

    Change history

    Change timeSummary of changesOperation
    2023-08-30The internal configuration of the API is changed, but the call is not affectedView Change Details
    2023-03-09The request parameters of the API has changedView Change Details

    相关文档