GenerateWebofficeToken - Intelligent Media Management - Alibaba Cloud Documentation Center

Generates an access token for document preview or editing.

Operation description

Before you call this operation, make sure that you are familiar with the billing of Intelligent Media Management (IMM).****
The operation generates an access token that is valid for 30 minutes and a refresh token that is valid for 1 day.
The returned expiration time is in UTC.
The operation supports the following input formats:
- Word files: .doc, .docx, .txt, .dot, .wps, .wpt, .dotx, .docm, .dotm, and .rtf
- Presentation files: .ppt, .pptx, .pptm, .ppsx, .ppsm, .pps, .potx, .potm, .dpt, and .dps
- Spreadsheet documents: .et, .xls, .xlt, .xlsx, .xlsm, .xltx, .xltm, and .csv
- PDF files: .pdf
The operation supports an input document that is up to 200 MB in size.
The operation supports an input document that contains up to 5,000 pages.
For a project created before December 1, 2023, you are charged for previewing or editing a document in the project based on the number of times the document is opened. For a project created on or after December 1, 2023, you are charged based on the number of API operation calls made for previewing or editing a document. If you want to switch to API call-based billing for document previewing and editing, use a project created on or after December 1, 2023. In API call-based billing, one API call allows only one user to use the feature. If multiple users use the information returned by the API call, only the last user has access to the document and the access permissions of other users are revoked.
You can use the NotifyTopicName parameter to specify a Simple Message Queue (SMQ) topic in the same region as the IMM project for getting notified of file save operations. For more information, see Use queues. For more information about the JSON example of the Message field, see WebOffice message example.

Note To manage multiple versions of the document, you must enable versioning for the bucket that stores the document and 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.

Debug

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:
- The required resource types are displayed in bold characters.
- 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.

Operation	Access level	Resource type	Condition key	Associated operation
imm:GenerateWebofficeToken	none	*Project `acs:imm:{#regionId}:{#accountId}:project/{#ProjectName}`	none	none

Request parameters

Parameter	Type	Required	Description	Example
Filename	string	No	The name of the file. The extension must be included in the file name. By default, this parameter is set to the last depth level of the SourceURI parameter value. Supported extensions (only preview supported for .pdf): Word documents: .doc, .docx, .txt, .dot, .wps, .wpt, .dotx, .docm, .dotm, and .rtf Presentation documents: .ppt, .pptx, .pptm, .ppsx, .ppsm, .pps, .potx, .potm, .dpt, and .dps Table documents: .et, .xls, .xlt, .xlsx, .xlsm, .xltx, .xltm, and .csv PDF documents: .pdf	test.pptx
CachePreview	boolean	No	Specifies whether to enable cache preview. true: enables cache preview. The document can be previewed only and cannot be collaboratively edited. false: does not enable cache preview. The document can be collaboratively edited when it is being previewed. Note The pricing for document previews varies based on whether cache preview is enabled or disabled. Note If you specify this parameter, the Pemission.copy parameter does not take effect. > Note Printing is not supported during cache preview.	false
UserData	string	No	The user-defined data that you want to return in asynchronous messages. This parameter takes effect only when you specify the MNS settings in the Notification parameter. The maximum length of the value is 2,048 bytes.	{"file_id": "abc"}
ExternalUploaded	boolean	No	Specifies whether to allow an upload of a document to the Object Storage Service (OSS) bucket. Valid values: true: Documents can be directly uploaded to OSS. The uploaded document overwrites the existing document and a new version is generated for the document. Before you upload a new document, close the existing document if it is being edited. After the document is uploaded, wait for approximately 5 minutes before you open the document again so that the new version can successfully load. Upload a new document only when the existing is closed. Otherwise, the uploaded document is overwritten when the existing document is saved. false: Documents cannot be directly uploaded to OSS. If you try to upload a document, an error is returned. This is the default value.	false
Permission	WebofficePermission	No	The user permission settings in the JSON format. The parameter supports the following permission fields: Each field is of type Boolean and can have a value of true and false (the default value): Readonly: grants the permission to preview the document. This field is optional. Rename: grants the permission to rename the document. Notification messages of a rename event can be sent only by using SMQ. This field is optional. History: grants the permission to view historical versions. This field is optional. Copy: grants the permission to copy the document. This field is optional. Export: grants the permission to export the document as a PDF file. This field is optional. Print: grants the permission to print the document. This field is optional. Note Only online preview is supported for PDF documents. When you call the operation on a PDF document, you can set Readonly only to true. Note To manage multiple versions of the document, you must enable versioning for the bucket that stores the document and set the History parameter to true. Note Printing is not supported during cache preview.
User	WebofficeUser	No	The user information. The user information that you want to display on the WebOffice page. If you do not specify this parameter, the user name displayed is Unknown.
CredentialConfig	CredentialConfig	No	If you have no special requirements, leave this parameter empty. The configurations of authorization chains. For more information, see Use authorization chains to access resources of other entities.
Notification	Notification	No	The notification settings. Only Simple Message Queue messages are supported. For more information, see WebOffice message example. Note A notification is sent after the document is saved or renamed.

