Apa itu snapshot dokumen - Object Storage Service - Alibaba Cloud Documentation Center

Fitur snapshot dokumen memungkinkan Anda menghasilkan snapshot halaman tertentu dari dokumen—seperti file Word, Excel, PPT, atau PDF—di cloud tanpa perlu mengunduh file tersebut. Fitur ini mendukung berbagai skenario, seperti penyematan di halaman web dan pencadangan data.

Skenario

Pencadangan dan pemulihan data: Anda dapat membuat snapshot dokumen secara berkala di bucket Object Storage Service (OSS) untuk tujuan pencadangan data.
Ekstraksi informasi penting: Gunakan snapshot dokumen untuk menangkap halaman tertentu guna mengekstraksi informasi penting dengan cepat.

Cara menggunakan fitur ini

Prasyarat

Di Object Storage Service (OSS), Anda harus membuat bucket, mengunggah dokumen yang akan diproses ke bucket tersebut, dan menyambungkan proyek Intelligent Media Management (IMM) ke bucket tersebut. Proyek IMM harus berada di wilayah yang sama dengan bucket.

Snapshot dokumen

Anda dapat menggunakan SDK untuk memanggil API snapshot dokumen guna memprosesnya.

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 {
        // Wilayah China (Hangzhou) digunakan sebagai contoh. Atur Endpoint sesuai wilayah aktual.
        String endpoint = "https://oss-cn-hangzhou.aliyuncs.com";
        // Dapatkan kredensial akses dari variabel lingkungan. Sebelum menjalankan kode contoh ini, pastikan variabel lingkungan OSS_ACCESS_KEY_ID dan OSS_ACCESS_KEY_SECRET telah disetel.
        EnvironmentVariableCredentialsProvider credentialsProvider = CredentialsProviderFactory.newEnvironmentVariableCredentialsProvider();
        // Tentukan nama bucket, misalnya examplebucket.
        String bucketName = "examplebucket";
        // Tentukan path lengkap objek. Jika dokumen tidak berada di direktori root bucket, Anda harus menyertakan path lengkapnya, misalnya exampledir/demo.docx.
        String objectName = "demo.docx";
        // Tentukan wilayah tempat bucket berada. Wilayah China (Hangzhou) digunakan sebagai contoh. Atur wilayah menjadi cn-hangzhou.
        String region = "cn-hangzhou";

        // Buat instance OSSClient.
        // Setelah instance OSSClient tidak lagi diperlukan, panggil metode shutdown untuk melepas sumber daya.
        ClientBuilderConfiguration clientBuilderConfiguration = new ClientBuilderConfiguration();
        clientBuilderConfiguration.setSignatureVersion(SignVersion.V4);
        OSS ossClient = OSSClientBuilder.create()
                .endpoint(endpoint)
                .credentialsProvider(credentialsProvider)
                .clientConfiguration(clientBuilderConfiguration)
                .region(region)
                .build();

        try {
            // Bangun instruksi pemrosesan snapshot dokumen untuk mendapatkan snapshot halaman kedua dokumen.
            String style = "doc/snapshot,target_jpg,source_docx,page_2";
            // Atur waktu kedaluwarsa URL yang ditandatangani menjadi 3.600 detik.
            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("Terjadi OSSException, artinya permintaan Anda sampai ke OSS, "
                    + "tetapi ditolak dengan tanggapan error karena suatu alasan.");
            System.out.println("Pesan Error:" + oe.getErrorMessage());
            System.out.println("Kode Error:" + oe.getErrorCode());
            System.out.println("ID Permintaan:" + oe.getRequestId());
            System.out.println("Host ID:" + oe.getHostId());
        } catch (ClientException ce) {
            System.out.println("Terjadi ClientException, artinya klien mengalami "
                    + "masalah internal serius saat mencoba berkomunikasi dengan OSS, "
                    + "misalnya tidak dapat mengakses jaringan.");
            System.out.println("Pesan Error:" + ce.getMessage());
        } finally {
            if (ossClient != null) {
                ossClient.shutdown();
            }
        }
    }
}

Python

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

# Dapatkan kredensial akses dari variabel lingkungan. Sebelum menjalankan kode contoh ini, pastikan variabel lingkungan OSS_ACCESS_KEY_ID dan OSS_ACCESS_KEY_SECRET telah disetel.
auth = oss2.ProviderAuthV4(EnvironmentVariableCredentialsProvider())

# Tentukan nama bucket.
bucket = 'examplebucket'

# Tentukan Endpoint untuk wilayah tempat bucket berada. Wilayah China (Hangzhou) digunakan sebagai contoh.
endpoint = 'https://oss-cn-hangzhou.aliyuncs.com'

# Tentukan ID wilayah Alibaba Cloud umum.
region = 'cn-hangzhou'
bucket = oss2.Bucket(auth, endpoint, bucket, region=region)

# Tentukan nama dokumen sumber. Jika dokumen tidak berada di direktori root bucket, Anda harus menyertakan path lengkapnya, misalnya exampledir/demo.docx.
key = 'demo.docx'

# Tentukan waktu kedaluwarsa dalam detik.
expire_time = 3600

