對於無法在瀏覽器中直接預覽的文字文檔(Word)、示範文檔(PPT)和表格文檔(Excel),您可以藉助 WebOffice 的線上預覽功能,實現直接在瀏覽器中查看文檔內容,而無需下載文檔。
使用情境
企業知識庫或文件管理系統:員工可將檔案上傳並轉化為網頁格式,方便快速查看,提升資訊訪問效率和安全性。
線上教育平台:教師和學生可以即時查看教材、講義和作業,促進互動和學習體驗。
協同辦公與專案管理工具:團隊成員共用的工作計劃、設計稿和報告文檔可直接在瀏覽器中查看,提升團隊協作效率。
支援的檔案類型
檔案類型 | 檔案尾碼 |
Word | doc、dot、wps、wpt、docx、dotx、docm、dotm、rtf |
PPT | ppt、pptx、pptm、ppsx、ppsm、pps、potx、potm、dpt、dps |
Excel | xls、xlt、et、xlsx、xltx、csv、xlsm、xltm |
注意事項
不建議對 OSS 檔案執行跨境訪問操作。例如,檔案儲存體在新加坡地區的 Bucket 中,卻從中國內地發起預覽、讀取或下載請求。在此類情境下,網路鏈路品質受跨境網路環境影響較大,可能出現訪問延遲升高、預覽失敗、下載中斷或串連不穩定等情況,因此無法保證網路穩定性和訪問體驗。建議盡量確保訪問端與 Bucket 所在地區保持一致,避免跨境訪問帶來的不確定性。
WebOffice線上預覽僅支援同步處理(x-oss-process處理方式)。
WebOffice 線上預覽需通過後端服務調用 OSS SDK 產生簽名 URL,不支援在前端代碼中直接初始化 OSS SDK,也不支援直接通過 GET 參數形式構造預覽 URL。
ali-ossSDK 需要傳入accessKeyId和accessKeySecret參數,前端環境下可通過瀏覽器DevTools查看並竊取憑證,存在憑證泄露風險。以未簽名的 GET 請求直接存取 OSS 對象會被拒絕(返回 403AccessDenied),簽名機制確保訪問合法性,避免未授權訪問產生不可控的資料處理費用。後端產生的簽名 URL 可在瀏覽器中直接使用,簽名 URL 包含OSSAccessKeyId、Expires、Signature參數,有到期時間,到期後自動失效。
如何使用
前提條件
在OSS中建立儲存空間(Bucket),上傳需要預覽的Office文檔至Bucket中,並為該Bucket綁定Intelligent Media Management(IMM)的 Project,IMM Project需要跟Bucket在同一地區下。
需要您通過自訂網域名訪問OSS,通過自訂網域名訪問檔案時才能開啟預覽。
說明如提示網域名稱未配置至小程式的WebView白名單,請通過DingTalk使用者群(DingTalk群號:88490020073)聯絡Intelligent Media Management支援人員。技術支援人員將根據使用者提供的微信可信網域名稱驗證檔案進行白名單配置。
擷取URL連結實現預覽
Java
要求使用3.17.4及以上版本的Java SDK,Java SDK的安裝請參見安裝。
package com.aliyun.oss.demo;
import com.aliyun.oss.*;
import com.aliyun.oss.common.auth.*;
import com.aliyun.oss.common.comm.SignVersion;
import com.aliyun.oss.model.GeneratePresignedUrlRequest;
import java.net.URL;
import java.util.Date;
public class Demo {
public static void main(String[] args) throws Throwable {
// 請填寫您的自訂網域名。例如http://static.example.com。
String endpoint = "http://static.example.com";
// 從環境變數中擷取訪問憑證。運行本程式碼範例之前,請確保已設定環境變數OSS_ACCESS_KEY_ID和OSS_ACCESS_KEY_SECRET。
EnvironmentVariableCredentialsProvider credentialsProvider = CredentialsProviderFactory.newEnvironmentVariableCredentialsProvider();
// 填寫Bucket名稱,例如examplebucket。
String bucketName = "examplebucket";
// 填寫Object完整路徑。如果不在Bucket根目錄,需攜帶Object完整路徑
String objectName = "exampledir/exampleobject.docx";
// 填寫Bucket所在地區。以華東1(杭州)為例,Region填寫為cn-hangzhou。
String region = "cn-hangzhou";
// 建立OSSClient執行個體。
// 當OSSClient執行個體不再使用時,調用shutdown方法以釋放資源。
ClientBuilderConfiguration clientBuilderConfiguration = new ClientBuilderConfiguration();
// 請注意,設定true開啟CNAME選項。
clientBuilderConfiguration.setSupportCname(true);
// 顯式聲明使用 V4 簽名演算法
clientBuilderConfiguration.setSignatureVersion(SignVersion.V4);
OSS ossClient = OSSClientBuilder.create()
.endpoint(endpoint)
.credentialsProvider(credentialsProvider)
.clientConfiguration(clientBuilderConfiguration)
.region(region)
.build();
try {
// 文檔處理參數
String style = "doc/preview,export_1,print_1/watermark,text_5YaF6YOo6LWE5paZ,size_30,t_60";
// 指定簽名URL到期時間為3600秒)
Date expiration = new Date(new Date().getTime() + 3600 * 1000L );
GeneratePresignedUrlRequest req = new GeneratePresignedUrlRequest(bucketName, objectName, HttpMethod.GET);
req.setExpiration(expiration);
req.setProcess(style);
URL signedUrl = ossClient.generatePresignedUrl(req);
System.out.println(signedUrl);
} catch (OSSException oe) {
System.out.println("Caught an OSSException, which means your request made it to OSS, "
+ "but was rejected with an error response for some reason.");
System.out.println("Error Message:" + oe.getErrorMessage());
System.out.println("Error Code:" + oe.getErrorCode());
System.out.println("Request ID:" + oe.getRequestId());
System.out.println("Host ID:" + oe.getHostId());
} catch (ClientException ce) {
System.out.println("Caught an ClientException, which means the client encountered "
+ "a serious internal problem while trying to communicate with OSS, "
+ "such as not being able to access the network.");
System.out.println("Error Message:" + ce.getMessage());
} finally {
if (ossClient != null) {
ossClient.shutdown();
}
}
}
}Python
要求使用Python SDK 2.18.4及以上版本,Python SDK的安裝請參見安裝(Python SDK V1)。
# -*- coding: utf-8 -*-
import oss2
from oss2.credentials import EnvironmentVariableCredentialsProvider
# 從環境變數中擷取訪問憑證。運行本程式碼範例之前,請確保已設定環境變數OSS_ACCESS_KEY_ID和OSS_ACCESS_KEY_SECRET。
auth = oss2.ProviderAuthV4(EnvironmentVariableCredentialsProvider())
# 填寫Bucket名稱
bucket = 'examplebucket'
# 請填寫您的自訂網域名。例如https://static.example.com。
endpoint = 'https://static.example.com'
# 填寫阿里雲通用Region ID
region = 'cn-hangzhou'
# 使用自訂網域名初始化bucket
bucket = oss2.Bucket(auth, endpoint, bucket, is_cname=True, region=region)
# 指定處理檔案
key = 'example.docx'
# 指定到期時間,單位秒
expire_time = 3600
# 構建線上預覽的處理指示。
image_process = 'doc/preview,export_1,print_1/watermark,text_5YaF6YOo6LWE5paZ,size_30,t_60'
# 產生簽名URL,帶上處理參數
url = bucket.sign_url('GET', key, expire_time, params={'x-oss-process': image_process}, slash_safe=True)
# 列印簽名URL
print(url)Go
要求使用Go SDK 3.0.2及以上版本,Go SDK的安裝請參見安裝OSS Go SDK。
package main
import (
"context"
"flag"
"log"
"time"
"github.com/aliyun/alibabacloud-oss-go-sdk-v2/oss"
"github.com/aliyun/alibabacloud-oss-go-sdk-v2/oss/credentials"
)
// 定義全域變數
var (
region string // 儲存地區
bucketName string // 儲存空間名稱
objectName string // 對象名稱
)
// init函數用於初始化命令列參數
func init() {
flag.StringVar(®ion, "region", "", "The region in which the bucket is located.")
flag.StringVar(&bucketName, "bucket", "", "The name of the bucket.")
flag.StringVar(&objectName, "object", "", "The name of the object.")
}
func main() {
// 解析命令列參數
flag.Parse()
// 檢查bucket名稱是否為空白
if len(bucketName) == 0 {
flag.PrintDefaults()
log.Fatalf("invalid parameters, bucket name required")
}
// 檢查region是否為空白
if len(region) == 0 {
flag.PrintDefaults()
log.Fatalf("invalid parameters, region required")
}
// 檢查object名稱是否為空白
if len(objectName) == 0 {
flag.PrintDefaults()
log.Fatalf("invalid parameters, object name required")
}
// 載入預設配置並設定憑證提供者和地區
cfg := oss.LoadDefaultConfig().
WithCredentialsProvider(credentials.NewEnvironmentVariableCredentialsProvider()).
WithRegion(region).
// 請填寫您的自訂網域名。例如http://static.example.com。
WithEndpoint("http://static.example.com").
WithUseCName(true)
// 建立OSS用戶端
client := oss.NewClient(cfg)
// 產生GetObject的預簽名URL
result, err := client.Presign(context.TODO(), &oss.GetObjectRequest{
Bucket: oss.Ptr(bucketName),
Key: oss.Ptr(objectName),
// 設定文檔處理參數
Process: oss.Ptr("doc/preview,export_1,print_1/watermark,text_5YaF6YOo6LWE5paZ,size_30,t_60"),
}, oss.PresignExpires(10*time.Minute))
if err != nil {
log.Fatalf("failed to get object presign %v", err)
}
log.Printf("request method:%v\n", result.Method)
log.Printf("request expiration:%v\n", result.Expiration)
log.Printf("request url:%v\n", result.URL)
if len(result.SignedHeaders) > 0 {
// 當返回結果包含簽名頭時,使用簽名URL發送GET請求時也包含相應的要求標頭,以免出現不一致,導致請求失敗和簽名錯誤
log.Printf("signed headers:\n")
for k, v := range result.SignedHeaders {
log.Printf("%v: %v\n", k, v)
}
}
}Node.js
要求使用Node.js SDK 8.0及以上版本,Node.js SDK的安裝請參見安裝(Node.js SDK)。
const OSS = require("ali-oss");
// 定義一個產生簽名 URL 的函數
async function generateSignatureUrl(fileName) {
// 擷取簽名URL
const client = await new OSS({
// 請填寫您的自訂網域名。例如http://static.example.com。
endpoint: 'http://static.example.com',
// 從環境變數中擷取訪問憑證。運行本程式碼範例之前,請確保已設定環境變數OSS_ACCESS_KEY_ID和OSS_ACCESS_KEY_SECRET。
accessKeyId: process.env.OSS_ACCESS_KEY_ID,
accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET,
bucket: 'examplebucket',
// 填寫Bucket所在地區。以華東1(杭州)為例,Region填寫為oss-cn-hangzhou。
region: 'oss-cn-hangzhou',
authorizationV4: true,
cname: true
});
// 產生簽名URL,並包含文檔處理參數
return await client.signatureUrlV4('GET', 3600, {
headers: {}, // 請根據實際發送的要求標頭設定此處的要求標頭
queries: {
"x-oss-process": "doc/preview,export_1,print_1/watermark,text_5YaF6YOo6LWE5paZ,size_30,t_60" // 添加文檔處理參數
}
}, fileName);
}
// 調用函數並傳入檔案名稱
generateSignatureUrl('yourFileName').then(url => {
console.log('Generated Signature URL:', url);
}).catch(err => {
console.error('Error generating signature URL:', err);
});
PHP
要求使用PHP SDK 2.7.0及以上版本,PHP SDK的安裝請參見安裝(PHP SDK V1)。
<?php
if (is_file(__DIR__ . '/../autoload.php')) {
require_once __DIR__ . '/../autoload.php';
}
if (is_file(__DIR__ . '/../vendor/autoload.php')) {
require_once __DIR__ . '/../vendor/autoload.php';
}
use OSS\OssClient;
use OSS\Core\OssException;
use OSS\Http\RequestCore;
use OSS\Http\ResponseCore;
use OSS\Credentials\EnvironmentVariableCredentialsProvider;
// 從環境變數中擷取訪問憑證。運行本程式碼範例之前,請確保已設定環境變數OSS_ACCESS_KEY_ID和OSS_ACCESS_KEY_SECRET。
$provider = new EnvironmentVariableCredentialsProvider();
//請填寫您的自訂網域名。例如http://static.example.com。
$endpoint = "http://static.example.com";
// 填寫Bucket名稱,例如examplebucket。
$bucket= "examplebucket";
// 如果文檔位於Bucket根目錄,則直接填寫文檔名稱。如果文檔不在Bucket根目錄,需攜帶文檔完整路徑,例如exampledir/example.docx。
$object = 'example.docx';
$config = array(
"provider" => $provider,
"endpoint" => $endpoint,
"signatureVersion" => OssClient::OSS_SIGNATURE_VERSION_V4,
"cname" => true,
"region"=> "cn-hangzhou"
);
$ossClient = new OssClient($config);
// 產生一個帶處理參數的簽名的URL,有效期間是3600秒,可以直接使用瀏覽器訪問。
$timeout = 3600;
$options = array(
// 構建線上預覽的處理指示。
OssClient::OSS_PROCESS => "doc/preview,export_1,print_1/watermark,text_5YaF6YOo6LWE5paZ,size_30,t_60");
$signedUrl = $ossClient->signUrl($bucket, $object, $timeout, "GET", $options);
print("url: \n" . $signedUrl);產生的簽名URL樣本如下:
http://static.example.com/example.docx?x-oss-process=doc%2Fpreview%2Cexport_1%2Cprint_1%2Fwatermark%2Ctext_5YaF6YOo6LWE5paZ%2Csize_30%2Ct_60&x-oss-date=20250122T020741Z&x-oss-expires=3600&x-oss-signature-version=OSS4-HMAC-SHA256&x-oss-credential=LTAI********************%2F20250122%2Fcn-hangzhou%2Foss%2Faliyun_v4_request&x-oss-signature=514ed93accdb80921c4b2897c6147fdb1599308c6457f68ee0ac2f771c7d0312複製產生的URL並粘貼到瀏覽器地址欄,按斷行符號鍵即可預覽WebOffice文檔。
參數說明
操作名稱:doc/preview
具體參數如下表所示:
參數名稱 | 類型 | 是否必須 | 描述 |
int | 否 | 是否允許列印。取值:
| |
copy | int | 否 | 是否允許複製。取值:
|
export | int | 否 | 是否允許匯出為PDF。取值:
|
maxpage | int | 否 | 最大渲染頁數,取大於0的整數。 |
watermark | string | 否 | 浮水印參數。 |
text | string | 否 | 浮水印文字,需經過URL Safe的Base64編碼。具體操作,請參見浮水印編碼,推薦通過base64url encoder進行編碼。 父節點:watermark |
size | int | 否 | 浮水印文字字型大小,取大於0的整數。 父節點:watermark |
t | int | 否 | 浮水印文字透明度。取值範圍:0~100。預設值:100(不透明)。 父節點:watermark |
color | string | 否 | 浮水印文字顏色,RGB顏色值,預設值為#FFFFFF。 例如:#000000表示黑色,#FFFFFF表示白色。 父節點:watermark |
rotate | int | 否 | 指定文字順時針旋轉角度。取值範圍:0~360。預設值為0(不旋轉)。 父節點:watermark |
type | string | 否 | 指定文字浮水印的字型,需經過URL Safe的Base64編碼。具體操作,請參見浮水印編碼,推薦通過base64url encoder進行編碼。 支援的字型如下:
父節點:watermark |
相關API
以上操作方式底層基於API實現,如果您的程式自訂要求較高,您可以直接發起REST API請求。直接發起REST API請求需要手動編寫代碼計算簽名。關於公用要求標頭Authorization的計算方法,請參見簽名版本4(推薦)。
預覽資訊
預覽文檔名稱:example.docx
預覽頁面:文檔前3頁
預覽頁面浮水印資訊:
浮水印類型:文字浮水印
浮水印文字:內部資料
浮水印字型大小:30號字型
浮水印透明度:60
預覽頁面許可權資訊:允許使用者複製、匯出、列印
處理樣本
GET /example.docx?x-oss-process=doc/preview,export_1,print_1/watermark,text_5YaF6YOo6LWE5paZ,size_30,t_60 HTTP/1.1
Host: doc-demo.oss-cn-hangzhou.aliyuncs.com
Date: Fri, 28 Oct 2022 06:40:10 GMT
Authorization: SignatureValue許可權說明
阿里雲帳號預設擁有全部許可權。阿里雲帳號下的RAM使用者或RAM角色預設沒有任何許可權,需要阿里雲帳號或帳號管理員通過RAM Policy概述或Bucket Policy授予操作許可權。
API | Action | 說明 |
GetObject |
| 下載Object。 |
| 下載Object時,如果通過versionId指定了Object的版本,則需要授予此操作的許可權。 | |
| 下載Object時,如果Object的中繼資料套件含X-Oss-Server-Side-Encryption: KMS,則需要此操作的許可權。 |
API | Action | 說明 |
無 |
| 通過OSS使用IMM進行資料處理的許可權。 |
API | Action | 說明 |
GenerateWebofficeToken |
| 用於擷取Weboffice憑證。 |
RefreshWebofficeToken |
| 用於重新整理Weboffice憑證。 |
計費說明
WebOffice線上預覽功能會產生以下計費項目。有關計費項目的定價詳情,請參見OSS產品定價和計費項目。
API | 計費項目 | 說明 |
GetObject | GET 類型請求 | 根據成功的請求次數計算請求費用。 |
外網流出流量費用 | 如果是通過外網Endpoint(樣本值oss-cn-hangzhou.aliyuncs.com)或者傳輸加速Endpoint(樣本值oss-accelerate.aliyuncs.com)調用GetObject介面時,會產生外網流出流量費用,根據資料容量大小計費。 | |
低頻訪問資料取回容量 | 如果取回的資料是低頻訪問資料,會產生低頻訪問資料取回容量的費用,按資料取回量計費。 | |
歸檔直讀資料取回容量 | 如果讀取的是歸檔的Object且Bucket開啟了歸檔直讀,會產生歸檔直讀資料取回容量費用,根據取回的資料容量大小計費。 | |
傳輸加速 | 如果開啟了傳輸加速功能且使用傳輸加速網域名稱訪問您的Bucket會產生傳輸加速費用,根據資料容量大小計費。 |
API | 計費項目 | 說明 |
GenerateWebofficeToken | DocumentWebofficePreview | 文檔預覽功能會產生文檔處理費用。 重要 截至2023年12月1日之前建立的線上預覽專案將根據文檔的開啟次數進行收費,而2023年12月1日及之後建立的專案則將按照API介面的調用次數計費。 |
RefreshWebofficeToken |
常見問題
是否支援預覽動態PPT中的動畫和視頻?
支援預覽動態PPT中的動畫和視頻,但請注意,線上預覽功能最大支援200 MB的文檔,超過200 MB則無法訪問。
是否支援預覽圖片檔案?
不支援。圖片檔案(如 jpg、png、gif 等)不通過 WebOffice 預覽,但可直接通過檔案 URL 在瀏覽器中預覽,無需調用文檔線上預覽 SDK。若圖片被強制下載,請檢查 Content-Disposition 和 Content-Type 設定。詳情請參見如何配置訪問 OSS 檔案時的預覽行為?。
開啟CDN後產生帶簽名的文檔URL報錯Either the Signature query string parameter or the Authorization header should be specified, not both.
如果您在私人 Bucket 開啟回源功能後,通過 CDN 網域名稱訪問已綁定至 IMM 專案的 Bucket 中的檔案,無需提供額外的簽名資訊。請按照以下要求進行配置:
授權預設角色 您需要為CDN的預設角色
AliyunCDNAccessingPrivateOSSRole授予oss:ProcessImm、imm:GenerateWebofficeToken以及imm:RefreshWebofficeToken的許可權。訪問資源時,應使用不包含簽名資訊的 URL。
例如,您可以使用如下格式的URL:http://cdn.example.info/demo.ppt?x-oss-process=doc/preview,export_1,print_1 使用文檔線上預覽功能。
為什麼使用 xlsx 檔案預覽時變成下載?
使用 x-oss-process 參數進行文檔線上預覽時,如果使用了 pdf/preview、xls/preview、xlsx/preview 等格式特定參數,OSS 會將其視為無效參數,直接返回原始檔案並附帶 Content-Disposition: attachment 頭,導致瀏覽器下載檔案而非線上預覽。
正確做法:統一使用 doc/preview 參數進行文檔預覽:
x-oss-process=doc/preview,export_1,print_1/watermark,text_<浮水印內容>,size_30,t_60使用前請確保已開通 IMM Intelligent Media Management服務並完成 Bucket 綁定。