Example scenarios

This section provides sample parameter configurations in some typical document editing and preview scenarios.

Only preview a file (PDF files can only be previewed)

In preview mode, a document can only be previewed but not edited. The following content provides a sample configuration:

 {
    "ProjectName"   : "test-project",
    "SourceURI" : "oss://test-bucket/test-object.pdf",
    "Filename" : "test-object.docx",
    "PreviewPages" : "5",
    "Permission" : "{'Readonly':'true'}"
}

Preview a file with an extension in uppercase

To preview a file with an extension in uppercase, the extension part of the Filename parameter value must be in lowercase. The following content provides a sample configuration:

 {
    "ProjectName"   : "test-project",
    "SourceURI" : "oss://test-bucket/test-object.DOCX",
    "Filename" : "test-object.docx",
    "PreviewPages" : "5",
    "Permission" : "{'Readonly':'true'}"
}

Preview a specified number of pages from the beginning of a document

To preview a specified number of pages from the beginning of a document, specify the PreviewPages parameter. The following sample configuration allows the first 5 pages to be previewed:

 {
    "ProjectName"   : "test-project",
    "SourceURI" : "oss://test-bucket/test-object.docx",
    "Filename" : "test-object.docx",
    "PreviewPages" : "5",
    "Permission" : "{'Readonly':'true'}"
}

Specify a password for document previews

You can allow a document to be previewed only when a correct preview password is provided. If the document is originally protected by a password, the document can be previewed by using this preview password without requiring the original password that protects the document. The following content provides a sample configuration:

 {
    "ProjectName"   : "test-project",
    "SourceURI" : "oss://test-bucket/test-object.docx",
    "Filename" : "test-object.docx",
    "Password" : "123456",
    "Permission" : "{'Readonly':'true'}"
}

Add a watermark for document previews

The following configuration provides an example on how to add a watermark for document previews

 {
    "ProjectName"   : "test-project",
    "SourceURI" : "oss://test-bucket/test-object.docx",
    "Filename" : "test-object.docx",
    "Watermark" : "{'Type':'1','Value':'Watermark text','Font':'bold 20px Serif'}",
    "Permission" : "{'Readonly':'true'}"
}

The following configuration provides an example on how to hide the toolbar for document previews:

 {
    "ProjectName"   : "test-project",
    "SourceURI" : "oss://test-bucket/test-object.docx",
    "Filename" : "test-object.docx",
    "Hidecmb" : "true",
    "Permission" : "{'Readonly':'true'}"
}

Grant permissions for editing, version-checking, copying, printing, and exporting

The following configuration provides an example on how to grant permissions to edit, copy, and print a document, export the document as PDF, and view historical versions of the document:

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

Parameter	Type	Description	Example

The current API has no return parameters

Examples

Sample success responses

JSONformat

{
  "RequestId": "1759315A-CB33-0A75-A72B-62D7********",
  "WebofficeURL": "https://office-hl.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 time	Summary of changes	Operation
2023-08-30	The internal configuration of the API is changed, but the call is not affected	View Change Details
2023-03-09	The request parameters of the API has changed	View Change Details