What are document snapshots-Object Storage Service(OSS)-阿里云帮助中心

The document snapshot feature generates a snapshot of a specific page from a document, such as a Word, Excel, PPT, or PDF file, stored in OSS without downloading the entire file. This feature is useful for scenarios such as web page embedding and data backup.

Use cases

Data backup and recovery: Periodically create document snapshots in an OSS bucket for backup.
Key information extraction: Capture snapshots of specific pages to quickly extract and view key information.

How to use

Prerequisites

In OSS, create a bucket, upload the documents to be processed to the bucket, and bind an Intelligent Media Management (IMM) project to the bucket. The IMM project must be in the same region as the bucket.

Document snapshots

Use an SDK to call the document snapshot API.

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 {
        // This example uses the China (Hangzhou) region. Replace the endpoint with the one for your region.
        String endpoint = "https://oss-cn-hangzhou.aliyuncs.com";
        // Obtain credentials from environment variables. Ensure the OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables are set before running this example.
        EnvironmentVariableCredentialsProvider credentialsProvider = CredentialsProviderFactory.newEnvironmentVariableCredentialsProvider();
        // Specify the bucket name. Example: examplebucket.
        String bucketName = "examplebucket";
        // Specify the full path of the object. If the object is not in the root directory of the bucket, include the full path. Example: exampledir/demo.docx.
        String objectName = "demo.docx";
        // Specify the region where the bucket is located. This example uses cn-hangzhou for the China (Hangzhou) region.
        String region = "cn-hangzhou";

        // Create an OSSClient instance.
        // When the OSSClient instance is no longer needed, call the shutdown method to release its resources.
        ClientBuilderConfiguration clientBuilderConfiguration = new ClientBuilderConfiguration();
        clientBuilderConfiguration.setSignatureVersion(SignVersion.V4);
        OSS ossClient = OSSClientBuilder.create()
                .endpoint(endpoint)
                .credentialsProvider(credentialsProvider)
                .clientConfiguration(clientBuilderConfiguration)
                .region(region)
                .build();

        try {
            // Build the processing instruction to get a snapshot of the second page.
            String style = "doc/snapshot,target_jpg,source_docx,page_2";
            // Set the expiration time of the signed URL to 3,600 seconds.
            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

# Obtain credentials from environment variables. Before you run this example, make sure that the OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables are configured.
auth = oss2.ProviderAuthV4(EnvironmentVariableCredentialsProvider())

# Specify the bucket name.
bucket = 'examplebucket'

# Specify the endpoint of the region where the bucket is located. This example uses the China (Hangzhou) region.
endpoint = 'https://oss-cn-hangzhou.aliyuncs.com'

# Specify the Alibaba Cloud region ID.
region = 'cn-hangzhou'
bucket = oss2.Bucket(auth, endpoint, bucket, region=region)

# Specify the object name. If the object is not in the root directory of the bucket, include the full path of the object. Example: exampledir/demo.docx.
key = 'demo.docx'

# Specify the expiration time in seconds.
expire_time = 3600

# Build the processing instruction to get a snapshot of the second page.
process = 'doc/snapshot,target_jpg,source_docx,page_2 '

# Generate a signed URL that contains document processing parameters.
url = bucket.sign_url('GET', key, expire_time, params={'x-oss-process': process}, slash_safe=True)

# Print the signed 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() {
	// Obtain credentials from environment variables. Before you run this example, make sure that the OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables are configured.
	provider, err := oss.NewEnvironmentVariableCredentialsProvider()
	if err != nil {
		fmt.Println("Error:", err)
		os.Exit(-1)
	}

	// Create an OSSClient instance.
	// Set yourEndpoint to the endpoint for the bucket. This example uses https://oss-cn-hangzhou.aliyuncs.com for the China (Hangzhou) region. Set the endpoint based on your requirements.
	// Set yourRegion to the region where the bucket is located. This example uses cn-hangzhou for the China (Hangzhou) region. Set the region based on your requirements.
	clientOptions := []oss.ClientOption{oss.SetCredentialsProvider(&provider)}
	clientOptions = append(clientOptions, oss.Region("yourRegion"))
	// Set the signature version.
	clientOptions = append(clientOptions, oss.AuthVersion(oss.AuthV4))
	client, err := oss.New("yourEndpoint", "", "", clientOptions...)
	if err != nil {
		HandleError(err)
	}

	// Specify the name of the bucket where the file is stored. Example: examplebucket.
	bucketName := "examplebucket"
	bucket, err := client.Bucket(bucketName)
	if err != nil {
		HandleError(err)
	}
	// Specify the file name. If the file is not in the root directory of the bucket, include the full path of the file. Example: exampledir/demo.docx.
	ossObjectName := "demo.docx"
	// Generate a signed URL and set the expiration time to 3,600 seconds. The maximum validity period is 32,400 seconds.
	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");

// Define a function to generate a signed URL.
async function generateSignatureUrl(fileName) {
  // Obtain the signed URL.
  const client = await new OSS({
      // Obtain credentials from environment variables. Before you run this example, make sure that the OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables are configured.
      accessKeyId: process.env.OSS_ACCESS_KEY_ID,
      accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET,
      bucket: 'examplebucket',
      // Set the region where the bucket is located. This example uses oss-cn-hangzhou for the China (Hangzhou) region.
      region: 'oss-cn-hangzhou',
      // Set secure to true to use HTTPS. This prevents the browser from blocking the download link.
      secure: true,
      authorizationV4: true
  });

  return await client.signatureUrlV4('GET', 3600, {
      headers: {}, // Set the request headers based on your actual request.
      queries: {
        "x-oss-process": "doc/snapshot,target_jpg,source_docx,page_1" // Build the processing instruction to get a snapshot of the first page.
    }
  }, fileName);
}
// Call the function and pass the file name.
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;

// Obtain credentials from environment variables. Before you run this example, make sure that the OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables are configured.
$provider = new EnvironmentVariableCredentialsProvider();
// Set yourEndpoint to the endpoint for the region where the bucket is located. This example uses https://oss-cn-hangzhou.aliyuncs.com for the China (Hangzhou) region.
$endpoint = "yourEndpoint";
// Set yourRegion to the region where the bucket is located. This example uses cn-hangzhou for the China (Hangzhou) region. Set the region based on your requirements.
$region = "yourRegion";
// Specify the bucket name. Example: examplebucket.
$bucket= "examplebucket";
// Specify the full path of the object. Example: exampledir/demo.docx. The full path cannot contain the bucket name.
$object = "exampledir/demo.docx";

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

// Generate a signed URL that contains document processing parameters. The URL is valid for 3,600 seconds and can be accessed in a browser.
$timeout = 3600;

$options = array(
    // Build the processing instruction to get a snapshot of the first page.
    OssClient::OSS_PROCESS => "doc/snapshot,target_jpg,source_docx,page_1");

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

The following is an example of a generated signed 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

Copy the generated URL and paste it into the address bar of your browser to view the specified document snapshot.

Parameters

Action: doc/snapshot

The following table describes the parameters.

Parameter	Type	Required	Description
target	string	No	The output format of the snapshot. Valid values: png (default) jpg
source	string	No	The format of the source document. By default, OSS determines the format from the object's file extension. Valid values: pdf xlsx xls docx doc pptx ppt Note If this parameter is not specified and the object does not have a file extension, an error is returned.
page	int	No	The page number to capture. The default value is 1. The maximum value is 2000.

API reference

If the SDKs do not meet your requirements, you can make REST API requests directly. This requires you to manually calculate the signature. For information about how to calculate the Authorization header, see Signature Version 4 (recommended).

First-page snapshot of example.docx

Processing method

Default processing

Example

// Get a snapshot of the first page of example.docx.
GET /example.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

JPG snapshot of page 2

Processing method

target: jpg
source: docx
page: 2

Example

// Get a JPG snapshot of page 2 of the Word document example.
GET /example?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

Permissions

By default, an Alibaba Cloud account has full permissions. RAM users and RAM roles have no permissions by default. The account owner or an administrator must grant them permissions by using a RAM policy or a bucket policy.

API	Action	Description
GetObject	`oss:GetObject`	Downloads an object.
	`oss:GetObjectVersion`	When downloading an object, if you specify the object version through versionId, this permission is required.
	`kms:Decrypt`	When downloading an object, if the object metadata contains X-Oss-Server-Side-Encryption: KMS, this permission is required.

API	Action	Description
None	`oss:ProcessImm`	Allows the use of data processing capabilities of IMM in OSS.

API	Action	Description
CreateOfficeConversionTask	`imm:CreateOfficeConversionTask`	Permission to use IMM for document conversion or snapshots.

Billing

WebOffice online preview generates the following billable items. For pricing details, see OSS Product Pricing and Billable items:

API	Billable item	Description
GetObject	GET requests	You are charged request fees based on the number of successful requests.
	Outbound traffic over the Internet	If you call the GetObject operation by using a public endpoint, such as oss-cn-hangzhou.aliyuncs.com, or an acceleration endpoint, such as oss-accelerate.aliyuncs.com, you are charged fees for outbound traffic over the Internet based on the data size.
	Retrieval of IA objects	If IA objects are retrieved, you are charged IA data retrieval fees based on the size of the retrieved IA data.
	Retrieval of Archive objects in a bucket for which real-time access is enabled	If you retrieve Archive objects in a bucket for which real-time access is enabled, you are charged Archive data retrieval fees based on the size of retrieved Archive objects.
	Transfer acceleration fees	If you enable transfer acceleration and use an acceleration endpoint to access your bucket, you are charged transfer acceleration fees based on the data size.

API	Billable item	Description
CreateOfficeConversionTask	DocumentConvert	You are charged request fees based on the number of successful requests.

Usage notes

Document snapshot only supports synchronous processing (the x-oss-process method).

FAQ

Maximum source document size

The maximum source document size is 20 MB.