Todos os produtos
Search
Central de documentação

Object Storage Service:Document snapshots

Última atualização: Jul 03, 2026

Gere um snapshot de uma página específica de um documento armazenado no OSS — como arquivos Word, Excel, PPT ou PDF — sem baixar o arquivo. Use os snapshots para incorporação em páginas web e backup de dados.

Casos de uso

  • Backup de dados: Capture snapshots periodicamente das principais páginas de documentos em seus buckets do OSS.

  • Extração de informações essenciais: Converta uma página específica em imagem para extrair ou exibir conteúdo rapidamente.

Limitações

  • Os snapshots de documentos usam apenas processamento síncrono (método x-oss-process).

  • Tamanho máximo do documento de origem: 20 MB.

  • Formatos de entrada compatíveis: pdf, xlsx, xls, docx, doc, pptx, ppt.

Pré-requisitos

Antes de começar, verifique se você tem:

Gerar um snapshot de documento

Gere uma URL assinada com o parâmetro x-oss-process para recuperar o snapshot de qualquer página. A URL permanece válida pelo período definido e pode ser aberta diretamente no navegador.

Todos os exemplos usam a ação doc/snapshot e geram uma URL assinada com expiração de 3.600 segundos. Substitua os valores de exemplo pelo nome real do seu bucket, nome do objeto e região.

Python

# -*- coding: utf-8 -*-
import oss2
from oss2.credentials import EnvironmentVariableCredentialsProvider

# Load credentials from environment variables OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET.
auth = oss2.ProviderAuthV4(EnvironmentVariableCredentialsProvider())

endpoint = 'https://oss-cn-hangzhou.aliyuncs.com'
region = 'cn-hangzhou'
bucket = oss2.Bucket(auth, endpoint, 'examplebucket', region=region)

# If the object is not in the root directory, include the full path, e.g., exampledir/demo.docx.
key = 'demo.docx'
expire_time = 3600

# Snapshot the second page of a .docx file and return it as a JPG.
process = 'doc/snapshot,target_jpg,source_docx,page_2'

