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:
Um bucket do OSS. Consulte Crie um bucket.
O documento carregado no bucket. Consulte Carregar objetos.
Um projeto do Intelligent Media Management (IMM) vinculado ao bucket, na mesma região. Consulte Vincular um projeto IMM.
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 |
|
|
string |
Não |
|
Formato da imagem de saída. Valores válidos: |
|
|
string |
Não |
Extensão do nome do objeto |
Formato do documento de entrada. Valores válidos: |
|
|
int |
Não |
|
Número da página a capturar. Valor máximo: |
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 |
|
Baixe um objeto. |
|
GetObject |
|
Necessária ao especificar a versão do objeto via |
|
GetObject |
|
Necessária quando os metadados do objeto contêm |
|
— |
|
Usa recursos de processamento de dados do IMM no OSS. |
|
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.: |
|
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. |