什麼是文檔快照 - Object Storage Service

使用文檔快照功能，您可以無需下載文檔，直接在雲端擷取文檔（Word/Excel/PPT/PDF）特定頁的快照，支援網頁嵌入、資料備份等多種情境。

使用情境

資料備份與恢複：在業務系統日常運行過程中，定期建立OSS Bucket中的文檔快照，用於備份資料。
關鍵資訊提取：文檔快照可以擷取特定頁的快照，快速提取關鍵資訊。

如何使用

前提條件

在OSS中建立儲存空間（Bucket），上傳需要處理的文檔至Bucket中，並為該Bucket綁定Intelligent Media Management（IMM）的 Project，IMM Project需要跟Bucket在同一地區下。

文檔快照

您可以使用SDK調用文檔快照介面進行處理。

Java

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 {
        // Endpoint以華東1（杭州）為例，其它Region請按實際情況填寫。
        String endpoint = "https://oss-cn-hangzhou.aliyuncs.com";
        // 從環境變數中擷取訪問憑證。運行本程式碼範例之前，請確保已設定環境變數OSS_ACCESS_KEY_ID和OSS_ACCESS_KEY_SECRET。
        EnvironmentVariableCredentialsProvider credentialsProvider = CredentialsProviderFactory.newEnvironmentVariableCredentialsProvider();
        // 填寫Bucket名稱，例如examplebucket。
        String bucketName = "examplebucket";
        // 填寫Object完整路徑。如果圖片不在Bucket根目錄，需攜帶完整路徑，例如exampledir/demo.docx
        String objectName = "demo.docx";
        // 填寫Bucket所在地區。以華東1（杭州）為例，Region填寫為cn-hangzhou。
        String region = "cn-hangzhou";

        // 建立OSSClient執行個體。
        // 當OSSClient執行個體不再使用時，調用shutdown方法以釋放資源。
        ClientBuilderConfiguration clientBuilderConfiguration = new ClientBuilderConfiguration();
        clientBuilderConfiguration.setSignatureVersion(SignVersion.V4);
        OSS ossClient = OSSClientBuilder.create()
                .endpoint(endpoint)
                .credentialsProvider(credentialsProvider)
                .clientConfiguration(clientBuilderConfiguration)
                .region(region)
                .build();

        try {
            // 構建文檔快照處理指示,擷取文檔的第2頁快照。
            String style = "doc/snapshot,target_jpg,source_docx,page_2";
            // 指定簽名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

# -*- 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'

# 填寫Bucket所在地區對應的Endpoint。以華東1（杭州）為例
endpoint = 'https://oss-cn-hangzhou.aliyuncs.com'

# 填寫阿里雲通用Region ID
region = 'cn-hangzhou'
bucket = oss2.Bucket(auth, endpoint, bucket, region=region)

# 指定原圖名稱。如果圖片不在Bucket根目錄，需攜帶圖片完整路徑，例如exampledir/demo.docx
key = 'demo.docx'

# 指定到期時間，單位秒
expire_time = 3600

# 構建文檔快照處理指示,擷取文檔的第2頁快照。
process = 'doc/snapshot,target_jpg,source_docx,page_2 '

# 產生簽名URL，帶上圖片處理參數
url = bucket.sign_url('GET', key, expire_time, params={'x-oss-process': process}, slash_safe=True)

# 列印簽名URL
print(url)

Go

package main

import (
	"fmt"
	"os"

	"github.com/aliyun/aliyun-oss-go-sdk/oss"
)

func HandleError(err error) {
	fmt.Println("Error:", err)
	os.Exit(-1)
}

func main() {
	// 從環境變數中擷取訪問憑證。運行本程式碼範例之前，請確保已設定環境變數OSS_ACCESS_KEY_ID和OSS_ACCESS_KEY_SECRET。
	provider, err := oss.NewEnvironmentVariableCredentialsProvider()
	if err != nil {
		fmt.Println("Error:", err)
		os.Exit(-1)
	}

	// 建立OSSClient執行個體。
	// yourEndpoint填寫Bucket對應的Endpoint，以華東1（杭州）為例，填寫為https://oss-cn-hangzhou.aliyuncs.com。其它Region請按實際情況填寫。
	// yourRegion填寫Bucket所在地區，以華東1（杭州）為例，填寫為cn-hangzhou。其它Region請按實際情況填寫。
	clientOptions := []oss.ClientOption{oss.SetCredentialsProvider(&provider)}
	clientOptions = append(clientOptions, oss.Region("yourRegion"))
	// 設定簽名版本
	clientOptions = append(clientOptions, oss.AuthVersion(oss.AuthV4))
	client, err := oss.New("yourEndpoint", "", "", clientOptions...)
	if err != nil {
		HandleError(err)
	}

	// 指定圖片所在Bucket的名稱，例如examplebucket。
	bucketName := "examplebucket"
	bucket, err := client.Bucket(bucketName)
	if err != nil {
		HandleError(err)
	}
	// 指定圖片名稱。如果圖片不在Bucket根目錄，需攜帶檔案完整路徑，例如exampledir/demo.docx。
	ossObjectName := "demo.docx"
	// 產生帶簽名的URL，並指定到期時間為3600s。（最長有效時間為32400秒）
	signedURL, err := bucket.SignURL(ossObjectName, oss.HTTPGet, 3600, oss.Process("doc/snapshot,target_jpg,source_docx,page_2"))
	if err != nil {
		HandleError(err)
	} else {
		fmt.Println(signedURL)
	}
}

Node.js

const OSS = require("ali-oss");

// 定義一個產生簽名 URL 的函數
async function generateSignatureUrl(fileName) {
  // 擷取簽名URL
  const client = await new OSS({
      // 從環境變數中擷取訪問憑證。運行本程式碼範例之前，請確保已設定環境變數OSS_ACCESS_KEY_ID和OSS_ACCESS_KEY_SECRET。
      accessKeyId: process.env.OSS_ACCESS_KEY_ID,
      accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET,
      bucket: 'examplebucket',
      // yourregion填寫Bucket所在地區。以華東1（杭州）為例，Region填寫為oss-cn-hangzhou。
      region: 'oss-cn-hangzhou',
      // 設定secure為true，使用HTTPS，避免產生的下載連結被瀏覽器攔截
      secure: true,
      authorizationV4: true
  });

  return await client.signatureUrlV4('GET', 3600, {
      headers: {}, // 請根據實際發送的要求標頭設定此處的要求標頭
      queries: {
        "x-oss-process": "doc/snapshot,target_jpg,source_docx,page_1" // 構建文檔快照處理指示,擷取文檔的第2頁快照。
    }
  }, fileName);
}
// 調用函數並傳入檔案名稱
generateSignatureUrl('yourFileName').then(url => {
  console.log('Generated Signature URL:', url);
}).catch(err => {
  console.error('Error generating signature URL:', err);
});

PHP

<?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\Credentials\EnvironmentVariableCredentialsProvider;
use OSS\OssClient;

// 從環境變數中擷取訪問憑證。運行本程式碼範例之前，請確保已設定環境變數OSS_ACCESS_KEY_ID和OSS_ACCESS_KEY_SECRET。
$provider = new EnvironmentVariableCredentialsProvider();
// yourEndpoint填寫Bucket所在地區對應的Endpoint。以華東1（杭州）為例，Endpoint填寫為https://oss-cn-hangzhou.aliyuncs.com。
$endpoint = "yourEndpoint";
// yourRegion填寫Bucket所在地區，以華東1（杭州）為例，填寫為cn-hangzhou。其它Region請按實際情況填寫。
$region = "yourRegion";
// 填寫Bucket名稱，例如examplebucket。
$bucket= "examplebucket";
// 填寫Object完整路徑，例如exampledir/demo.docx。Object完整路徑中不能包含Bucket名稱。
$object = "exampledir/demo.docx";

$config = array(
        "provider" => $provider,
        "endpoint" => $endpoint,
        "signatureVersion" => OssClient::OSS_SIGNATURE_VERSION_V4,
        "region"=> $region
    );
    $ossClient = new OssClient($config);

// 產生一個帶圖片處理參數的簽名的URL，有效期間是3600秒，可以直接使用瀏覽器訪問。
$timeout = 3600;

$options = array(
    // 構建文檔快照處理指示,擷取文檔的第2頁快照。。
    OssClient::OSS_PROCESS => "doc/snapshot,target_jpg,source_docx,page_1");

$signedUrl = $ossClient->signUrl($bucket, $object, $timeout, "GET", $options);
print("rtmp url: \n" . $signedUrl);

產生的簽名URL樣本如下：

https://examplebucket.oss-cn-hangzhou.aliyuncs.com/demo.docx?x-oss-process=doc%2Fsnapshot%2Ctarget_jpg%2Csource_docx%2Cpage_1&x-oss-date=20250225T023122Z&x-oss-expires=3600&x-oss-signature-version=OSS4-HMAC-SHA256&x-oss-credential=LTAI********************%2F20250225%2Fcn-hangzhou%2Foss%2Faliyun_v4_request&x-oss-signature=c6620caa4dc160e5a70ee96b5bae08464edf7a41bb6d47432eda65474f68f26a

複製產生的URL並粘貼到瀏覽器地址欄，即可擷取指定的文檔快照。

參數說明

操作名稱：doc/snapshot

具體參數如下表所示：

參數	類型	是否必須	描述
target	string	否	圖片目標格式。取值： png（預設） jpg
source	string	否	文檔源檔案格式，預設使用對象名尾碼。取值： pdf xlsx xls docx doc pptx ppt 說明如果該欄位未填寫，並且對象無尾碼，會返回錯誤。
page	int	否	文檔頁碼。預設首頁從1開始，最大2000。

許可權說明

阿里雲帳號預設擁有全部許可權。阿里雲帳號下的RAM使用者或RAM角色預設沒有任何許可權，需要阿里雲帳號或帳號管理員通過RAM Policy或Bucket Policy授予操作許可權。

API	Action	說明
GetObject	`oss:GetObject`	下載Object。
	`oss:GetObjectVersion`	下載Object時，如果通過versionId指定了Object的版本，則需要授予此操作的許可權。
	`kms:Decrypt`	下載Object時，如果Object的中繼資料套件含X-Oss-Server-Side-Encryption: KMS，則需要此操作的許可權。

API	Action	說明
無	`oss:ProcessImm`	通過OSS使用IMM進行資料處理的許可權。

API	Action	說明
CreateOfficeConversionTask	`imm:CreateOfficeConversionTask`	使用IMM進行文檔轉換或快照的許可權。

計費說明

WebOffice線上預覽會產生以下計費項目。有關計費項目的定價詳情，請參見OSS產品定價和計費項目：

API	計費項目	說明
GetObject	GET 類型請求	根據成功的請求次數計算請求費用。
	外網流出流量費用	如果是通過外網Endpoint（樣本值oss-cn-hangzhou.aliyuncs.com）或者傳輸加速Endpoint（樣本值oss-accelerate.aliyuncs.com）調用GetObject介面時，會產生外網流出流量費用，根據資料容量大小計費。
	低頻訪問資料取回容量	如果取回的資料是低頻訪問資料，會產生低頻訪問資料取回容量的費用，按資料取回量計費。
	歸檔直讀資料取回容量	如果讀取的是歸檔的Object且Bucket開啟了歸檔直讀，會產生歸檔直讀資料取回容量費用，根據取回的資料容量大小計費。
	傳輸加速	如果開啟了傳輸加速功能且使用傳輸加速網域名稱訪問您的Bucket會產生傳輸加速費用，根據資料容量大小計費。

API	計費項目	說明
CreateOfficeConversionTask	DocumentConvert	根據成功的請求次數計算請求費用。

Object Storage Service：文檔快照

使用情境

如何使用

前提條件

文檔快照

Java

Python

Go

Node.js

PHP

參數說明

相關API

擷取example.docx的首頁快照

處理方式

處理樣本

擷取word文檔example第2頁的jpg快照

處理方式

處理樣本

許可權說明

計費說明

注意事項

常見問題

文檔快照對來源文件大小限制是多少？