# Bangun instruksi pemrosesan snapshot dokumen untuk mendapatkan snapshot halaman kedua dokumen.
process = 'doc/snapshot,target_jpg,source_docx,page_2 '

# Hasilkan URL yang ditandatangani dengan parameter pemrosesan gambar.
url = bucket.sign_url('GET', key, expire_time, params={'x-oss-process': process}, slash_safe=True)

# Cetak URL yang ditandatangani.
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() {
	// Dapatkan kredensial akses dari variabel lingkungan. Sebelum menjalankan kode contoh ini, pastikan variabel lingkungan OSS_ACCESS_KEY_ID dan OSS_ACCESS_KEY_SECRET telah disetel.
	provider, err := oss.NewEnvironmentVariableCredentialsProvider()
	if err != nil {
		fmt.Println("Error:", err)
		os.Exit(-1)
	}

	// Buat instance OSSClient.
	// Atur yourEndpoint ke Endpoint bucket. Wilayah China (Hangzhou) digunakan sebagai contoh. Atur Endpoint menjadi https://oss-cn-hangzhou.aliyuncs.com. Sesuaikan untuk wilayah lain jika diperlukan.
	// Atur yourRegion ke wilayah tempat bucket berada. Wilayah China (Hangzhou) digunakan sebagai contoh. Atur wilayah menjadi cn-hangzhou. Sesuaikan untuk wilayah lain jika diperlukan.
	clientOptions := []oss.ClientOption{oss.SetCredentialsProvider(&provider)}
	clientOptions = append(clientOptions, oss.Region("yourRegion"))
	// Atur versi signature.
	clientOptions = append(clientOptions, oss.AuthVersion(oss.AuthV4))
	client, err := oss.New("yourEndpoint", "", "", clientOptions...)
	if err != nil {
		HandleError(err)
	}

	// Tentukan nama bucket tempat dokumen disimpan, misalnya examplebucket.
	bucketName := "examplebucket"
	bucket, err := client.Bucket(bucketName)
	if err != nil {
		HandleError(err)
	}
	// Tentukan nama dokumen. Jika dokumen tidak berada di direktori root bucket, Anda harus menyertakan path lengkapnya, misalnya exampledir/demo.docx.
	ossObjectName := "demo.docx"
	// Hasilkan URL yang ditandatangani dan atur waktu kedaluwarsa menjadi 3.600 detik. (Periode validitas maksimum adalah 32.400 detik.)
	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");

// Definisikan fungsi untuk menghasilkan URL yang ditandatangani.
async function generateSignatureUrl(fileName) {
  // Dapatkan URL yang ditandatangani.
  const client = await new OSS({
      // Dapatkan kredensial akses dari variabel lingkungan. Sebelum menjalankan kode contoh ini, pastikan variabel lingkungan OSS_ACCESS_KEY_ID dan OSS_ACCESS_KEY_SECRET telah disetel.
      accessKeyId: process.env.OSS_ACCESS_KEY_ID,
      accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET,
      bucket: 'examplebucket',
      // Atur yourregion ke wilayah tempat bucket berada. Wilayah China (Hangzhou) digunakan sebagai contoh. Atur wilayah menjadi oss-cn-hangzhou.
      region: 'oss-cn-hangzhou',
      // Atur secure ke true untuk menggunakan HTTPS dan mencegah browser memblokir tautan unduhan yang dihasilkan.
      secure: true,
      authorizationV4: true
  });

  return await client.signatureUrlV4('GET', 3600, {
      headers: {}, // Atur header permintaan sesuai permintaan aktual yang Anda kirim.
      queries: {
        "x-oss-process": "doc/snapshot,target_jpg,source_docx,page_1" // Bangun instruksi pemrosesan snapshot dokumen untuk mendapatkan snapshot halaman pertama dokumen.
    }
  }, fileName);
}
// Panggil fungsi dan berikan nama file.
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;

// Dapatkan kredensial akses dari variabel lingkungan. Sebelum menjalankan kode contoh ini, pastikan variabel lingkungan OSS_ACCESS_KEY_ID dan OSS_ACCESS_KEY_SECRET telah disetel.
$provider = new EnvironmentVariableCredentialsProvider();
// Atur yourEndpoint ke Endpoint untuk wilayah tempat bucket berada. Wilayah China (Hangzhou) digunakan sebagai contoh. Atur Endpoint menjadi https://oss-cn-hangzhou.aliyuncs.com.
$endpoint = "yourEndpoint";
// Atur yourRegion ke wilayah tempat bucket berada. Wilayah China (Hangzhou) digunakan sebagai contoh. Atur wilayah menjadi cn-hangzhou. Sesuaikan untuk wilayah lain jika diperlukan.
$region = "yourRegion";
// Tentukan nama bucket, misalnya examplebucket.
$bucket= "examplebucket";
// Tentukan path lengkap objek, misalnya exampledir/demo.docx. Path lengkap objek tidak boleh mengandung nama bucket.
$object = "exampledir/demo.docx";

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

// Hasilkan URL yang ditandatangani dengan parameter pemrosesan gambar. URL ini berlaku selama 3.600 detik dan dapat diakses langsung di browser.
$timeout = 3600;

$options = array(
    // Bangun instruksi pemrosesan snapshot dokumen untuk mendapatkan snapshot halaman pertama dokumen.
    OssClient::OSS_PROCESS => "doc/snapshot,target_jpg,source_docx,page_1");

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

Berikut contoh URL yang ditandatangani yang dihasilkan:

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

Salin URL yang dihasilkan, lalu tempelkan ke bilah alamat browser Anda untuk melihat snapshot dokumen yang ditentukan.

Parameter

Aksi: doc/snapshot

Tabel berikut menjelaskan parameter-parameter tersebut.

Parameter	Tipe	Wajib	Deskripsi
target	string	Tidak	Format target gambar. Nilai yang valid: png (default) jpg
source	string	Tidak	Format file dokumen sumber. Secara default, ekstensi file dari nama objek digunakan. Nilai yang valid: pdf xlsx xls docx doc pptx ppt Catatan Jika Anda tidak menentukan parameter ini dan objek tidak memiliki ekstensi file, maka akan dikembalikan error.
page	int	Tidak	Nomor halaman dokumen. Nilai default adalah 1, yang menunjukkan halaman pertama. Nilai maksimum adalah 2000.

Operasi API terkait

Operasi di atas diimplementasikan melalui pemanggilan API. Jika program Anda memiliki kebutuhan kustomisasi tinggi, Anda dapat langsung mengirim permintaan REST API. Dalam hal ini, Anda perlu menulis kode secara manual untuk menghitung signature. Untuk informasi selengkapnya tentang cara menghitung header permintaan umum Authorization, lihat Signature Version 4 (direkomendasikan).

Dapatkan snapshot halaman pertama dari example.docx

Metode pemrosesan

Pemrosesan default

Contoh

// Dapatkan snapshot halaman pertama dari 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

Dapatkan snapshot JPG halaman kedua dari dokumen Word example

Metode pemrosesan

target: jpg
source: docx
page: 2

Contoh

// Dapatkan snapshot JPG halaman kedua dari dokumen Word example.
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

Izin

Akun Alibaba Cloud memiliki izin penuh secara default. Sebaliknya, pengguna Resource Access Management (RAM) atau peran RAM di bawah akun tersebut tidak memiliki izin apa pun secara default. Akun Alibaba Cloud atau administrator harus memberikan izin melalui kebijakan RAM atau kebijakan bucket.

API	Aksi	Deskripsi
GetObject	`oss:GetObject`	Mengunduh objek.
	`oss:GetObjectVersion`	Saat mengunduh objek, jika Anda menentukan versi objek melalui versionId, izin ini diperlukan.
	`kms:Decrypt`	Saat mengunduh objek, jika metadata objek berisi X-Oss-Server-Side-Encryption: KMS, izin ini diperlukan.

API	Aksi	Deskripsi
None	`oss:ProcessImm`	Mengizinkan penggunaan kemampuan pemrosesan data IMM di OSS.

API	Tindakan	Deskripsi
CreateOfficeConversionTask	`imm:CreateOfficeConversionTask`	Izin untuk menggunakan IMM dalam konversi dokumen atau pembuatan snapshot.

Penagihan

Snapshot dikenai biaya untuk item yang dapat ditagih berikut. Untuk informasi selengkapnya mengenai harga item yang dapat ditagih, lihat Harga OSS dan Item yang dapat ditagih:

API	Item yang dapat ditagih	Deskripsi
GetObject	Permintaan GET	Anda dikenai biaya permintaan berdasarkan jumlah permintaan yang berhasil.
	Lalu lintas keluar melalui Internet	Jika Anda memanggil operasi GetObject menggunakan titik akhir publik, seperti oss-cn-hangzhou.aliyuncs.com, atau titik akhir percepatan, seperti oss-accelerate.aliyuncs.com, Anda dikenai biaya lalu lintas keluar melalui Internet berdasarkan ukuran data.
	Pengambilan objek IA	Jika data IA diambil, Anda dikenai biaya pengambilan data IA berdasarkan ukuran data IA yang diambil.
	Pengambilan objek Archive di bucket yang diaktifkan akses real-time	Jika Anda mengambil objek Archive di bucket yang diaktifkan akses real-time, Anda dikenai biaya pengambilan data Archive berdasarkan ukuran objek Archive yang diambil.
	Biaya akselerasi transfer	Jika Anda mengaktifkan akselerasi transfer dan menggunakan titik akhir percepatan untuk mengakses bucket Anda, Anda dikenai biaya akselerasi transfer berdasarkan ukuran data.

API	Item yang dapat ditagih	Deskripsi
CreateOfficeConversionTask	DocumentConvert	Anda dikenai biaya permintaan berdasarkan jumlah permintaan yang berhasil.

Catatan

Snapshot dokumen hanya mendukung pemrosesan sinkron melalui metode x-oss-process.

FAQ

Berapa ukuran maksimum dokumen sumber untuk snapshot dokumen?

Ukuran maksimum dokumen sumber untuk snapshot dokumen adalah 20 MB.