url = bucket.sign_url('GET', key, expire_time, params={'x-oss-process': process}, slash_safe=True)
print(url)

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 {
        // Replace with the endpoint for your bucket region.
        String endpoint = "https://oss-cn-hangzhou.aliyuncs.com";
        // Load credentials from environment variables OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET.
        EnvironmentVariableCredentialsProvider credentialsProvider = CredentialsProviderFactory.newEnvironmentVariableCredentialsProvider();
        String bucketName = "examplebucket";
        // If the object is not in the root directory, include the full path, e.g., exampledir/demo.docx.
        String objectName = "demo.docx";
        String region = "cn-hangzhou";

        ClientBuilderConfiguration clientBuilderConfiguration = new ClientBuilderConfiguration();
        clientBuilderConfiguration.setSignatureVersion(SignVersion.V4);
        OSS ossClient = OSSClientBuilder.create()
                .endpoint(endpoint)
                .credentialsProvider(credentialsProvider)
                .clientConfiguration(clientBuilderConfiguration)
                .region(region)
                .build();

        try {
            // Snapshot the second page of a .docx file and return it as a JPG.
            String style = "doc/snapshot,target_jpg,source_docx,page_2";
            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("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("Error Message:" + ce.getMessage());
        } finally {
            if (ossClient != null) {
                ossClient.shutdown();
            }
        }
    }
}

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() {
    // Load credentials from environment variables OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET.
    provider, err := oss.NewEnvironmentVariableCredentialsProvider()
    if err != nil {
        HandleError(err)
    }

    clientOptions := []oss.ClientOption{oss.SetCredentialsProvider(&provider)}
    clientOptions = append(clientOptions, oss.Region("cn-hangzhou"))
    clientOptions = append(clientOptions, oss.AuthVersion(oss.AuthV4))
    client, err := oss.New("https://oss-cn-hangzhou.aliyuncs.com", "", "", clientOptions...)
    if err != nil {
        HandleError(err)
    }

    bucket, err := client.Bucket("examplebucket")
    if err != nil {
        HandleError(err)
    }

    // If the object is not in the root directory, include the full path, e.g., exampledir/demo.docx.
    ossObjectName := "demo.docx"

    // Snapshot the second page of a .docx file and return it as a JPG. Max validity: 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");

async function generateSignatureUrl(fileName) {
  const client = await new OSS({
      // Load credentials from environment variables OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET.
      accessKeyId: process.env.OSS_ACCESS_KEY_ID,
      accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET,
      bucket: 'examplebucket',
      // Replace oss-cn-hangzhou with the region where your bucket is located.
      region: 'oss-cn-hangzhou',
      secure: true,
      authorizationV4: true
  });

  return await client.signatureUrlV4('GET', 3600, {
      headers: {},
      queries: {
        // Snapshot the first page of a .docx file and return it as a JPG.
        "x-oss-process": "doc/snapshot,target_jpg,source_docx,page_1"
      }
  }, fileName);
}

generateSignatureUrl('demo.docx').then(url => {
  console.log('Generated signed URL:', url);
}).catch(err => {
  console.error('Error generating signed 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;

// Load credentials from environment variables OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET.
$provider = new EnvironmentVariableCredentialsProvider();
$endpoint = "https://oss-cn-hangzhou.aliyuncs.com";
$region = "cn-hangzhou";
$bucket = "examplebucket";
// If the object is not in the root directory, include the full path.
$object = "exampledir/demo.docx";

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

$timeout = 3600;
$options = array(
    // Snapshot the first page of a .docx file and return it as a JPG.
    OssClient::OSS_PROCESS => "doc/snapshot,target_jpg,source_docx,page_1"
);

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

A URL assinada gerada tem o seguinte formato:

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

Abra a URL no navegador para visualizar o snapshot.

Parâmetros

Ação: doc/snapshot

Parâmetro

Tipo

Obrigatório

Padrão

Descrição

target

string

Não

png

Formato da imagem de saída. Valores válidos: png, jpg.

source

string

Não

Extensão do nome do objeto

Formato do documento de entrada. Valores válidos: pdf, xlsx, xls, docx, doc, pptx, ppt. Se não especificado e o objeto não tiver extensão, o sistema retornará um erro.

page

int

Não

1

Número da página a capturar. Valor máximo: 2000.

Referência da API

Se sua aplicação tiver requisitos além do suporte do SDK, envie solicitações diretamente à REST API. Para calcular o cabeçalho Authorization, consulte Signature Version 4 (recomendado).

Obter um snapshot da primeira página (padrão)

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

Obter um snapshot JPG da segunda página de um documento Word

Parâmetros: target=jpg, source=docx, page=2

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

Permissões

Uma conta Alibaba Cloud tem permissões totais por padrão. Usuários e funções RAM não têm permissões por padrão. O proprietário da conta ou um administrador deve concedê-las usando uma política RAM ou uma política de bucket.

API

Ação

Descrição

GetObject

oss:GetObject

Baixe um objeto.

GetObject

oss:GetObjectVersion

Necessária ao especificar a versão do objeto via versionId.

GetObject

kms:Decrypt

Necessária quando os metadados do objeto contêm X-Oss-Server-Side-Encryption: KMS.

oss:ProcessImm

Usa recursos de processamento de dados do IMM no OSS.

CreateOfficeConversionTask

imm:CreateOfficeConversionTask

Usa o IMM para conversão de documentos ou snapshots.

Faturamento

Snapshots de documentos geram cobranças pelos itens abaixo. Para detalhes de preços, consulte Preços do OSS e Itens faturáveis do IMM.

API

Item faturável

Descrição

GetObject

Solicitações GET

Cobrança por solicitação bem-sucedida.

GetObject

Tráfego de saída pela internet

Cobrança ao usar um endpoint público (ex.: oss-cn-hangzhou.aliyuncs.com) ou de aceleração (ex.: oss-accelerate.aliyuncs.com).

GetObject

Recuperação de dados de Acesso Infrequente

Cobrança ao recuperar objetos de Acesso Infrequente (IA).

GetObject

Recuperação de dados de Arquivo

Cobrança ao recuperar objetos de Arquivo em um bucket com acesso em tempo real ativado.

GetObject

Aceleração de transferência

Cobrança quando a aceleração de transferência está ativada e se usa um endpoint de aceleração.

CreateOfficeConversionTask

DocumentConvert

Cobrança por solicitação bem-sucedida.