AI 助理
备案控制台
官方文档
输入文档关键字查找
首页 对象存储 操作指南 数据处理 文档处理 文档处理参数 文档快照

文档快照

更新时间：
产品详情
我的收藏

使用文档快照功能，您可以无需下载文档，直接在云端获取文档（Word/Excel/PPT/PDF）特定页的快照，支持网页嵌入、数据备份等多种场景。

使用场景

  • 数据备份与恢复：在业务系统日常运行过程中，定期创建OSS 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实例。
        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 );
            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。

相关API

以上操作方式底层基于API实现，如果您的程序自定义要求较高，您可以直接发起REST API请求。直接发起REST API请求需要手动编写代码计算签名。关于公共请求头Authorization的计算方法，请参见签名版本4（推荐）。

获取example.docx的首页快照

处理方式

默认处理

处理示例

// 获取example.docx的首页快照。
GET /exmaple.docx?x-oss-process=doc/snapshot HTTP/1.1
Host: doc-demo.oss-cn-hangzhou.aliyuncs.com
Date: Fri, 28 Oct 2022 06:40:10 GMT
Authorization: SignatureValue

获取word文档example第2页的jpg快照

处理方式

  • target: jpg

  • source: docx

  • page: 2

处理示例

// 获取word文档example第2页的jpg快照。
GET /exmaple?x-oss-process=doc/snapshot,target_jpg,source_docx,page_2 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

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

根据成功的请求次数计算请求费用。

注意事项

  • 文档快照仅支持同步处理（x-oss-process处理方式）。

常见问题

文档快照对源文档大小限制是多少？

文档快照对源文档大小限制是20M。

上一篇：文档格式转换下一篇：文档智能处理